# 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.