# IGNY8 Sites, Planner, and Writer – Unified Architecture Plan

## Purpose
Describe the backend and frontend changes required to support cluster-first site planning, taxonomy-aware site building (blog, ecommerce, company), and seamless integration with WordPress sync workflows. This document consolidates the previous analysis into an actionable architecture plan—no implementation code, only structure, responsibilities, and key function/service names where helpful.

---

## High-Level Objectives
- Enforce keyword/cluster gating before any sitemap or content planning.
- Generate and manage taxonomies (categories, tags, product attributes, service groups) as first-class entities tied to clusters.
- Support three site archetypes (blog, ecommerce, company) while keeping the framework extensible.
- Ensure Planner → Ideas → Writer → Linker → Optimizer all operate with consistent metadata (clusters, taxonomies, entity types).
- Maintain a shared data model for native IGNY8 sites and synced WordPress properties—no duplication, just different hosting targets.

---

## Backend Architecture Plan

### 0. Ownership & Responsibility Layers
- **Planner Domain** – Keyword import, clustering, taxonomy recommendations, idea orchestration.
- **Site Builder Domain** – Brief intake, taxonomy blueprinting, sitemap scaffolding, hosting destination awareness.
- **Writer Domain** – Idea-to-task conversion, AI generation, media assets, optimization readiness.
- **Publishing/Sync Domain** – Deployment to IGNY8 renderer, WordPress/WooCommerce sync adapters, status reconciliation.

### 1. Data Model Extensions
| Area | Changes | Notes |
| --- | --- | --- |
| **Site Builder** | Add `SiteBlueprintCluster`, `SiteBlueprintTaxonomy`, `PageBlueprint.entity_type`, `PageBlueprint.taxonomy_ref_id`. Support taxonomy types (`blog_category`, `blog_tag`, `product_category`, `product_tag`, `product_attribute`, `service_category`). Track cluster role (hub, pillar, supporting). | Enables sitemap to reference clusters/taxonomies explicitly. |
| **Planner (Keywords/Clusters/Ideas)** | Enhance `Clusters` with `context_type` (`topic`, `attribute`, `service_line`), `dimension_meta` JSON. Extend `Keywords` with `attribute_values`. Expand `ContentIdeas` to include `site_entity_type`, `taxonomy_id`, `cluster_role`. | Allows multi-dimensional clustering (topic + attribute) and taxonomy seeding. |
| **Writer (Tasks/Content/Images)** | Add `Tasks.entity_type`, `Tasks.taxonomy_id`, `Tasks.cluster_role`, `Tasks.product_data`. Introduce `ContentClusterMap`, `ContentTaxonomyMap`, `ContentAttributeMap` tables. Expand `Images` with `usage_context`. | Gives structured metadata for publishing, linking, and optimization. |
| **Linker & Optimizer** | Update services to rely on new mapping tables and cluster dimensions for auto-linking and scoring. | No schema change beyond indices referencing new relations. |
| **WordPress Sync** | Store external taxonomy IDs within `SiteBlueprintTaxonomy`, `ContentTaxonomyMap`, etc., so synced content maps cleanly. | Requires metadata fields like `external_reference`. |

### 2. Service / Workflow Updates
- **StructureGenerationService.generate_structure**: extend prompts to consume cluster lists, taxonomy seeds, and site type; output page → cluster/taxonomy assignments.
- **TaxonomyService (new)**: handles CRUD of blueprint taxonomies, ties them to clusters/keywords, imports from WordPress/WooCommerce.
- **ClusteringService**: upgrade to produce topic + attribute layers, propose taxonomy seeds, flag uncovered product/service dimensions.
- **IdeasService & ContentGeneration pipeline**: ensure all tasks carry cluster/taxonomy metadata; enforce “no cluster, no idea/task” rule.
- **LinkingService / OptimizerService**: leverage `ContentClusterMap` and `ContentAttributeMap` to generate hub ↔ attribute links, evaluate dimension coverage.
- **WordPressSyncService**: fully implement taxonomy + product fetching, map to IGNY8 schema, and reuse TaxonomyService for storage.
- **WorkflowStateService (new)**: persists user progress for each site build (step status, prerequisites met) to drive state-aware frontend.
- **Validation hooks**: per-step API validators (e.g., `validate_clusters_attached(site_blueprint_id)`) exposed to frontend for gating buttons.

### 3. API & Validation
- Builder endpoints must require cluster selection and taxonomy definition before allowing `generate_structure`.
- Planner/Ideas endpoints validate that requested entity types align with available taxonomies (e.g., product ideas require product categories/attributes).
- Writer endpoints include entity metadata in serializers to surface context in dashboards.

### 4. End-to-End Backend Flow (Self-Guided)
1. **Wizard Initiation**  
   - `POST /site-builder/blueprints/` creates draft blueprint + workflow state record (step = `business_details`).
2. **Cluster Attachment**  
   - `POST /site-builder/blueprints/{id}/clusters/attach` validates at least one planner cluster; updates workflow state → `clusters_ready`.
3. **Taxonomy Blueprinting**  
   - `POST /site-builder/blueprints/{id}/taxonomies/` uses `TaxonomyService`. Each taxonomy row stored with cluster references; workflow state → `taxonomies_ready` when required types filled per site archetype.
4. **Sitemap Generation**  
   - `POST /site-builder/blueprints/{id}/generate_structure/` allowed only if previous flags true. Service writes `structure_json`, `PageBlueprint` rows, `SiteBlueprintCluster` coverage map; workflow state → `sitemap_ready`.
5. **Coverage Check**  
   - `POST /site-builder/blueprints/{id}/coverage/confirm` ensures each cluster has hub + at least one supporting entity; sets state → `ideas_ready`.
