igny8/v2/V2-Execution-Docs/03D-toolkit-plugin.md

# IGNY8 Phase 3: Toolkit Plugin (03D)
## Utility Plugin — Performance, Forms, Security, SMTP, WooCommerce

**Document Version:** 1.0
**Date:** 2026-03-23
**Phase:** IGNY8 Phase 3 — WordPress Ecosystem
**Status:** Build Ready
**Source of Truth:** Codebase at `/data/app/igny8/`
**Audience:** Claude Code, WordPress Developers, Architects

---

## 1. CURRENT STATE

### No Toolkit Exists
- Users rely on multiple plugins for common utilities: WP Super Cache, Contact Form 7, Wordfence, WP Mail SMTP, etc.
- Each additional plugin adds overhead, potential conflicts, and security surface area
- No IGNY8-branded utility layer exists

### Relationship to IGNY8 Ecosystem
- **Independent** — toolkit works without the main IGNY8 plugin or companion theme
- **Complementary** — designed to pair with the companion theme (03C) for a complete site stack
- **Defers** — if both toolkit and main IGNY8 plugin are installed, toolkit's SMTP module defers to IGNY8's SMTP (03A Module 9b) to avoid conflict
- **Same module pattern** — uses identical `register()`, `activate()`, `deactivate()`, `is_active()`, `boot()` module architecture as 03A

### Plugin Identity
- **Plugin Name:** IGNY8 Toolkit
- **Text Domain:** `igny8-toolkit`
- **Option Prefix:** `igny8_toolkit_`
- **Table Prefix:** `{wp_prefix}igny8_toolkit_`
- **Min Requirements:** WordPress 5.9+, PHP 7.4+
- **License:** GPL v2+
- **Freemium Model:** Core features free, advanced features premium (detailed per module below)

---

## 2. WHAT TO BUILD

### Overview
A separate utility plugin with 5 infrastructure modules. Each module is independently toggleable and has zero performance impact when disabled. Follows the same module manager pattern as the main IGNY8 plugin (03A).

### Module 1: Performance

**Purpose:** Page caching, asset optimization, image optimization, and database cleanup.

**Classes:**
| Class | File | Purpose |
|-------|------|---------|
| `Toolkit_Performance_Module` | `modules/performance/class-performance-module.php` | Module bootstrap |
| `Toolkit_Page_Cache` | `modules/performance/class-page-cache.php` | File-based page cache |
| `Toolkit_Asset_Optimizer` | `modules/performance/class-asset-optimizer.php` | CSS/JS combine + minify |
| `Toolkit_Image_Optimizer` | `modules/performance/class-image-optimizer.php` | WebP conversion, lazy loading |
| `Toolkit_Critical_CSS` | `modules/performance/class-critical-css.php` | Above-fold CSS extraction |
| `Toolkit_HTML_Minifier` | `modules/performance/class-html-minifier.php` | Remove whitespace/comments |
| `Toolkit_Browser_Cache` | `modules/performance/class-browser-cache.php` | Expires + cache-control headers |
| `Toolkit_Preload` | `modules/performance/class-preload.php` | `<link rel="preload">` injection |
| `Toolkit_Database_Optimizer` | `modules/performance/class-database-optimizer.php` | Clean transients, revisions, spam |

**Features:**

| Feature | Tier | Description |
|---------|------|-------------|
| Page cache (basic) | Free | File-based cache, auto-purge on `save_post` |
| HTML minification | Free | Strip whitespace and comments from HTML output |
| Asset optimizer | Premium | Combine + minify CSS/JS with exclusion rules |
| Image optimizer | Premium | WebP conversion via GD/Imagick, lazy loading, responsive srcset |
| Critical CSS | Premium | Extract above-fold CSS for faster FCP |
| Browser cache headers | Premium | Expires + cache-control via `.htaccess` or `send_headers` |
| Preload/prefetch | Premium | `<link rel="preload">` for key resources |
| Gzip compression check | Free | Display gzip status in dashboard |
| Database optimizer | Premium | Clean transients, post revisions, spam comments, orphan meta |

