igny8/docs/plans/Future_Moduels_Features/Taxonomy_Term_Content_Plan.md

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.
• Content supports content_type='taxonomy' and taxonomy‑specific structures. See 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.

1.2 WordPress Client Already Knows Taxonomies

• WordPress REST: get_categories, get_tags, create_category, create_tag. See backend/igny8_core/utils/wordpress.py.
• WooCommerce: product categories + attributes and terms are fetchable. See 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.
• 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