# Taxonomy & Term Content Plan (Detailed)

**Scope:** WordPress-only for current release. Shopify/custom sites remain future.

**Goal:** Make taxonomy terms and archives first‑class content pages (SEO landing pages) that are generated, optimized, and mapped to clusters using the same Planner → Writer → Optimizer pipeline as posts.

---

## 1) Current App Findings (Relevant Parts)

### 1.1 Content Models Already Support Taxonomy
- `Tasks` supports `content_type='taxonomy'` and `content_structure` values including `category_archive`, `tag_archive`, `attribute_archive`, `cluster_hub`. See [backend/igny8_core/business/content/models.py](../../backend/igny8_core/business/content/models.py).
- `Content` supports `content_type='taxonomy'` and taxonomy‑specific structures. See [backend/igny8_core/business/content/models.py](../../backend/igny8_core/business/content/models.py).
- `ContentTaxonomy` exists with `external_taxonomy`, `external_id`, `description`, and `metadata` for sync. See [backend/igny8_core/business/content/models.py](../../backend/igny8_core/business/content/models.py).

### 1.2 WordPress Client Already Knows Taxonomies
- WordPress REST: `get_categories`, `get_tags`, `create_category`, `create_tag`. See [backend/igny8_core/utils/wordpress.py](../../backend/igny8_core/utils/wordpress.py).
- WooCommerce: product categories + attributes and terms are fetchable. See [backend/igny8_core/utils/wordpress.py](../../backend/igny8_core/utils/wordpress.py).

### 1.3 Sync Service Partially Implemented (Then Removed)
- Taxonomy sync functions exist but are currently **skipped** with a “legacy removed” note. See [backend/igny8_core/business/integration/services/content_sync_service.py](../../backend/igny8_core/business/integration/services/content_sync_service.py).
- Posts sync assigns placeholder categories/tags by ID; product sync stores categories/tags/attributes in metadata only.

**Conclusion:** The database and data model already allow taxonomy content, but sync + content generation for terms is incomplete.

---

## 2) Target Outcome

### 2.1 First‑Class Term Landing Pages
Every taxonomy term becomes a **rich SEO landing page** rather than a simple list of posts.

**Examples**
- Category: “Electric Toothbrushes” → full landing page with intro, buyer guidance, top items, FAQs.
- Tag: “Remote Work” → topical overview + curated posts.
- Product Attribute: “Material: Stainless Steel” → attribute landing page.

### 2.2 Cluster‑Aligned Structure
- Each term is mapped to **primary cluster** + optional secondary clusters.
- Each term page follows a **cluster‑aligned structure** (H2/H3 outline, keyword coverage, semantic variants).

### 2.3 Same Pipeline as Posts
Planner → Writer → Optimizer should work for taxonomy pages the same way it works for posts.

---

## 3) Functional Scope

### 3.1 Content Writer for All Terms (Default + Custom Taxonomies)
- WordPress default: category, post_tag
- WooCommerce: product_cat, product_tag
- Product attributes (e.g., `pa_color`, `pa_size`)
- Custom taxonomies (configurable list from site integration)

### 3.2 Products Pages Writing
- Use existing product sync data + clusters to generate product landing pages and individual product enhancements.

### 3.3 Services / Company Pages Writing
- Use existing Writer structures (`service_page`, `business_page`, `general`) and cluster mapping.

### 3.4 Cluster Hub Pages
- Create **cluster landing pages** that aggregate all related terms + posts + products.

---

## 4) Architecture Plan (Aligned with App)

### 4.1 Taxonomy Sync (WordPress)
**Add/Restore taxonomy sync** in `ContentSyncService`:
- Fetch categories & tags via `WordPressClient`.
- Fetch WooCommerce product categories + attributes + terms.
- Sync to `ContentTaxonomy` with correct `external_taxonomy` values.

**Why:** term metadata is required for mapping, writing, and linking.

---

### 4.2 Term‑to‑Cluster Mapping
**New service:** `business/optimization/cluster_mapping.py` (shared with Optimizer).
- Map term name/description to clusters.
- Persist mapping in `Content.cluster` and/or a `ContentClusterMap`.

---

### 4.3 Term Content Generation (Writer)
**Flow (mirrors posts):**
1. Create `ContentIdea` from term + cluster data.
2. Create `Tasks` with `content_type='taxonomy'` and appropriate `content_structure`.
3. Use Writer to generate HTML content, meta, and structure.
4. Save as `Content` linked to `ContentTaxonomy`.

**Suggested structures:**
- Category → `category_archive`
- Tag → `tag_archive`
- Attribute → `attribute_archive`
- Cluster landing → `cluster_hub`

---

### 4.4 Publishing Back to WordPress
**WordPress update targets:**
- Write generated content to **term description** for taxonomy pages.
- Store structured content in term meta (future: ACF or custom IGNY8 plugin fields).

**Notes:**
- WordPress term descriptions accept HTML and can be displayed by themes.

---

### 4.5 Optimizer Alignment
Use Optimizer to:
- Rewrite existing term descriptions.
- Align term pages with cluster keyword targets.
- Inject schema and metadata updates.

---

## 5) API & UI Plan

### 5.1 API Endpoints (Proposed)
- `GET /api/v1/taxonomy/terms/?site_id=`
- `POST /api/v1/taxonomy/terms/sync/`
- `POST /api/v1/taxonomy/terms/create_tasks/`
- `POST /api/v1/taxonomy/terms/optimize/`
- `POST /api/v1/taxonomy/terms/publish/`

### 5.2 UI Pages
- **Taxonomy Overview**: list terms, cluster mapping status, content status.
- **Term Content Editor**: preview + rewrite + publish.
- **Cluster Hub Manager**: cluster landing pages and cross‑links.

---

## 6) Keyword + Cluster Strategy

### 6.1 Term‑Cluster Assignment
- Auto‑assign cluster based on keyword overlap + semantic similarity.
- Manual override in UI.

### 6.2 Term Keyword Targets
- Use cluster keywords as primary/secondary targets.
- Add term‑specific modifiers (e.g., “best”, “vs”, “near me”).

---

## 7) Term Landing Page Structure (SEO‑Rich)

**Default sections (taxonomy pages):**
1. Intro + term definition
2. Key subtopics (H2/H3)
3. Top related posts/products/services
4. FAQs
5. Internal links to related clusters

**Schema:**
- `CollectionPage` or `WebPage`
- `FAQPage` if FAQs present

---

## 8) Rollout Phases

**Phase 1**
- Taxonomy sync (categories + tags)
- Term mapping to clusters
- Writer tasks for term pages

**Phase 2**
- WooCommerce product categories + attributes
- Term optimization with Optimizer

**Phase 3**
- Cluster hub pages
- Full taxonomy publish flow

**Phase 4**
- Custom taxonomies configuration
- Cross‑site cluster navigation

---

## 9) Success Criteria
- All taxonomy terms have generated content and cluster mapping.
- Term landing pages outperform plain archive pages.
- Consistent internal linking between clusters, terms, and posts.

---

## 10) Risks & Mitigations
- **Risk:** Themes not showing term descriptions → **Mitigation:** IGNY8 plugin blocks or template guidance.
- **Risk:** Incorrect cluster mapping → **Mitigation:** manual override + suggestions.
- **Risk:** Over‑optimization → **Mitigation:** density caps + manual review.

---

## 11) Non‑Goals (v1)
- Shopify taxonomy sync
- Custom CMS adapters
- Automated publishing without review