128 lines
5.8 KiB
Markdown
128 lines
5.8 KiB
Markdown
# 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`
|
|
|
|
|