# IGNY8 Core Workflows & Systems

Combines the previous `CONTENT-WORKFLOW-DIAGRAM.md`, sample credit usage notes, and scattered workflow descriptions into a single reference.

---

## Table of Contents
1. Planner Workflows
2. Site Builder (State-Aware Wizard)
3. Ideas & Writer Pipeline
4. Publishing & Sync
5. Credit & Usage Examples

---

## 1. Planner Workflows

### Keyword Intake & Management
1. Import keywords via CSV/manual → validate intent, volume, difficulty.
2. Keywords inherit account/site/sector context; duplicates prevented via `seed_keyword` + site/sector constraint.
3. Filtering/searching available by status, intent, sector, cluster assignment.

### Auto Clustering
```
Keyword Selection → POST /planner/keywords/auto-cluster →
run_ai_task(auto_cluster) → AI groups keywords →
Clusters created + keywords linked → Credits deducted
```
- Clusters now tagged with `context_type` (`topic`, `attribute`, `service_line`).
- Outputs recommendation metadata used by site builder taxonomy step.

### Cluster Management
- Views show per-cluster metrics (keyword count, volume, gap warnings).
- Users can assign clusters to site blueprints; gating enforced before sitemap generation.

---

## 2. Site Builder Workflow (Self-Guided Wizard)

| Step | Requirements | Output |
| --- | --- | --- |
| 1. Business Details | Site + sector selected, site type (blog/ecom/company), hosting target (IGNY8 vs WP). | Draft `SiteBlueprint`, workflow state `business_details`. |
| 2. Cluster Assignment | ≥1 planner cluster linked; show coverage metrics. | `SiteBlueprintCluster` rows, state `clusters_ready`. |
| 3. Taxonomy Builder | Define/import categories, tags, product attributes, service groups; map to clusters. | `SiteBlueprintTaxonomy` records, state `taxonomies_ready`. |
| 4. AI Sitemap | Allowed only when clusters + taxonomies ready; AI generates pages w/ entity types + cluster refs. | `PageBlueprint` records, coverage matrix, state `sitemap_ready`. |
| 5. Coverage Validation | Confirm each cluster has hub/supporting pages; unresolved items block progress. | Approval flag, state `ideas_ready`. |
| 6. Ideas Hand-off | Selected pages pushed to Planner Ideas with optional guidance prompt. | Idea queue seeded, state `ideas_in_progress`. |

Frontend enforcement:
- Zustand `builderWorkflowStore` tracks step state via `/site-builder/workflow/{id}`.
- Next buttons disabled until backend returns `step_status = complete`.
- Inline tooltips explain missing prerequisites, with links back to Planner.

---

## 3. Ideas & Writer Pipeline

### Ideas Creation
1. Wizard hand-off calls `POST /planner/content-ideas/bulk_from_blueprint`.
2. Each idea stores `cluster_id`, `taxonomy_id`, `site_entity_type`, `cluster_role`.
3. Ideas appear in Planner UI with badges showing target page type (blog post, product page, service page, taxonomy hub).

### Task Generation
1. `PageGenerationService.generate_all_pages` turns ideas/pages into Writer tasks.
2. Tasks carry metadata: `entity_type`, `taxonomy_id`, `cluster_role`, `product_data` (JSON for specs), keywords.

### AI Content Generation
```
Task Selection → POST /writer/tasks/generate →
run_ai_task(generate_content) → AI produces html/json_blocks →
Content saved + linked to tasks → Linker/Optimizer receive metadata
```
- Content also mapped to clusters/taxonomies via `ContentClusterMap` etc.
- Images workflow attaches prompts, usage context (featured, gallery, variant).

### State Awareness
- Writer dashboards show per-site progress bars (e.g., “Cluster Alpha: 2/5 hubs published”).
- Editors cannot mark content ready unless required taxonomy/attribute data is filled.

---

## 4. Publishing & Sync

### IGNY8 Hosting
1. Deploy action triggers `SitesRendererAdapter`.
2. Adapter merges published `Content.json_blocks` into page definitions, writes to `/data/app/sites-data/clients/{site_id}/v{version}`.
3. Renderer serves `https://sites.igny8.com/{siteSlug}`; cluster/taxonomy metadata included for internal linking.

### WordPress Sync
1. Integration settings tested via `WordPressAdapter.test_connection`.
2. Sync job (`ContentSyncService`) fetches WP taxonomies/posts/products, maps them to IGNY8 schemas via TaxonomyService.
3. Publishing back to WP reuses same metadata: categories/tags/attributes auto-created if missing, pages matched by external IDs.
4. Workflow enforces cluster assignment for imported content before allowing optimization tasks.

---

## 5. Credit & Usage Examples

| Operation | Trigger | Credit Cost | Notes |
| --- | --- | --- | --- |
| Auto Cluster | Planner keywords | 1 credit / 30 keywords | Minimum 1 credit per request. |
| Idea Generation | Cluster selection | 1 credit / idea | Charged when ideas created. |
| Content Generation | Writer tasks | 3 credits / content | Includes HTML + structured blocks. |
| Image Generation | Image tasks | 1 credit / image | Prompt extraction included in content gen. |
| Re-optimization | Optimizer rerun | 1 credit / rerun | Optional step for existing content. |

Credits deducted post-success via `CreditService`. Usage logs available under Billing > Usage.

---

## Credit-Only Operating Principles
- Subscription plans only define credit refills + support tier; every feature stays unlocked.
- No per-plan limits (keywords, clusters, tasks, images, sites, users, etc.); credits are the sole limiter.
- Actions check credit balance before running; insufficient credits show a blocking warning with CTA to top up.
- Frontend should always show remaining credits + estimated cost before execution.
- Credits must be purchasable on-demand, with logs + notifications when balances are low.

These principles come from the former “sample usage limits & credit system” note and govern all future modules.

---

## Cross-References
- Strategy & architecture context: `01-strategy.md`
- Phase-specific learnings & QA logs: `03-phase-reports.md`
- Execution roadmap & milestones: `04-roadmap.md`