42 KiB
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
- Architecture Overview — Three Deliverables
- Build Sequence — What Comes First
- IGNY8 Plugin — Foundation & Infrastructure
- IGNY8 Plugin — Module 1: SEO Core
- IGNY8 Plugin — Module 2: Schema
- IGNY8 Plugin — Module 3: Sitemap
- IGNY8 Plugin — Module 4: Redirects
- IGNY8 Plugin — Module 5: Site Intelligence
- IGNY8 Plugin — Module 6: Internal Linking
- IGNY8 Plugin — Module 7: GSC
- IGNY8 Plugin — Module 8: Socializer
- IGNY8 Plugin — Module 9: Analytics + SMTP
- IGNY8 Plugin — Module 10: Content Sync (Connected)
- IGNY8 Plugin — Module 11: SAG Structure (Connected)
- IGNY8 Plugin — Setup Wizard & Import
- IGNY8 Plugin — Data Architecture
- IGNY8 Plugin — REST API Endpoints
- IGNY8 Plugin — Performance Rules
- Theme — CPTs, Taxonomies, Meta Fields
- Theme — Term Landing Pages & SAG Templates
- Theme — Landing Page Builder
- Theme — Block Patterns & Starter Templates
- Theme — Interlinking Display Components
- Theme — WooCommerce Integration
- Theme — Design System & Build Plan
- Toolkit Plugin — All 5 Modules
- Free vs Premium Split
- Theme ↔ Plugin Contract
- Plugin ↔ IGNY8 SaaS Communication
1. Architecture Overview — Three Deliverables
┌────────────────────────────────────────────────────────────┐
│ 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
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.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:
// 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:
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
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>. Singlewp_headhook 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)
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)
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
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
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
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
| 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. 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:
- Term Hero — H1 from term name, description, breadcrumbs, post count
- Rich Content — From IGNY8
_igny8_term_contentor WP term description - Child Terms — Grid of child term cards (if hierarchical)
- Posts Grid — All posts in this term, paginated
- Related Clusters — Other clusters sharing attribute values
- FAQ — From
_igny8_term_faqor_theme_*meta - 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 pagewoocommerce/single-product.php— Enhanced product pagewoocommerce/taxonomy-product_cat.php— Rich category landing pagewoocommerce/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
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
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
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
// 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
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-KEYheader - Plugin validates against
igny8_api_keyoption
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