igny8/part2-dev/planning/02-workflows.md

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