docs re-org

docs/40-WORKFLOWS/CONTENT-LIFECYCLE.md

@@ -0,0 +1,73 @@
+ # Content Lifecycle
+ 
+ ## Purpose
+ Trace content from keyword intake through clustering, idea generation, task creation, AI writing, image generation, and publishing/sync, mapping to backend services and frontend pages.
+ 
+ ## Code Locations (exact paths)
+ - Planner models: `backend/igny8_core/business/planning/models.py` (`Keywords`, `Clusters`, `ContentIdeas`)
+ - Writer models: `backend/igny8_core/business/content/models.py` (`Tasks`, `Content`, `Images`, `ContentTaxonomy`)
+ - ViewSets: `backend/igny8_core/modules/planner/views.py`; `backend/igny8_core/modules/writer/views.py`
+ - Automation orchestration: `backend/igny8_core/business/automation/services/automation_service.py`; Celery tasks `business/automation/tasks.py`
+ - WordPress sync/publish: `backend/igny8_core/business/integration/services/integration_service.py`, `modules/integration/views.py`
+ - Frontend pages: `frontend/src/pages/Planner/*`, `frontend/src/pages/Writer/*`, `frontend/src/pages/Automation/AutomationPage.tsx`, `frontend/src/pages/Sites/*`
+ 
+ ## High-Level Responsibilities
+ - Collect and cluster keywords, generate ideas, create tasks, generate content and images, then publish/sync.
+ - Support manual steps via Planner/Writer pages and automated runs via Automation pipeline.
+ - Maintain site/sector scoping and credit enforcement throughout AI operations.
+ 
+ ## Detailed Behavior
+ - Keywords → Clusters: `KeywordViewSet` (upload/create) and `ClusterViewSet` (manual or AI auto_cluster). Models inherit `SiteSectorBaseModel` for scoping.
+ - Clusters → ContentIdeas: `ContentIdeasViewSet` with AI generation endpoint; ideas track status.
+ - Ideas/Tasks: `Tasks` model holds brief/keywords/structure/status; created manually or by automation stage.
+ - Tasks → Content: Writer endpoints generate content (AI) and update `Content` records; statuses managed in writer views.
+ - Content → Images: `ImagesViewSet` handles image generation and storage; images linked to tasks/content.
+ - Publishing: Integration service sends content to WordPress via `/api/v1/integration` endpoints; WP plugin responds with IDs and syncs status back.
+ - Automation: `automation_service.run_automation` executes 7 stages with delays/retries/credit estimates; run status tracked in `AutomationRun`.
+ 
+ ## Data Structures / Models Involved (no code)
+ - Planner: `Keywords`, `Clusters`, `ContentIdeas`.
+ - Writer: `Tasks`, `Content`, `Images`, `ContentTaxonomy`.
+ - Automation: `AutomationConfig`, `AutomationRun`.
+ - Integration: `SiteIntegration`.
+ 
+ ## Execution Flow
+ - Manual path: upload keywords → cluster (auto/manual) → generate ideas → create tasks → generate content → generate images → publish to WP → WP syncs status back.
+ - Automated path: Automation pipeline stages perform the same transitions in sequence, logging progress and deducting credits.
+ - Each stage uses DRF viewsets; automation uses Celery tasks (`run_automation_task`, `resume_automation_task`) and logger for trace files.
+ 
+ ## Cross-Module Interactions
+ - Automation consumes planner/writer endpoints and triggers integration publish.
+ - Integration relies on site’s WP API key (`Site.wp_api_key`) and `SiteIntegration` config for credentials/URLs.
+ - Billing deducts credits for AI operations through `CreditService`.
+ 
+ ## State Transitions (if applicable)
+ - Keywords: status (active/inactive/used) per model.
+ - Clusters: status (active/archived).
+ - ContentIdeas: status (draft/approved/in_progress/completed).
+ - Tasks: status simplified (queued/completed) in Stage 1; content status (draft/published) and image status stored on related models.
+ - AutomationRun: status across run lifecycle (created/running/paused/completed/failed).
+ 
+ ## Error Handling
+ - Viewsets rely on unified DRF error responses; automation logger records failures per stage; Celery retries configured where applicable.
+ - WordPress sync errors surfaced via integration service responses.
+ 
+ ## Tenancy Rules
+ - All planner/writer/automation/integration models inherit account/site/sector via base models; viewsets filter by `request.account` and query params.
+ 
+ ## Billing Rules (if applicable)
+ - AI clustering/idea/content/image generation deduct credits via `CreditService` cost map; automation blocks run if estimated credits insufficient.
+ 
+ ## Background Tasks / Schedulers (if applicable)
+ - Automation scheduler: `check_scheduled_automations` enqueues runs; `run_automation_task`/`resume_automation_task` execute pipeline in Celery.
+ - AI tasks run async via Celery wrappers (`ai/tasks.py`).
+ 
+ ## Key Design Considerations
+ - Single source of truth for tenancy via base models; prevents cross-tenant data exposure.
+ - Automation mirrors manual flow; manual pages remain usable when automation is paused or disabled.
+ - WordPress publish/sync uses API key auth to avoid storing user credentials beyond site integration config.
+ 
+ ## How Developers Should Work With This Module
+ - When adding new content stages, update both manual endpoints and automation stages.
+ - Ensure every new action that calls AI is wired through `CreditService` and respects site/sector filters.
+ - For new publishing targets, extend `SiteIntegration` and integration service while keeping site/account scoping.