# 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](../../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