ds
This commit is contained in:
IGNY8 VPS (Salman)
127
part2-dev/planning/02-workflows.md
Normal file
127
part2-dev/planning/02-workflows.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# 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`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user