6. **Ideas Creation**  
   - `POST /planner/content-ideas/bulk_from_blueprint/` generates ideas referencing blueprint/page IDs; state → `ideas_in_progress`.
7. **Writer Tasks**  
   - `PageGenerationService.generate_all_pages` creates `Tasks` with entity metadata; `Content` pipeline runs as today but includes cluster/taxonomy associations.
8. **Link/Optimize**  
   - Linker/optimizer services query new mapping tables to produce suggestions and scorecards; statuses fed back to workflow to show completion percentages.
9. **Publish/Sync**  
   - `SitesRendererAdapter` or `WordPressAdapter` reads structured metadata for deployment, ensuring taxonomies exist upstream (adapter auto-creates if missing).

---

## Frontend Architecture Plan

### 1. Wizard & Sites Module
| Step | Enhancements |
| --- | --- |
| Business Details | Site type selector (blog/ecommerce/company) with hosting options (IGNY8, WordPress); auto-detect hosting if WP integration exists. |
| Cluster Assignment | Dedicated step to select/attach planner clusters (with search/filter); block progress until at least one cluster chosen; show metrics (keywords, volume). |
| Taxonomy Builder | Visual editor for categories/tags/product attributes/service groups. Allow suggestions from clustering results and imports from WP. Support linking each taxonomy item to a cluster (hub or attribute). |
| Sitemap Review | Present AI-generated pages grouped by cluster/taxonomy; allow manual adjustments; highlight uncovered clusters or orphaned taxonomies. Show checklist for required hub/supporting pages per cluster. |
| Ideas Hand-off | Provide UI to send selected pages to Ideas module with optional guidance prompt (2nd prompt requirement). Display confirmation modal summarizing clusters + page counts. |

### 1.1 Wizard State Management (Self-Guided UX)
- Use a dedicated Zustand/Redux slice `builderWorkflowStore` to track: `currentStep`, `completedSteps`, `blockingIssues`, `blueprintState`.
- Each step component fetches validation status via `/site-builder/workflow/{blueprintId}` to decide if Next button is enabled.
- Inline “Why disabled?” tooltips list missing requirements (e.g., “Attach ≥1 cluster with ≥3 keywords each”).
- Breadcrumb/progress indicator shows step numbers + completion badges.
- Autosave after each interaction; resume wizard lands user back on last incomplete step.

### 2. Planner & Keyword UI
- Update cluster list views to show context type and associated taxonomies.
- Add attribute dimension visualization (e.g., matrix of clusters vs attributes).
- Ensure keyword table supports attribute tagging and multi-dimensional filtering.

### 3. Ideas & Writer Dashboards
- Surfaces for entity types (blog post, product, service, taxonomy page) with filters.
- Editors receive context chips (cluster, taxonomy, attribute). Provide quick links to hub pages and attribute groups.
- Validation states: warn if content lacks required taxonomy or attribute coverage before publishing.
- Task list views grouped by blueprint/site; show progress bars (e.g., “Products: 5/12 drafted”).
- Writer editor side panel summarises: assigned cluster, target taxonomy, keyword cluster metrics, attribute list.

### 4. Linker & Optimizer UI
- Linker suggestion panel grouped by cluster role (hub → supporting, hub → attribute).
- Optimizer scorecards showing coverage per cluster dimension (topic, attribute, intent).

### 5. WordPress Sync Screens
- Integration settings show detected taxonomies and site type.
- Sync dashboard lists imported posts/products/services with their cluster/taxonomy assignments; allow manual re-mapping.
- Provide “Sync health” panel: taxonomy parity, cluster coverage, last sync time. Buttons disabled if prerequisites unmet (e.g., no clusters mapped).

### 6. UX Guardrails & Guidance
- **Contextual Helpers**: Each wizard step includes collapsible explainer matching backend validations (“Clusters drive sitemap; select clusters to continue.”).
- **Empty States**: Planner/writer views show CTA buttons to jump back into wizard steps when prerequisites missing.
- **Notifications**: System toasts (or inline callouts) when backend rejects action—links take user to offending step.
- **Review Mode**: After completion, a read-only summary page lists all steps with “Edit” buttons, ensuring users never feel lost.

---

## Workflow Alignment Summary
1. **Site Brief Intake** → choose site type + hosting, gather business data.
2. **Cluster Gating** → attach keyword clusters/keywords; enforce before sitemap.
3. **Taxonomy Blueprint** → define or import taxonomies linked to clusters.
4. **AI Sitemap Generation** → produce pages with entity types + cluster/taxonomy refs.
5. **Coverage Validation** → ensure no cluster/taxonomy gaps before moving on.
6. **Ideas Creation** → push sitemap nodes into Ideas with cluster/taxonomy metadata; capture secondary prompt.
7. **Writer Flow** → existing pipeline enhanced with entity metadata, rich product/service attributes, and multi-dimensional content blocks.
8. **Linking & Optimization** → leverage new relations for automatic internal linking and SEO scoring.
9. **Deployment / Sync** → IGNY8 hosting deploys enriched content; WordPress adapter syncs posts/products/services with matching taxonomies (no duplication, just publishing).

---

## Implementation Notes
- Prioritize schema migrations and service updates before UI changes to ensure APIs provide necessary data.
- Keep prompts/configs environment-driven for easy tuning as new site types (e.g., SaaS portals) are added later.
- Maintain backward compatibility by auto-populating default values for existing blueprints/tasks until users opt into the new flow.
- Testing should cover: multi-site types, imported WordPress data, planner → writer gating, and deployment outputs.

---

*Document owner: Architecture team.*  
*Last updated: {{DATE}} (replace during edits).*