igny8/docs/plans/Future_Moduels_Features/Optimizer_Module_Plan.md

Optimizer Module Plan (Detailed)

Scope: Optimizer focuses on rewriting/optimizing existing content across posts, pages, products, services, company pages, and taxonomy archives. Current release scope is WordPress-only (publish/sync + content discovery). Shopify/custom support is future.

Status Today: Optimizer module exists but is inactive by default and partially implemented. See docs/10-MODULES/OPTIMIZER.md.

---

1) Goal

Upgrade existing content to SEO‑strong, intent‑aligned pages by:

• Mapping content to semantic/topic clusters.
• Aligning page intent with cluster keyword targets.
• Rewriting structure + content to match current search intent.
• Adding schema, metadata, and on‑page SEO improvements.

---

2) Feature Set (Detailed)

2.1 Content Types Supported (WordPress v1)

• Posts (blog/article)
• Pages (static)
• Products (custom post type, if configured)
• Services (custom post type, if configured)
• Company pages (about/team/careers/FAQ/press)
• Taxonomy archives (category/tag)
• Cluster pages (IGNY8 cluster views)

---

2.2 Cluster‑Aligned Optimization

What it does

• Associates each content item with a primary cluster + secondary clusters.
• Uses cluster keyword list as optimization targets.

Outputs

• Updated content aligned to the best matching cluster intent.
• Keyword coverage improvements with semantic variants.

---

2.3 Intent‑Aligned Rewrite Engine

What it does

• Rewrites content to match user intent (informational, commercial, transactional).
• Adjusts structure and sections to meet SERP expectations.

Capabilities

• Expand thin pages into full SEO pages.
• Compress overly long pages to reduce fluff.
• Add missing sections and re‑order content flow.

---

2.4 SEO‑Rich Output (Structure + Meta + Schema)

What it does

• Generates SEO‑optimized headings, internal structure, and metadata.
• Adds schema markup when applicable.

Includes

• Meta title + meta description refresh
• H1/H2/H3 structure alignment
• Internal/external link placeholders (Linker integration)
• Image alt text improvements
• Schema JSON‑LD (Article, Product, FAQ, Organization, Breadcrumb, Service)

---

2.5 Page‑Level Optimization Scores

What it does

• Scores before/after content quality using current Optimizer scoring model.
• Tracks improvements by cluster alignment + keyword coverage.

---

3) App‑Consistent Architecture

3.1 Backend Modules (Aligned with Current Structure)

• Existing: backend/igny8_core/modules/optimizer/
• Existing: backend/igny8_core/business/optimization/

Add / Extend

• business/optimization/cluster_mapping.py (cluster assignment & keyword targets)
• modules/optimizer/models.py (extend OptimizationTask)
• modules/optimizer/serializers.py (add cluster mapping + schema)
• modules/optimizer/views.py (extend API)

---

3.2 Data Models (Proposed Extensions)

OptimizationTask (extend)

• primary_cluster_id
• secondary_cluster_ids (JSON)
• keyword_targets (JSON)
• schema_type (article/product/service/faq/org)
• schema_json (JSON)
• metadata_before (JSON)
• metadata_after (JSON)
• structure_changes (JSON)

---

3.3 API Endpoints (Aligned with Existing Style)

Existing

• POST /api/v1/optimizer/analyze/
• POST /api/v1/optimizer/optimize/
• POST /api/v1/optimizer/batch_optimize/

Add

• POST /api/v1/optimizer/assign_cluster/
• GET /api/v1/optimizer/cluster_suggestions/?content_id=
• POST /api/v1/optimizer/preview/ (structure + metadata + schema preview)
• POST /api/v1/optimizer/apply/ (persist optimized version)

---

3.4 Frontend Pages (Consistent with Current UI)

Pages

• /optimizer/content (content list + status)
• /optimizer/preview/:id (analysis + diff + schema preview)

Components

• Cluster mapping panel
• Keyword target editor
• Structure diff viewer
• Metadata + schema preview

---

4) WordPress‑Only Scope (Current Release)

4.1 WordPress Content Coverage

• Posts and Pages
• Taxonomy archives (category/tag)
• Custom post types (products/services if configured)

4.2 WordPress Sync Integration

• Use existing sync pipelines to pull WordPress content.
• Maintain wordpress_id mapping for optimized updates.

---

5) Optimization Logic (High‑Level)

5.1 Cluster Matching

• Analyze content title, headings, and keyword density.
• Match to existing cluster keyword sets.
• Provide suggestions if confidence < threshold.

5.2 Content Rewrite

• Rebuild structure to match intent + cluster focus.
• Inject missing sections (FAQs, comparisons, benefits, use cases).
• Normalize tone with existing Writer prompt settings.

5.3 SEO Enhancements

• Meta title/description refresh
• Heading structure refinement
• Internal link opportunities (handoff to Linker)
• Schema generation based on content type

---

6) Settings & Controls (Unified Settings)

Site Settings → Automation tab

• Enable Optimizer module
• Default schema type per content type
• Keyword density targets
• Content length guidelines
• Allow auto‑apply vs manual review

---

7) Notifications

• “Optimization analysis ready”
• “Optimization applied”
• “Schema generated”

---

8) Rollout Phases

Phase 1 (MVP)

• Analyze + optimize existing posts/pages
• Cluster mapping suggestions
• Manual apply

Phase 2

• Products/services/company pages support
• Schema + metadata output

Phase 3

• Taxonomy archive optimization
• Batch optimization

Phase 4

• Full automation stage integration

---

9) Non‑Goals (v1)

• Shopify/custom CMS support
• Automated schema validation tools
• Automatic publishing without review

---

10) Success Criteria

• Increased keyword coverage vs cluster targets
• Higher content quality scores (before/after)
• Improved SERP performance for optimized pages

---

11) Dependencies

• Cluster data quality in Planner
• WordPress sync reliability
• Unified settings availability

---

12) Risks & Mitigations

• Risk: Over‑optimization → Mitigation: density caps + manual review.
• Risk: Wrong cluster mapping → Mitigation: suggestion + override flow.
• Risk: Schema mismatch → Mitigation: type validation + preview.

---

13) Future Extensions (Post‑WordPress)

• Shopify product catalogs
• Custom CMS adapters
• Automated schema validation pipeline
• SERP‑based optimization suggestions