821 lines
42 KiB
Markdown
821 lines
42 KiB
Markdown
# Doc C — WordPress Ecosystem: Development Guide for Claude Code
|
|
|
|
**Version:** 1.0
|
|
**Date:** March 2026
|
|
**For:** Claude Code (Opus 4.6) in VSCode
|
|
**Purpose:** Step-by-step implementation guide for the IGNY8 WordPress Plugin (free + connected), Companion Theme, and Toolkit Plugin — where every file goes, what it does, build sequence, and how it connects to the IGNY8 SaaS platform
|
|
**Scope:** Plugin (14 modules, 10 build phases), Theme (7 CPTs, 9 taxonomies, 15 landing sections, 50+ block patterns, 5 starters, WooCommerce), Toolkit Plugin (5 modules)
|
|
**Rule:** Plugin works with ANY theme. Theme works WITHOUT the plugin. Both work WITHOUT the IGNY8 SaaS platform. Connected mode enhances both but is never required.
|
|
**Dependency:** Doc A (SAG Architecture) defines the blueprint/cluster data the plugin receives in connected mode. Doc B (Platform Modules) defines the IGNY8 SaaS features that push content/schemas/links to the plugin.
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Architecture Overview — Three Deliverables](#1-architecture-overview)
|
|
2. [Build Sequence — What Comes First](#2-build-sequence)
|
|
3. [IGNY8 Plugin — Foundation & Infrastructure](#3-plugin-foundation)
|
|
4. [IGNY8 Plugin — Module 1: SEO Core](#4-seo-core)
|
|
5. [IGNY8 Plugin — Module 2: Schema](#5-schema)
|
|
6. [IGNY8 Plugin — Module 3: Sitemap](#6-sitemap)
|
|
7. [IGNY8 Plugin — Module 4: Redirects](#7-redirects)
|
|
8. [IGNY8 Plugin — Module 5: Site Intelligence](#8-site-intelligence)
|
|
9. [IGNY8 Plugin — Module 6: Internal Linking](#9-internal-linking)
|
|
10. [IGNY8 Plugin — Module 7: GSC](#10-gsc)
|
|
11. [IGNY8 Plugin — Module 8: Socializer](#11-socializer)
|
|
12. [IGNY8 Plugin — Module 9: Analytics + SMTP](#12-analytics-smtp)
|
|
13. [IGNY8 Plugin — Module 10: Content Sync (Connected)](#13-content-sync)
|
|
14. [IGNY8 Plugin — Module 11: SAG Structure (Connected)](#14-sag-structure)
|
|
15. [IGNY8 Plugin — Setup Wizard & Import](#15-setup-wizard)
|
|
16. [IGNY8 Plugin — Data Architecture](#16-data-architecture)
|
|
17. [IGNY8 Plugin — REST API Endpoints](#17-rest-api)
|
|
18. [IGNY8 Plugin — Performance Rules](#18-performance)
|
|
19. [Theme — CPTs, Taxonomies, Meta Fields](#19-theme-structure)
|
|
20. [Theme — Term Landing Pages & SAG Templates](#20-term-templates)
|
|
21. [Theme — Landing Page Builder](#21-landing-pages)
|
|
22. [Theme — Block Patterns & Starter Templates](#22-patterns-starters)
|
|
23. [Theme — Interlinking Display Components](#23-interlinking-display)
|
|
24. [Theme — WooCommerce Integration](#24-woocommerce)
|
|
25. [Theme — Design System & Build Plan](#25-design-build)
|
|
26. [Toolkit Plugin — All 5 Modules](#26-toolkit)
|
|
27. [Free vs Premium Split](#27-free-premium)
|
|
28. [Theme ↔ Plugin Contract](#28-theme-plugin-contract)
|
|
29. [Plugin ↔ IGNY8 SaaS Communication](#29-saas-communication)
|
|
|
|
---
|
|
|
|
## 1. Architecture Overview — Three Deliverables {#1-architecture-overview}
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────┐
|
|
│ IGNY8 PLUGIN │
|
|
│ SEO Core, Schema, Sitemap, Redirects, Analytics, GSC, │
|
|
│ Site Intelligence, Internal Linking, Socializer, SMTP │
|
|
│ + Connected: Content Sync, SAG Structure │
|
|
│ │
|
|
│ Distribution: Free on WordPress.org │
|
|
│ Connected premium features via IGNY8 SaaS subscription │
|
|
│ Works with ANY theme │
|
|
└──────────────────────┬─────────────────────────────────────┘
|
|
│ reads plugin data via igny8() API
|
|
┌──────────────────────┴─────────────────────────────────────┐
|
|
│ COMPANION THEME │
|
|
│ 7 CPTs, 9 custom taxonomies, meta fields, SAG templates, │
|
|
│ term landing pages, landing page builder, 50+ patterns, │
|
|
│ 5 site-type starters, WooCommerce templates, design system │
|
|
│ │
|
|
│ Distribution: Free on WordPress.org (limited), Premium │
|
|
│ Works WITHOUT the plugin (graceful degradation) │
|
|
└──────────────────────┬─────────────────────────────────────┘
|
|
│ extends theme with infrastructure
|
|
┌──────────────────────┴─────────────────────────────────────┐
|
|
│ TOOLKIT PLUGIN │
|
|
│ Performance/Caching, Forms, Security, SMTP, WooCommerce │
|
|
│ │
|
|
│ Distribution: Free on WordPress.org (limited), Premium │
|
|
│ Works with ANY theme │
|
|
└────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
**Key principle:** Each piece works independently. Together they create the full SAG-optimized WordPress experience.
|
|
|
|
---
|
|
|
|
## 2. Build Sequence — What Comes First {#2-build-sequence}
|
|
|
|
```
|
|
PHASE 1 (Days 1-3) ─── Plugin Foundation
|
|
│ Skeleton, module manager, admin menu, REST API base,
|
|
│ setup wizard, database installer, compatibility layer
|
|
|
|
PHASE 2 (Days 4-7) ─── SEO Core Module
|
|
│ Meta box, title tags, meta description, content analysis,
|
|
│ OG tags, breadcrumbs, robots.txt, verification codes
|
|
|
|
PHASE 3 (Days 8-10) ─── Schema + Sitemap + Redirects
|
|
│ JSON-LD schemas, XML sitemap, redirect manager, 404 monitor
|
|
|
|
PHASE 4 (Days 11-13) ── Site Intelligence
|
|
│ Site audit, orphan detection, thin content, cannibalization,
|
|
│ cluster detection, intelligence dashboard
|
|
|
|
PHASE 5 (Days 14-15) ── Internal Linking
|
|
│ Link crawl, link audit, suggestions, link graph
|
|
|
|
PHASE 6 (Days 16-18) ── Socializer + Analytics + SMTP
|
|
│ Share buttons, social profiles, GA/GTM connector,
|
|
│ pixel manager, SMTP override, GSC OAuth + dashboard
|
|
|
|
PHASE 7 (Days 19-20) ── SEO Import
|
|
│ Yoast, RankMath, AIOSEO importers
|
|
|
|
PHASE 8 (Days 21-23) ── Connected Mode — Content Sync
|
|
│ API client, content puller, mapper, sync queue, scheduler
|
|
|
|
PHASE 9 (Days 24-27) ── Connected Mode — SAG Structure
|
|
│ Blueprint sync, taxonomy builder, term builder,
|
|
│ cluster manager, structure visualizer
|
|
|
|
PHASE 10 (Days 28-30) ─ Polish + Package
|
|
Cross-module testing, performance audit, WP.org compliance
|
|
|
|
--- THEME BUILD (30 days, can overlap with plugin Phases 6+) ---
|
|
|
|
THEME PHASE 1 (Days 1-3) Foundation (templates, design system, CSS)
|
|
THEME PHASE 2 (Days 4-6) CPTs + Taxonomies + Meta Boxes
|
|
THEME PHASE 3 (Days 7-9) Term Landing Page Templates
|
|
THEME PHASE 4 (Days 10-11) Interlinking Display Components
|
|
THEME PHASE 5 (Days 12-14) Landing Page Builder
|
|
THEME PHASE 6 (Days 15-16) Single Templates (service, portfolio, docs)
|
|
THEME PHASE 7 (Days 17-19) Custom Blocks + 50+ Patterns
|
|
THEME PHASE 8 (Days 20-22) Site-Type Starters + WooCommerce
|
|
THEME PHASE 9 (Days 23-27) Toolkit Plugin (all 5 modules)
|
|
THEME PHASE 10 (Days 28-30) Setup Wizard + Polish
|
|
|
|
--- THEME CAN START after Plugin Phase 5 (interlinking data contract defined) ---
|
|
```
|
|
|
|
---
|
|
|
|
## 3. IGNY8 Plugin — Foundation & Infrastructure {#3-plugin-foundation}
|
|
|
|
### 3.1 Complete File Structure
|
|
|
|
```
|
|
igny8/
|
|
├── igny8.php # Plugin header, bootstrap, constants
|
|
├── readme.txt # WordPress.org readme
|
|
├── uninstall.php # Full cleanup on uninstall
|
|
│
|
|
├── includes/
|
|
│ ├── class-igny8.php # Main singleton class
|
|
│ ├── class-module-manager.php # Register, activate, deactivate modules
|
|
│ ├── class-api-client.php # IGNY8 SaaS API client (connected mode)
|
|
│ ├── class-connection.php # API key validation, connection status
|
|
│ ├── class-utils.php # Shared utilities
|
|
│ ├── class-ajax.php # Shared AJAX handler
|
|
│ ├── class-rest-api.php # Plugin REST endpoints (for theme + external)
|
|
│ ├── class-compatibility.php # Detect conflicting plugins, show notices
|
|
│ │
|
|
│ ├── modules/ # 14 modules (see sections 4-14)
|
|
│ │ ├── seo/ # SEO Core (Phase 2)
|
|
│ │ ├── schema/ # Schema (Phase 3)
|
|
│ │ ├── sitemap/ # Sitemap (Phase 3)
|
|
│ │ ├── redirects/ # Redirects (Phase 3)
|
|
│ │ ├── analytics/ # Analytics (Phase 6)
|
|
│ │ ├── site-intelligence/ # Site Intelligence (Phase 4)
|
|
│ │ ├── linking/ # Internal Linking (Phase 5)
|
|
│ │ ├── gsc/ # Google Search Console (Phase 6)
|
|
│ │ ├── socializer/ # Social sharing + posting (Phase 6)
|
|
│ │ ├── smtp/ # Email delivery (Phase 6)
|
|
│ │ ├── content-sync/ # [Connected] Content from IGNY8 (Phase 8)
|
|
│ │ └── sag/ # [Connected] SAG structure (Phase 9)
|
|
│ │
|
|
│ ├── admin/ # Admin UI infrastructure
|
|
│ │ ├── class-admin-menu.php # Menu registration (top-level "IGNY8" menu)
|
|
│ │ ├── class-dashboard.php # Main plugin dashboard page
|
|
│ │ ├── class-setup-wizard.php # First-run wizard (6 steps)
|
|
│ │ ├── class-compatibility-notice.php # Admin notices for conflicts
|
|
│ │ ├── views/ # PHP templates for admin pages
|
|
│ │ │ ├── dashboard.php
|
|
│ │ │ ├── wizard/step-1 through step-6.php
|
|
│ │ │ └── connect-prompt.php
|
|
│ │ └── assets/
|
|
│ │ ├── admin.css, admin.js
|
|
│ │ └── meta-box.css, meta-box.js
|
|
│ │
|
|
│ ├── frontend/
|
|
│ │ ├── class-head-output.php # ALL <head> output (meta, schema, OG) in single hook
|
|
│ │ ├── class-share-output.php # Share button HTML/CSS/JS (conditional)
|
|
│ │ └── assets/
|
|
│ │ ├── share-buttons.css # <3KB, loaded only if share enabled
|
|
│ │ └── share-buttons.js # <2KB, loaded only if share enabled
|
|
│ │
|
|
│ ├── data/
|
|
│ │ ├── class-installer.php # Create all custom DB tables on activation
|
|
│ │ ├── class-migrator.php # Version-based migration handler
|
|
│ │ └── class-importer.php # Import from Yoast/RankMath/AIOSEO
|
|
│ │
|
|
│ └── integrations/
|
|
│ ├── class-woocommerce.php # WooCommerce-specific SEO/schema
|
|
│ └── class-theme-bridge.php # Data passing to companion theme
|
|
│
|
|
└── languages/
|
|
└── igny8.pot # Translation template
|
|
```
|
|
|
|
### 3.2 Module Manager Pattern
|
|
|
|
Every module follows the same lifecycle:
|
|
|
|
```php
|
|
// class-module-manager.php pattern
|
|
|
|
class ModuleManager {
|
|
private $modules = [];
|
|
|
|
public function register($slug, $class, $options = []) {
|
|
// Register module with slug, class path, free/connected flag
|
|
}
|
|
|
|
public function activate($slug) {
|
|
// Enable module, call module's activate() method
|
|
}
|
|
|
|
public function deactivate($slug) {
|
|
// Disable module, call module's deactivate() method
|
|
}
|
|
|
|
public function is_active($slug) {
|
|
// Check igny8_active_modules option
|
|
}
|
|
|
|
public function boot_active_modules() {
|
|
// Called on plugins_loaded — instantiate all active modules
|
|
}
|
|
}
|
|
|
|
// Each module extends:
|
|
abstract class IGNY8_Module {
|
|
abstract public function get_slug();
|
|
abstract public function get_name();
|
|
abstract public function init(); // Hook registration
|
|
public function activate() {} // On module enable
|
|
public function deactivate() {} // On module disable
|
|
public function is_connected_only() { return false; }
|
|
}
|
|
```
|
|
|
|
### 3.3 Admin Menu Structure
|
|
|
|
```
|
|
IGNY8 (top-level menu, dashicons-chart-area)
|
|
├── Dashboard # Plugin overview + connect prompt
|
|
├── SEO # SEO settings page
|
|
├── Schema # Schema settings
|
|
├── Sitemaps # Sitemap configuration
|
|
├── Redirects # Redirect manager + 404 log
|
|
├── Site Intelligence # Audit dashboard
|
|
├── Internal Links # Link audit + suggestions
|
|
├── Search Console # GSC connection + metrics
|
|
├── Socializer # Share buttons + accounts
|
|
├── Analytics # GA/GTM/pixel settings
|
|
├── SMTP # Mail settings
|
|
├── Settings # Global plugin settings
|
|
│
|
|
└── (Connected only, appear after connection):
|
|
├── Content Sync # Sync dashboard
|
|
└── SAG Structure # Blueprint + structure visualizer
|
|
```
|
|
|
|
### 3.4 Public API Class
|
|
|
|
The plugin exposes a global function for themes and other plugins:
|
|
|
|
```php
|
|
function igny8() {
|
|
return IGNY8::instance();
|
|
}
|
|
|
|
// Usage by theme:
|
|
if (function_exists('igny8')) {
|
|
$title = igny8()->seo->get_title($post_id);
|
|
$schema = igny8()->schema->get_json_ld($post_id);
|
|
$breadcrumbs = igny8()->seo->get_breadcrumbs();
|
|
$related = igny8()->linking->get_related_links($post_id);
|
|
$cluster_nav = igny8()->linking->get_cluster_navigation($post_id);
|
|
$term_content = igny8()->seo->get_term_content($term_id);
|
|
$share = igny8()->socializer->render_share_buttons($post_id);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4-12. Plugin Modules — Build Reference {#4-seo-core}
|
|
|
|
Each module section below specifies: files to create, what each file does, which hooks it uses, what data it reads/writes, and how it connects to the IGNY8 SaaS platform in connected mode.
|
|
|
|
### Module 1: SEO Core (Phase 2, Days 4-7)
|
|
|
|
**Files:** `modules/seo/` — 9 PHP files + 2 view templates (see file structure above)
|
|
|
|
**What it does:**
|
|
- `class-meta-box.php` — Adds SEO meta box below editor on all post types. Fields: focus keyword, SEO title (with SERP preview), meta description (with character counter), canonical URL, robots index/follow toggles. Saves to `_igny8_*` post meta keys. Connected enhancement: multi-keyword fields, cluster-aware scoring.
|
|
- `class-title-tag.php` — Manages `<title>` tag output. Template system: `{site_title} {separator} {page_title}`. Customizable per post type. Filters: `igny8_title_parts`, `igny8_title_separator`.
|
|
- `class-meta-tags.php` — Outputs `<meta name="description">`, `<meta name="robots">`, `<link rel="canonical">` in `<head>`. Single `wp_head` hook at priority 1.
|
|
- `class-content-analysis.php` — Real-time JavaScript analysis in editor: keyword density, heading check (H1 count, H2 usage), readability score (Flesch), internal link count, image alt text check, meta length check. Outputs score 0-100 stored in `_igny8_seo_score`.
|
|
- `class-breadcrumbs.php` — Generates breadcrumb HTML. Shortcode `[igny8_breadcrumbs]`. Also outputs BreadcrumbList schema. SAG-aware: when connected, breadcrumbs follow dimensional path (Home → Attribute → Term → Post).
|
|
- `class-opengraph.php` — OG title, description, image, type, URL. Twitter Card meta. Per-post overrides via meta box.
|
|
- `class-robots-txt.php` — Virtual robots.txt manager. Adds sitemap URL, custom rules.
|
|
- `class-verification.php` — Google, Bing, Pinterest, Yandex verification meta tags.
|
|
|
|
**WP Hooks used:** `wp_head` (priority 1), `add_meta_boxes`, `save_post`, `wp_title`, `document_title_parts`, `the_content` (for breadcrumb auto-insertion option).
|
|
|
|
### Module 2: Schema (Phase 3, Days 8-9)
|
|
|
|
**Files:** `modules/schema/` — 12 PHP files
|
|
|
|
**What it does:** Generates JSON-LD for all schema types and outputs as a single `<script type="application/ld+json">` block in `wp_head`. Schema types: Article/BlogPosting, Organization/Person, WebPage/CollectionPage, BreadcrumbList, FAQPage, HowTo, LocalBusiness, Service, Product (WooCommerce), WebSite+SearchAction, custom field for advanced users.
|
|
|
|
**Schema selection logic:** Content type → schema type mapping. Blog posts get Article. Service CPT gets Service. Products get Product. FAQ CPT gets FAQPage. Hub pages get WebPage. Users can override via `_igny8_schema_type` meta.
|
|
|
|
**Connected enhancement:** IGNY8 SaaS pushes pre-generated schemas (FAQ pairs, HowTo steps, Pros/Cons) via bulk endpoint. Plugin stores in post meta and renders alongside auto-generated schemas.
|
|
|
|
### Module 3: Sitemap (Phase 3, Day 9)
|
|
|
|
**Files:** `modules/sitemap/` — 5 PHP files
|
|
|
|
**What it does:** XML sitemap index at `/sitemap_index.xml`. Sub-sitemaps per post type, per taxonomy, image sitemap. XSL stylesheet for browser viewing. Respects noindex settings. Includes `<lastmod>`, `<image:image>`. WooCommerce: includes price, availability in product sitemap entries.
|
|
|
|
### Module 4: Redirects (Phase 3, Day 10)
|
|
|
|
**Files:** `modules/redirects/` — 4 PHP files + 1 view
|
|
|
|
**What it does:** CRUD for 301/302/307 redirects in custom DB table. 404 monitoring with hit count. Auto-redirect when post slug changes. CSV import/export. Admin page with sortable/filterable table.
|
|
|
|
### Module 5: Site Intelligence (Phase 4, Days 11-13)
|
|
|
|
**Files:** `modules/site-intelligence/` — 10 PHP files + 2 views
|
|
|
|
**What it does (Free):** Site audit runner (WP Cron scheduled, weekly). Orphan page detection (pages with 0 internal links pointing to them). Thin content scanner (below word count threshold, configurable). Empty taxonomy terms. Duplicate title/meta detection. Keyword cannibalization (multiple pages targeting same keyword). Basic cluster detection (auto-group content by topic similarity).
|
|
|
|
**What it does (Connected):** Full SAG gap analysis: missing clusters, missing term pages, missing attribute values. Cluster health scores: content coverage, link density per cluster. Architecture blueprint showing recommended new pages. Priority queue: which gaps to fill first. Topical authority scoring per cluster.
|
|
|
|
**Dashboard:** Admin page showing audit results. Severity color coding (critical/warning/info). Per-issue action buttons. Re-run audit button. Connected: SAG gap analysis section with "Connect to IGNY8 to fix these gaps" CTA.
|
|
|
|
### Module 6: Internal Linking (Phase 5, Days 14-15)
|
|
|
|
**Files:** `modules/linking/` — 7 PHP files + 2 views
|
|
|
|
**What it does (Free):** Link crawl: scans all content, builds `{prefix}igny8_link_map` table. Link audit page: per-post inbound/outbound link counts, broken links, orphan pages. Link suggestions: "This post could link to these 5 related posts" based on shared categories/tags/keywords. Link equity distribution overview.
|
|
|
|
**What it does (Connected):** SAG-aware automatic link suggestions based on cluster relationships (data from Doc A Linker module). Bulk link insertion tool. Link template rules (keyword → URL mapping). Contextual link placement (AI-determined anchor text and position). Link priority scoring based on cluster importance.
|
|
|
|
### Module 7: GSC (Phase 6, Day 18)
|
|
|
|
**Files:** `modules/gsc/` — 6 PHP files + 2 views
|
|
|
|
**What it does (Free):** Google OAuth connection. Search performance dashboard: clicks, impressions, CTR, position. Keyword position tracking. Date range filtering.
|
|
|
|
**What it does (Connected):** URL Inspection API: inspect any URL's index status. Auto-indexing: content published via IGNY8 gets auto-inspected and index-requested (driven by IGNY8 SaaS, plugin receives status updates). Status display: index status column in content list, metabox on edit screen.
|
|
|
|
### Module 8: Socializer (Phase 6, Days 16-17)
|
|
|
|
**Files:** `modules/socializer/` — 8 PHP files + 2 views
|
|
|
|
**What it does (Free):** Pure CSS/JS share buttons (zero external dependencies, <5KB total). Position options: floating, above/below content, inline. Networks: Facebook, X, LinkedIn, Pinterest, WhatsApp, Telegram, Email, Copy Link. Social profile links management (site-wide, used in schema).
|
|
|
|
**What it does (Connected):** Auto-post to social platforms on WordPress publish (content adapted by IGNY8 SaaS Socializer module). Per-platform message templates. Scheduling. Platform API connections: X, Facebook Pages, LinkedIn, Instagram. Dynamic OG image generation. Social post performance tracking.
|
|
|
|
### Module 9: Analytics + SMTP (Phase 6, Days 17-18)
|
|
|
|
**Analytics files:** `modules/analytics/` — 4 PHP files
|
|
**SMTP files:** `modules/smtp/` — 3 PHP files
|
|
|
|
**Analytics:** GA4 connector (tracking code injection), GTM connector, Facebook/TikTok/Pinterest pixel manager, custom header/footer scripts manager.
|
|
|
|
**SMTP:** Override `wp_mail()` with SMTP credentials. Email delivery log in custom DB table. Test email utility.
|
|
|
|
---
|
|
|
|
## 13. IGNY8 Plugin — Content Sync (Connected Mode) {#13-content-sync}
|
|
|
|
### Files
|
|
|
|
```
|
|
modules/content-sync/
|
|
├── class-sync-module.php # Module entry, WP Cron scheduling
|
|
├── class-content-puller.php # Fetch content from IGNY8 SaaS API
|
|
├── class-content-mapper.php # Map IGNY8 content_type → WP post type
|
|
├── class-image-downloader.php # Download AI images → attach to posts
|
|
├── class-sync-queue.php # {prefix}igny8_sync_queue table management
|
|
├── class-publish-scheduler.php # Review queue, scheduled publishing
|
|
└── views/
|
|
├── sync-dashboard.php # Status, controls, history
|
|
└── content-review.php # Review queue before publish
|
|
```
|
|
|
|
### Content Type Mapping
|
|
|
|
| IGNY8 content_type | WP post_type | WP template | Notes |
|
|
|-------------------|-------------|-------------|-------|
|
|
| post | post | Standard | Default |
|
|
| page | page | Default page | — |
|
|
| product | product | WooCommerce product | Requires WooCommerce |
|
|
| service | service | single-service template | Requires theme CPT |
|
|
| company_page | page | page-company template | — |
|
|
| taxonomy_landing | — | — | Written to term description, not a post |
|
|
| cluster_hub | page | page-hub template | Landing page preset applied |
|
|
| comparison | post | Standard | — |
|
|
| brand_page | post or page | Standard | — |
|
|
|
|
### Sync Flow
|
|
|
|
```
|
|
IGNY8 SaaS publishes content
|
|
→ Webhook to plugin: POST /wp-json/igny8/v1/sync/push
|
|
→ Plugin creates sync queue entry (status: pending)
|
|
→ WP Cron processes queue:
|
|
1. Download images → attach to media library
|
|
2. Map content_type → WP post_type
|
|
3. Create/update WP post with content, meta, featured image
|
|
4. Assign taxonomies from IGNY8 cluster/attribute data
|
|
5. If taxonomy_landing: write to term description instead
|
|
6. Status: 'review' (manual review required) or 'synced' (auto-publish)
|
|
→ Plugin POSTs confirmation back to IGNY8 SaaS
|
|
```
|
|
|
|
---
|
|
|
|
## 14. IGNY8 Plugin — SAG Structure (Connected Mode) {#14-sag-structure}
|
|
|
|
### Files
|
|
|
|
```
|
|
modules/sag/
|
|
├── class-sag-module.php # Module entry
|
|
├── class-blueprint-sync.php # Receive SAG blueprint JSON from IGNY8
|
|
├── class-taxonomy-builder.php # register_taxonomy() from SAG attributes
|
|
├── class-term-builder.php # wp_insert_term() from attribute values
|
|
├── class-cluster-manager.php # Map clusters → hub pages/terms
|
|
├── class-structure-visualizer.php # Visual map of site structure
|
|
└── views/
|
|
├── sag-dashboard.php # SAG structure overview
|
|
├── blueprint-review.php # Review proposed taxonomies before applying
|
|
└── structure-map.php # Visual cluster/taxonomy/content map
|
|
```
|
|
|
|
### Blueprint Sync Flow
|
|
|
|
```
|
|
IGNY8 SaaS confirms blueprint
|
|
→ POST to plugin: /wp-json/igny8/v1/sag/sync-blueprint
|
|
→ Plugin stores blueprint in igny8_sag_blueprint option
|
|
→ Blueprint review UI shows proposed changes:
|
|
- New taxonomies to create
|
|
- New terms to create
|
|
- Existing taxonomies to map
|
|
→ User approves → Taxonomy Builder executes:
|
|
1. register_taxonomy() for each SAG attribute
|
|
(stored in option for persistence across requests)
|
|
2. wp_insert_term() for each attribute value
|
|
3. Set term meta: _igny8_term_sag_attribute, _igny8_term_sag_level
|
|
4. Map clusters to existing hub pages or create placeholders
|
|
→ Plugin POSTs success + term IDs back to IGNY8 SaaS
|
|
→ IGNY8 SaaS updates SAGAttribute.wp_taxonomy_slug and wp_sync_status
|
|
```
|
|
|
|
### Structure Visualizer
|
|
|
|
Admin page showing:
|
|
- Tree view: Taxonomies → Terms → assigned posts/products
|
|
- Cluster map: clusters as cards with hub page status, supporting content count
|
|
- Gap indicators: terms without content, clusters without hubs
|
|
- Connected to IGNY8: "Generate content for this term" links to IGNY8 app
|
|
|
|
---
|
|
|
|
## 15. Setup Wizard & SEO Import {#15-setup-wizard}
|
|
|
|
### Wizard Steps
|
|
|
|
| Step | Title | What It Does |
|
|
|------|-------|-------------|
|
|
| 1 | Site Type | Blog, Business, eCommerce, Local Business, SaaS, Portfolio — sets schema defaults |
|
|
| 2 | SEO Import | Detects Yoast/RankMath/AIOSEO → one-click import via WP Cron |
|
|
| 3 | Site Basics | Site name, Organization/Person, logo, title separator |
|
|
| 4 | Social Profiles | All social URLs + default sharing image |
|
|
| 5 | Connect to IGNY8 | API key input, connection test, site pairing. Clear skip option. |
|
|
| 6 | Done | Summary, "Run first site audit" CTA, key settings links |
|
|
|
|
### SEO Import Data Mapping
|
|
|
|
| Source | Source Meta Key | IGNY8 Meta Key |
|
|
|--------|----------------|---------------|
|
|
| Yoast | `_yoast_wpseo_focuskw` | `_igny8_focus_keyword` |
|
|
| Yoast | `_yoast_wpseo_title` | `_igny8_seo_title` |
|
|
| Yoast | `_yoast_wpseo_metadesc` | `_igny8_meta_description` |
|
|
| Yoast | `_yoast_wpseo_canonical` | `_igny8_canonical_url` |
|
|
| Yoast | `_yoast_wpseo_meta-robots-noindex` | `_igny8_robots_index` |
|
|
| RankMath | `rank_math_focus_keyword` | `_igny8_focus_keyword` |
|
|
| RankMath | `rank_math_title` | `_igny8_seo_title` |
|
|
| RankMath | `rank_math_description` | `_igny8_meta_description` |
|
|
| RankMath | `rank_math_canonical_url` | `_igny8_canonical_url` |
|
|
| RankMath | `rank_math_robots` | `_igny8_robots_index` + `_igny8_robots_follow` |
|
|
| AIOSEO | `_aioseo_title` | `_igny8_seo_title` |
|
|
| AIOSEO | `_aioseo_description` | `_igny8_meta_description` |
|
|
|
|
Import runs as background WP Cron task with progress tracking. Completion report shows counts per data type.
|
|
|
|
---
|
|
|
|
## 16. Data Architecture {#16-data-architecture}
|
|
|
|
### Custom Database Tables
|
|
|
|
| Table | Purpose | Created In |
|
|
|-------|---------|-----------|
|
|
| `{prefix}igny8_redirects` | Redirect rules (source, target, type, hits) | Phase 3 |
|
|
| `{prefix}igny8_404_log` | 404 hit log (URL, referrer, hits, resolved) | Phase 3 |
|
|
| `{prefix}igny8_link_map` | Internal link graph (source→target, anchor, position) | Phase 5 |
|
|
| `{prefix}igny8_audit_results` | Site audit findings (type, severity, message, data) | Phase 4 |
|
|
| `{prefix}igny8_email_log` | SMTP delivery log (to, subject, status, error) | Phase 6 |
|
|
| `{prefix}igny8_sync_queue` | Content sync queue (IGNY8 ID, status, WP post/term ID) | Phase 8 |
|
|
|
|
### Post Meta Keys (all prefixed `_igny8_`)
|
|
|
|
SEO: `focus_keyword`, `secondary_keywords`, `seo_title`, `meta_description`, `canonical_url`, `robots_index`, `robots_follow`, `og_title`, `og_description`, `og_image`, `twitter_title`, `twitter_description`, `schema_type`, `schema_custom`, `seo_score`, `content_score`, `readability_score`
|
|
|
|
Connected: `cluster_id`, `related_links`, `link_suggestions`, `last_analysis`, `igny8_content_id`, `sync_status`, `schema_faq`, `schema_howto`, `schema_article`, `schema_review`
|
|
|
|
### Term Meta Keys (all prefixed `_igny8_term_`)
|
|
|
|
`seo_title`, `meta_description`, `robots_index`, `og_image`, `content`, `cluster_id`, `sag_attribute`, `sag_level`, `faq`, `related_terms`, `igny8_id`
|
|
|
|
### Options Keys (all prefixed `igny8_`)
|
|
|
|
Global: `version`, `active_modules`, `seo_settings`, `schema_settings`, `sitemap_settings`, `social_profiles`, `analytics_settings`, `redirect_settings`, `smtp_settings`, `share_settings`, `linking_settings`, `intelligence_settings`
|
|
|
|
Connected: `api_key`, `api_connected`, `site_id`, `last_sync`, `sag_blueprint`, `gsc_token`, `gsc_property`
|
|
|
|
---
|
|
|
|
## 17. REST API Endpoints {#17-rest-api}
|
|
|
|
### Plugin-Provided Endpoints (for theme + external consumers)
|
|
|
|
```
|
|
GET /wp-json/igny8/v1/related/{post_id} # Related content links
|
|
GET /wp-json/igny8/v1/cluster/{cluster_id} # All content in cluster
|
|
GET /wp-json/igny8/v1/term/{term_id}/content # Term landing page data
|
|
GET /wp-json/igny8/v1/structure/overview # Site structure summary
|
|
GET /wp-json/igny8/v1/audit/summary # Site audit summary
|
|
```
|
|
|
|
### Plugin-Received Endpoints (from IGNY8 SaaS platform)
|
|
|
|
```
|
|
POST /wp-json/igny8/v1/sync/push # Push content from IGNY8
|
|
POST /wp-json/igny8/v1/sag/sync-blueprint # Push SAG blueprint
|
|
POST /wp-json/igny8/v1/sag/create-taxonomies # Create taxonomies from blueprint
|
|
POST /wp-json/igny8/v1/terms/{term_id}/content # Push term content
|
|
POST /wp-json/igny8/v1/schema/bulk-update # Push schemas for multiple posts
|
|
POST /wp-json/igny8/v1/gsc/status-sync # Push GSC index statuses
|
|
POST /wp-json/igny8/v1/event # Webhooks (task ready, etc.)
|
|
```
|
|
|
|
All endpoints validate `X-IGNY8-API-KEY` header against `Site.wp_api_key`.
|
|
|
|
---
|
|
|
|
## 18. Performance Rules {#18-performance}
|
|
|
|
| Rule | How |
|
|
|------|-----|
|
|
| Zero frontend CSS unless share buttons enabled | `wp_enqueue_scripts` with conditional check |
|
|
| Zero frontend JS unless share buttons or dynamic features active | Same conditional |
|
|
| ALL `<head>` output in single `wp_head` hook at priority 1 | `class-head-output.php` consolidates everything |
|
|
| Schema as single JSON-LD block, not multiple `<script>` tags | `class-schema-generator.php` merges all schemas |
|
|
| Admin assets only on IGNY8 admin pages | `admin_enqueue_scripts` with screen check |
|
|
| Meta box assets only on editor screens | Screen check before enqueue |
|
|
| Site audit runs via WP Cron, never on page load | `wp_schedule_event` weekly |
|
|
| Link crawl is background process | WP Cron, batch processing |
|
|
| Connected mode API calls are async | WP Cron queue, never blocks |
|
|
| Option reads use object cache | `wp_cache_get/set` wrapping |
|
|
|
|
---
|
|
|
|
## 19-25. Theme Build Reference {#19-theme-structure}
|
|
|
|
### 19. CPTs, Taxonomies, Meta Fields
|
|
|
|
**7 CPTs:** service, landing_page, portfolio, team_member, testimonial, faq, documentation
|
|
|
|
**9 Custom Taxonomies:** service_category, service_area, service_attribute, cluster, portfolio_category, portfolio_tag, faq_category, doc_category, topic_tag
|
|
|
|
**WooCommerce:** Theme does NOT register Woo taxonomies. Provides rich templates for product_cat, product_tag, pa_* archives. Registers `cluster` taxonomy for `product` post type.
|
|
|
|
**Meta fields per CPT:** Service (10 fields: price, duration, process steps, outcomes, FAQs, CTA, areas, gallery, related). Portfolio (8 fields: client, date, URL, results, tech, testimonial, gallery, before/after). Team (6 fields: position, email, phone, social, order, department). Testimonial (8 fields: author name/title, company, rating, image, featured, linked service/product). FAQ (2 fields: order, schema enabled). Documentation (4 fields: sidebar, TOC, last reviewed, related docs).
|
|
|
|
All theme meta keys use `_theme_` prefix. Theme reads `_igny8_` prefix for plugin data.
|
|
|
|
### 20. Term Landing Pages & SAG Templates
|
|
|
|
Every taxonomy term archive renders as a rich landing page with 7 sections:
|
|
|
|
1. **Term Hero** — H1 from term name, description, breadcrumbs, post count
|
|
2. **Rich Content** — From IGNY8 `_igny8_term_content` or WP term description
|
|
3. **Child Terms** — Grid of child term cards (if hierarchical)
|
|
4. **Posts Grid** — All posts in this term, paginated
|
|
5. **Related Clusters** — Other clusters sharing attribute values
|
|
6. **FAQ** — From `_igny8_term_faq` or `_theme_*` meta
|
|
7. **CTA** — Configurable call to action
|
|
|
|
Template files: `taxonomy-service_category.html`, `taxonomy-service_area.html`, `taxonomy-service_attribute.html`, `taxonomy-cluster.html`, `taxonomy-faq_category.html`, `taxonomy-product_cat.html`, `taxonomy-product_tag.html`
|
|
|
|
### 21. Landing Page Builder
|
|
|
|
**CPT:** `landing_page` with section repeater meta box (`_theme_landing_sections`)
|
|
|
|
**15 section types:** hero, features-grid, how-it-works, social-proof, pricing, faq, cta-band, content-block, stats-counter, team, portfolio-grid, contact-form, video-embed, logo-bar, comparison-table
|
|
|
|
**8 presets:** SaaS Product, Service Business, Product Launch, Lead Generation, Portfolio/Agency, Event/Webinar, Cluster Hub, Term Landing
|
|
|
|
Admin JS: drag-to-reorder sections, add/remove/duplicate, per-section field configuration. Frontend renderer: loops through sections, renders each with its template.
|
|
|
|
### 22. Block Patterns & Starter Templates
|
|
|
|
**50+ block patterns** organized by category: Heroes (4), Content (4), Social Proof (4), Conversion (4), Services (3), Portfolio (3), Footers (3), plus additional patterns.
|
|
|
|
**5 site-type starters** (importable demo content): Blog, SaaS, Corporate, eCommerce, Portfolio. Each includes: front-page, core pages, sample CPT entries, sample taxonomy terms.
|
|
|
|
### 23. Interlinking Display Components
|
|
|
|
6 template parts that read IGNY8 plugin data with graceful fallbacks:
|
|
|
|
| Component | Template Part | Data Source | Fallback |
|
|
|-----------|-------------|-------------|----------|
|
|
| Related Content | `parts/related-content.html` | `_igny8_related_links` post meta | WordPress related by category |
|
|
| Cluster Navigation | `parts/cluster-navigation.html` | `igny8()->linking->get_cluster_navigation()` | Posts in same cluster term |
|
|
| Attribute Browse | `parts/attribute-browse.html` | Custom taxonomy terms for context | — |
|
|
| Breadcrumb Trail | `parts/breadcrumbs.html` | `igny8()->seo->get_breadcrumbs()` | Theme simple breadcrumbs |
|
|
| Term Quick Links | `parts/term-quick-links.html` | All terms assigned to current post | — |
|
|
| Child Term Grid | `parts/child-term-grid.html` | `get_term_children()` + term meta | — |
|
|
|
|
### 24. WooCommerce Integration
|
|
|
|
When WooCommerce active, theme provides:
|
|
- `woocommerce/archive-product.php` — SAG-structured shop page
|
|
- `woocommerce/single-product.php` — Enhanced product page
|
|
- `woocommerce/taxonomy-product_cat.php` — Rich category landing page
|
|
- `woocommerce/content-product.php` — Product card in archives
|
|
- Cart, checkout, account template overrides
|
|
|
|
### 25. Design System & Build Execution
|
|
|
|
**theme.json:** Complete design token system — colors (primary palette + extended), typography (heading + body from curated list), spacing scale, shadows, border radius, transitions. Custom tokens for term pages and interlinking components.
|
|
|
|
**CSS:** BEM naming `.tn-block__element--modifier`. Total CSS budget <35KB gzipped.
|
|
**JS:** ES6+, vanilla JS, no jQuery on frontend. Each feature in own file, conditionally loaded. Total JS budget <15KB gzipped.
|
|
|
|
**Performance targets:** FCP <1.0s, LCP <1.5s, TBT <50ms, CLS <0.05, PageSpeed 95+ mobile.
|
|
|
|
---
|
|
|
|
## 26. Toolkit Plugin — All 5 Modules {#26-toolkit}
|
|
|
|
### File Structure
|
|
|
|
```
|
|
theme-name-toolkit/
|
|
├── theme-name-toolkit.php # Plugin header, module loader
|
|
├── readme.txt
|
|
├── includes/
|
|
│ ├── class-toolkit.php # Main class
|
|
│ ├── class-module-manager.php # Module toggle system
|
|
│ ├── modules/
|
|
│ │ ├── performance/ # Page cache, asset optimizer, image optimizer,
|
|
│ │ │ # critical CSS, HTML minifier, browser cache, preload
|
|
│ │ ├── forms/ # Form builder, renderer, processor, notifications,
|
|
│ │ │ # entries admin, anti-spam
|
|
│ │ ├── security/ # Login protection, firewall, hardening, headers, audit log
|
|
│ │ ├── smtp/ # SMTP mailer, email log, test email
|
|
│ │ └── woocommerce/ # Quick view, wishlist, AJAX cart, product filters, gallery
|
|
│ └── admin/
|
|
│ ├── class-dashboard.php # Module toggle dashboard
|
|
│ └── views/dashboard.php
|
|
└── languages/
|
|
```
|
|
|
|
Each module: independent enable/disable toggle from toolkit dashboard. Zero frontend impact when disabled.
|
|
|
|
---
|
|
|
|
## 27. Free vs Premium Split {#27-free-premium}
|
|
|
|
### Theme
|
|
|
|
| Feature | Free (WordPress.org) | Premium |
|
|
|---------|---------------------|---------|
|
|
| All 7 CPTs + taxonomies | ✅ | ✅ |
|
|
| All term landing page templates | ✅ | ✅ |
|
|
| Basic interlinking components | ✅ | ✅ |
|
|
| Landing page sections | 3 (hero, content-block, cta-band) | All 15 |
|
|
| Landing page presets | 2 (generic, service) | All 8 |
|
|
| Block patterns | 10 (2 per category) | All 50+ |
|
|
| Starter templates | 2 (blog, corporate) | All 5 |
|
|
| WooCommerce templates | ❌ | ✅ |
|
|
| Setup wizard + demo import | ❌ | ✅ |
|
|
| IGNY8 plugin bridge | ✅ Full | ✅ Full |
|
|
|
|
### Toolkit Plugin
|
|
|
|
| Feature | Free | Premium |
|
|
|---------|------|---------|
|
|
| Performance: page cache + HTML minification | ✅ | ✅ |
|
|
| Performance: full suite (critical CSS, image opt, WebP, assets) | ❌ | ✅ |
|
|
| Security: basic hardening + login protection | ✅ | ✅ |
|
|
| Security: full suite (firewall, audit log, 2FA) | ❌ | ✅ |
|
|
| Forms: basic (5 field types) | ✅ | ✅ |
|
|
| Forms: full suite (conditional logic, multi-step, file upload) | ❌ | ✅ |
|
|
| SMTP: basic mail override | ✅ | ✅ |
|
|
| SMTP: full suite (email log, templates) | ❌ | ✅ |
|
|
| WooCommerce enhancements | ❌ | ✅ |
|
|
|
|
---
|
|
|
|
## 28. Theme ↔ Plugin Contract {#28-theme-plugin-contract}
|
|
|
|
### What Theme Reads from Plugin
|
|
|
|
| Data | Source | Used For |
|
|
|------|--------|---------|
|
|
| SEO title | `igny8()->seo->get_title()` | `<title>` tag (theme defers to plugin) |
|
|
| Breadcrumbs | `igny8()->seo->get_breadcrumbs()` | Breadcrumb display |
|
|
| Related links | `_igny8_related_links` post meta | Related Articles section |
|
|
| Cluster navigation | `igny8()->linking->get_cluster_navigation()` | "More in this topic" section |
|
|
| Term landing content | `_igny8_term_content` term meta | Term archive hero section |
|
|
| Term FAQs | `_igny8_term_faq` term meta | FAQ accordion on term pages |
|
|
| Related terms | `_igny8_term_related_terms` term meta | "Related topics" block |
|
|
| SAG attribute label | `_igny8_term_sag_attribute` term meta | Attribute navigation sections |
|
|
| Share buttons | `igny8()->socializer->render_share_buttons()` | Social sharing section |
|
|
| Schema | `igny8()->schema->get_json_ld()` | Theme does NOT render schema (plugin owns `<head>`) |
|
|
|
|
### Graceful Degradation
|
|
|
|
```php
|
|
// Theme pattern for ALL plugin data reads:
|
|
if (function_exists('igny8')) {
|
|
$data = igny8()->module->get_data($id);
|
|
} else {
|
|
$data = theme_fallback_function($id);
|
|
}
|
|
```
|
|
|
|
When plugin is NOT installed: breadcrumbs use theme's simple implementation, related content uses category-based matching, term pages show standard WP description, share buttons don't render, schema doesn't output.
|
|
|
|
---
|
|
|
|
## 29. Plugin ↔ IGNY8 SaaS Communication {#29-saas-communication}
|
|
|
|
### Authentication
|
|
|
|
- Plugin stores `igny8_api_key` (from setup wizard Step 5)
|
|
- All requests to IGNY8 SaaS include `Authorization: Bearer {api_key}`
|
|
- All requests FROM IGNY8 SaaS to plugin include `X-IGNY8-API-KEY` header
|
|
- Plugin validates against `igny8_api_key` option
|
|
|
|
### Outbound (Plugin → SaaS)
|
|
|
|
| Event | Endpoint on SaaS | Payload |
|
|
|-------|------------------|---------|
|
|
| Site structure sync (daily) | `POST /v1/integration/integrations/{id}/update-structure/` | Post types, taxonomies, counts |
|
|
| Incremental data sync | `POST /v1/integration/integrations/{id}/sync-data/` | Modified posts since last sync |
|
|
| Full site scan (weekly) | `POST /v1/integration/integrations/{id}/full-scan/` | All posts, products, taxonomies |
|
|
| Content publish confirmation | `POST /v1/integration/integrations/{id}/publish-confirm/` | WP post ID, URL, status |
|
|
| Taxonomy creation report | `POST /v1/integration/integrations/{id}/taxonomy-report/` | Created taxonomy slugs + term IDs |
|
|
|
|
### Inbound (SaaS → Plugin)
|
|
|
|
| Event | Plugin Endpoint | Payload |
|
|
|-------|----------------|---------|
|
|
| Push content | `POST /wp-json/igny8/v1/sync/push` | Content HTML, meta, images, content_type |
|
|
| Push blueprint | `POST /wp-json/igny8/v1/sag/sync-blueprint` | Full SAG blueprint JSON |
|
|
| Create taxonomies | `POST /wp-json/igny8/v1/sag/create-taxonomies` | Taxonomy definitions + terms |
|
|
| Push term content | `POST /wp-json/igny8/v1/terms/{id}/content` | HTML content + meta for term |
|
|
| Push schemas | `POST /wp-json/igny8/v1/schema/bulk-update` | Schema JSON-LD per post |
|
|
| Push GSC statuses | `POST /wp-json/igny8/v1/gsc/status-sync` | URL index statuses |
|
|
| Push events | `POST /wp-json/igny8/v1/event` | task_ready, link_suggestion, etc. |
|
|
|
|
### Sync Architecture
|
|
|
|
```
|
|
IGNY8 SaaS (api.igny8.com)
|
|
│
|
|
│ Outbound webhooks (push content, blueprints, schemas, statuses)
|
|
▼
|
|
WordPress Plugin (site.com/wp-json/igny8/v1/*)
|
|
│
|
|
│ Periodic sync (structure, data, confirmations)
|
|
▼
|
|
IGNY8 SaaS (api.igny8.com/v1/integration/*)
|
|
```
|
|
|
|
All communication is HTTPS. Plugin-side: async via WP Cron (never blocks page load). SaaS-side: async via Celery tasks (never blocks API response).
|
|
|
|
---
|
|
|
|
## Reference Documents
|
|
|
|
| Document | Purpose |
|
|
|----------|---------|
|
|
| **IGNY8-Plugin-Build-Plan.md** | Complete plugin plan — modules, features, phases, file structure |
|
|
| **Theme-Build-Plan.md** | Complete theme plan — CPTs, taxonomies, templates, patterns, toolkit |
|
|
| **IGNY8-Current-State.md** | Current IGNY8 SaaS state — integration layer, plugin distribution, sync architecture |
|
|
| **Doc A — SAG Architecture Dev Guide** | SAG models, blueprints — what the plugin receives in connected mode |
|
|
| **Doc B — Platform Modules Dev Guide** | SaaS modules — what generates content/schemas/links pushed to plugin |
|
|
|
|
---
|
|
|
|
*End of Doc C — WordPress Ecosystem Development Guide*
|