**Database Table: `{prefix}igny8_toolkit_cache_stats`**
```sql
CREATE TABLE {prefix}igny8_toolkit_cache_stats (
  id              BIGINT AUTO_INCREMENT PRIMARY KEY,
  hits            INT DEFAULT 0,
  misses          INT DEFAULT 0,
  purges          INT DEFAULT 0,
  last_purge      DATETIME NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### Module 2: Forms

**Purpose:** Drag-and-drop form builder with submissions storage, email notifications, and anti-spam.

**Classes:**
| Class | File | Purpose |
|-------|------|---------|
| `Toolkit_Forms_Module` | `modules/forms/class-forms-module.php` | Module bootstrap |
| `Toolkit_Form_Builder` | `modules/forms/class-form-builder.php` | Admin form editor |
| `Toolkit_Form_Renderer` | `modules/forms/class-form-renderer.php` | Frontend rendering via shortcode/block |
| `Toolkit_Form_Processor` | `modules/forms/class-form-processor.php` | Submission handling |
| `Toolkit_Form_Notifications` | `modules/forms/class-form-notifications.php` | Email notifications |
| `Toolkit_Form_Entries` | `modules/forms/class-form-entries.php` | Submission viewer + export |
| `Toolkit_Form_AntiSpam` | `modules/forms/class-form-antispam.php` | Honeypot + token validation |

**Features:**

| Feature | Tier | Description |
|---------|------|-------------|
| Basic builder (5 field types) | Free | text, email, textarea, select, checkbox |
| Simple rendering | Free | Shortcode `[igny8_form id="X"]` |
| All field types | Premium | + radio, file upload, hidden, number, date |
| Conditional logic | Premium | Show/hide fields based on other field values |
| Multi-step forms | Premium | Step-by-step form wizard |
| Submissions dashboard | Premium | View, search, export CSV, delete entries |
| Email templates | Premium | Customizable notification templates |

**Anti-spam:** Honeypot field + basic token validation — no external service dependency.

**Embed:** Shortcode `[igny8_form id="X"]` + Gutenberg block for insertion.

**Database Table: `{prefix}igny8_toolkit_submissions`**
```sql
CREATE TABLE {prefix}igny8_toolkit_submissions (
  id              BIGINT AUTO_INCREMENT PRIMARY KEY,
  form_id         INT NOT NULL,
  data            LONGTEXT NOT NULL,
  ip_hash         VARCHAR(64) NULL,
  user_agent      VARCHAR(500) NULL,
  created_at      DATETIME NOT NULL,
  INDEX idx_form (form_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### Module 3: Security

**Purpose:** Login protection, basic firewall, WordPress hardening, and audit logging.

**Classes:**
| Class | File | Purpose |
|-------|------|---------|
| `Toolkit_Security_Module` | `modules/security/class-security-module.php` | Module bootstrap |
| `Toolkit_Login_Protection` | `modules/security/class-login-protection.php` | Brute-force protection |
| `Toolkit_Firewall` | `modules/security/class-firewall.php` | Bad user agent blocking, upload protection |
| `Toolkit_Hardening` | `modules/security/class-hardening.php` | XML-RPC disable, file editor, WP version |
| `Toolkit_Headers` | `modules/security/class-headers.php` | Security headers |
| `Toolkit_Audit_Log` | `modules/security/class-audit-log.php` | Event tracking |

**Features:**

| Feature | Tier | Description |
|---------|------|-------------|
| Login attempts limit | Free | Default 5 attempts, 15min lockout |
| File editor disable | Free | `DISALLOW_FILE_EDIT` constant |
| Security headers | Free | X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy |
| Hide WP version | Free | Remove generator meta tag |
| XML-RPC disable | Free | Block XML-RPC requests |
| Advanced firewall | Premium | Block bad user agents, PHP execution in uploads |
| 2FA via email code | Premium | Two-factor authentication on login |
| Full audit logging | Premium | Track logins, settings changes, plugin activations, role changes |
| IP allowlist/blocklist | Premium | Manage access by IP address |

**Database Table: `{prefix}igny8_toolkit_audit_log`**
```sql
CREATE TABLE {prefix}igny8_toolkit_audit_log (
  id              BIGINT AUTO_INCREMENT PRIMARY KEY,
  event_type      VARCHAR(50) NOT NULL,
  user_id         BIGINT NULL,
  object_type     VARCHAR(50) NULL,
  object_id       BIGINT NULL,
  details         LONGTEXT NULL,
  ip              VARCHAR(45) NULL,
  created_at      DATETIME NOT NULL,
  INDEX idx_event (event_type, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### Module 4: SMTP

**Purpose:** SMTP mail override for sites NOT using the main IGNY8 plugin. If both installed, this module defers to IGNY8's SMTP (03A Module 9b).

**Classes:**
| Class | File | Purpose |
|-------|------|---------|
| `Toolkit_SMTP_Module` | `modules/smtp/class-smtp-module.php` | Module bootstrap (checks for main plugin) |
| `Toolkit_SMTP_Mailer` | `modules/smtp/class-smtp-mailer.php` | SMTP mail override |
| `Toolkit_Email_Log` | `modules/smtp/class-email-log.php` | Delivery log with status |
| `Toolkit_Email_Test` | `modules/smtp/class-email-test.php` | Test email sender |

**Features:**

| Feature | Tier | Description |
|---------|------|-------------|
| SMTP override | Free | Host, port, username, password, encryption (SSL/TLS) |
| From name/email | Free | Override WordPress default sender |
| Mail sending | Free | Route all `wp_mail()` through SMTP |
| Email delivery log | Premium | Track sent/failed with error details |
| Email templates | Premium | Customizable notification email templates |
| Resend failed | Premium | Retry failed deliveries |

**Conflict Resolution:** On `boot()`, check `class_exists('IGNY8_SMTP_Module')` — if main plugin SMTP is active, this module auto-deactivates and shows admin notice: "SMTP is handled by the IGNY8 plugin."

**Database Table: `{prefix}igny8_toolkit_email_log`**
```sql
CREATE TABLE {prefix}igny8_toolkit_email_log (
  id              BIGINT AUTO_INCREMENT PRIMARY KEY,
  to_email        VARCHAR(320) NOT NULL,
  subject         VARCHAR(500) NOT NULL,
  status          VARCHAR(20) NOT NULL,
  error_message   TEXT NULL,
  sent_at         DATETIME NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### Module 5: WooCommerce Enhancements

**Purpose:** UX improvements for WooCommerce stores. Entirely premium — only available in paid version.

**Classes:**
| Class | File | Purpose |
|-------|------|---------|
| `Toolkit_WooCommerce_Module` | `modules/woocommerce/class-woocommerce-module.php` | Module bootstrap (requires WooCommerce) |
| `Toolkit_Quick_View` | `modules/woocommerce/class-quick-view.php` | Modal product preview on shop pages |
| `Toolkit_Wishlist` | `modules/woocommerce/class-wishlist.php` | Cookie-based (guest) + user meta (logged in) |
| `Toolkit_AJAX_Cart` | `modules/woocommerce/class-ajax-cart.php` | AJAX add-to-cart on archive pages |
| `Toolkit_Product_Filters` | `modules/woocommerce/class-product-filters.php` | Price/attribute/category AJAX filters |
| `Toolkit_Product_Gallery` | `modules/woocommerce/class-product-gallery.php` | Zoom, lightbox, thumbnails |

**Features (all Premium):**
- Quick view modal on shop/archive pages
- Wishlist (cookie-based for guests, user meta for logged-in)
- AJAX add-to-cart on archive pages (no page reload)
- Product filters (price range, attributes, categories) with AJAX
- Product gallery enhancement (zoom, lightbox, thumbnail navigation)

**Conditional Loading:** Module only loads when WooCommerce is active (`class_exists('WooCommerce')`).

---

## 3. DATA MODELS & APIS

### Database Tables (4 total)

All tables created on plugin activation by installer class:

| # | Table | Module | Purpose |
|---|-------|--------|---------|
| 1 | `{prefix}igny8_toolkit_submissions` | Forms | Form submission data (JSON) |
| 2 | `{prefix}igny8_toolkit_email_log` | SMTP | Email delivery tracking |
| 3 | `{prefix}igny8_toolkit_audit_log` | Security | Security event log |
| 4 | `{prefix}igny8_toolkit_cache_stats` | Performance | Cache hit/miss stats |

### Options Summary

All options use `igny8_toolkit_` prefix:

| Option Key | Module | Content |
|------------|--------|---------|
| `igny8_toolkit_performance_settings` | Performance | Cache, minify, optimize toggles |
| `igny8_toolkit_forms` | Forms | JSON: `[{id, name, fields, settings}]` |
| `igny8_toolkit_security_settings` | Security | Login limits, hardening toggles |
| `igny8_toolkit_smtp_settings` | SMTP | Host, port, user, pass, encryption |
| `igny8_toolkit_woocommerce_settings` | WooCommerce | Feature toggles |
| `igny8_toolkit_license_key` | Global | Premium license key |
| `igny8_toolkit_license_status` | Global | active/expired/invalid |

### No REST API Endpoints
The toolkit plugin does not expose REST endpoints. All admin pages are standard WordPress admin screens.

---

## 4. IMPLEMENTATION STEPS

### Plugin Architecture

```
igny8-toolkit/
├── igny8-toolkit.php                  # Plugin header, constants, module loader
├── readme.txt                         # WordPress.org readme
├── uninstall.php                      # Full cleanup on uninstall
├── includes/
│   ├── class-toolkit.php              # Main singleton class
│   ├── class-module-manager.php       # Module toggle (same pattern as 03A)
│   ├── class-installer.php            # Create 4 DB tables on activation
│   ├── class-license.php              # Premium license validation
│   ├── modules/
│   │   ├── performance/               # Module 1 — 9 class files
│   │   ├── forms/                     # Module 2 — 7 class files
│   │   ├── security/                  # Module 3 — 6 class files
│   │   ├── smtp/                      # Module 4 — 4 class files
│   │   └── woocommerce/               # Module 5 — 6 class files
│   └── admin/
│       ├── class-dashboard.php        # Toolkit dashboard
│       └── views/                     # Admin page templates
├── admin/                             # Admin CSS + JS
│   ├── css/
│   └── js/
├── frontend/                          # Frontend CSS + JS
│   ├── css/
│   └── js/
└── languages/
    └── igny8-toolkit.pot              # Translation template
```

### Build Sequence

**Phase 1: Foundation (Days 1-2)**
1. Create `igny8-toolkit.php` with header, constants, autoloader
2. Build `class-toolkit.php` singleton — `instance()`, `init()`, `load_modules()`
3. Build `class-module-manager.php` — same pattern as 03A
4. Build `class-installer.php` — create 4 DB tables via `dbDelta()`
5. Build `class-license.php` — premium license validation
6. Build `admin/class-dashboard.php` — toolkit overview page

**Phase 2: Performance Module (Days 3-5)**
1. Build page cache (file-based, purge on `save_post`)
2. Build HTML minifier (output buffer processing)
3. Build asset optimizer (combine/minify with exclusions)
4. Build image optimizer (WebP via GD/Imagick, lazy loading)
5. Build critical CSS generator
6. Build browser cache + preload
7. Build database optimizer

**Phase 3: Forms Module (Days 6-8)**
1. Build form builder admin UI
2. Build form renderer (shortcode + block)
3. Build form processor (validation + sanitization)
4. Build notifications (email on submission)
5. Build anti-spam (honeypot + token)
6. Build entries admin page (view + CSV export)

**Phase 4: Security Module (Days 9-11)**
1. Build login protection (attempt tracking, lockout)
2. Build firewall (bad user agents, upload protection)
3. Build hardening (XML-RPC, file editor, version hide, headers)
4. Build audit log (event tracking)
5. Build 2FA (premium — email code on login)

**Phase 5: SMTP Module (Days 12-13)**
1. Build SMTP mailer (override `wp_mail`)
2. Build conflict check (defer to main IGNY8 plugin if active)
3. Build email log
4. Build test email sender

**Phase 6: WooCommerce Module (Days 14-16)**
1. Build quick view modal
2. Build wishlist (cookie + user meta)
3. Build AJAX cart
4. Build product filters
5. Build gallery enhancements

**Phase 7: Compliance (Days 17-18)**
1. WordPress.org compliance — sanitize/escape, nonces, capability checks
2. i18n pass — all strings via `igny8-toolkit` text domain
3. readme.txt with feature list, changelog
4. Accessibility review

### Admin Menu Structure

```
IGNY8 Toolkit (top-level, dashicons-admin-tools)
├── Dashboard        — Overview, module status, cache stats
├── Performance      — Cache, minify, optimize, image settings
├── Forms            — Form builder, entries, settings
├── Security         — Login protection, hardening, audit log
├── SMTP             — Mail settings, log, test
├── WooCommerce      — Feature toggles (when WooCommerce active)
└── License          — Premium license management
```

---

## 5. ACCEPTANCE CRITERIA

### Performance (Module 1)
- [ ] Page cache creates static HTML files and serves them on repeat visits
- [ ] Cache auto-purges on `save_post` for the updated post's URL
- [ ] HTML minification reduces output size by removing whitespace/comments
- [ ] Image optimizer converts uploads to WebP format
- [ ] Lazy loading adds `loading="lazy"` to images below fold
- [ ] Database optimizer cleans transients, revisions, spam comments
- [ ] Cache stats table tracks hits/misses/purges

### Forms (Module 2)
- [ ] Form builder creates forms with configurable fields
- [ ] `[igny8_form id="X"]` shortcode renders form on frontend
- [ ] Form submissions stored in `igny8_toolkit_submissions` table
- [ ] Email notification sent on submission
- [ ] Honeypot field blocks spam submissions
- [ ] Entries admin page shows submissions with CSV export
- [ ] All form data sanitized: `sanitize_text_field()`, `sanitize_email()`, `wp_kses_post()` per field type

### Security (Module 3)
- [ ] Login attempts limited to 5 per 15 minutes (configurable)
- [ ] Lockout message displayed after threshold exceeded
- [ ] XML-RPC disabled when hardening active
- [ ] File editor disabled via `DISALLOW_FILE_EDIT`
- [ ] WP version removed from `<head>` and feeds
- [ ] Security headers set: X-Frame-Options, X-Content-Type-Options, Referrer-Policy
- [ ] Audit log records login attempts, settings changes, plugin activations

### SMTP (Module 4)
- [ ] SMTP override routes `wp_mail()` through configured server
- [ ] Test email sends successfully with configured SMTP
- [ ] Module auto-deactivates when main IGNY8 plugin SMTP is active
- [ ] Email log records sent/failed status with error messages

### WooCommerce (Module 5)
- [ ] Quick view modal opens on shop/archive pages
- [ ] Wishlist persists for guests (cookie) and users (user meta)
- [ ] AJAX add-to-cart works without page reload
- [ ] Product filters update results via AJAX
- [ ] Module only loads when WooCommerce is active

### Cross-Module
- [ ] All 5 modules independently toggleable — zero impact when disabled
- [ ] Plugin activates without errors on WordPress 5.9+ with PHP 7.4+
- [ ] All 4 database tables created on activation
- [ ] All strings translatable via `igny8-toolkit` text domain
- [ ] All inputs sanitized, all outputs escaped
- [ ] Nonce verification on all form submissions
- [ ] Premium features gated behind license validation

---

## 6. CLAUDE CODE INSTRUCTIONS

### Context Requirements
Before starting implementation:
1. Read 03A (main plugin) — understand module manager pattern to replicate
2. Read 03C (companion theme) — understand theme as primary consumer of toolkit features

### Execution Order
```
Foundation → Performance → Forms → Security → SMTP → WooCommerce → Compliance
```

### Critical Rules
1. **Independent plugin** — must work without main IGNY8 plugin or companion theme
2. **Same module pattern** — `register()`, `activate()`, `deactivate()`, `is_active()`, `boot()` — identical to 03A
3. **SMTP conflict resolution** — check `class_exists('IGNY8_SMTP_Module')` on boot, auto-defer if main plugin active
4. **WooCommerce conditional** — Module 5 only loads when `class_exists('WooCommerce')` is true
5. **Table prefix** — all tables use `{wp_prefix}igny8_toolkit_` (different from main plugin's `{wp_prefix}igny8_`)
6. **Option prefix** — all options use `igny8_toolkit_` prefix
7. **Text domain** — `igny8-toolkit` (different from plugin's `igny8` and theme's `igny8-theme`)
8. **Freemium** — free features work without license, premium features check `class-license.php` validation
9. **Sanitize/escape** — same WordPress standards as 03A
10. **No external dependencies** — no CDN scripts, no external API calls (except SMTP + optional license check)

### File Creation Order
```
1. igny8-toolkit.php (plugin header + bootstrap)
2. includes/class-toolkit.php (singleton)
3. includes/class-module-manager.php (module orchestration)
4. includes/class-installer.php (4 DB tables)
5. includes/class-license.php (premium validation)
6. includes/admin/class-dashboard.php (overview page)
7. includes/modules/performance/* (9 files)
8. includes/modules/forms/* (7 files)
9. includes/modules/security/* (6 files)
10. includes/modules/smtp/* (4 files)
11. includes/modules/woocommerce/* (6 files)
12. admin/ (CSS + JS assets)
13. frontend/ (CSS + JS assets)
14. uninstall.php (cleanup)
15. languages/igny8-toolkit.pot (i18n)
```

### Cross-References

| Doc | Relationship |
|-----|-------------|
| 03A WP Plugin Standalone | Module manager pattern replicated; SMTP conflict resolution when both installed |
| 03C Companion Theme | Theme is primary consumer of toolkit features (forms, performance) |