igny8/master-docs/40-product/CONTENT-LIFECYCLE.md

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.