igny8/master-docs/10-backend/planner/PLANNER-MODELS-AND-FLOW.md

Planner Models and Flow

Purpose

Provide a detailed view of planner models, their constraints, and how planner CRUD/bulk operations move data toward the writer pipeline.

Code Locations (exact paths)

• Models: backend/igny8_core/business/planning/models.py
• Serializers: backend/igny8_core/modules/planner/serializers.py
• Views: backend/igny8_core/modules/planner/views.py
• Services: backend/igny8_core/business/planning/services/clustering_service.py, ideas_service.py

High-Level Responsibilities

• Maintain tenant/site/sector-scoped planner entities (Keywords, Clusters, ContentIdeas) backed by global SeedKeywords.
• Enforce industry/sector alignment and uniqueness within site/sector.
• Support search, filtering, ordering, and bulk operations for planner data.
• Feed automation and writer tasks with curated ideas and clusters.

Detailed Behavior

• Models:
  • Keywords: links to SeedKeyword; overrides for volume/difficulty; optional cluster; status new/mapped; disabled flag; validation ensures seed keyword industry matches site industry and seed sector matches site sector’s industry sector; unique per site/sector and seed keyword; soft-delete enabled.
  • Clusters: topic groups with counts, volume, mapped_pages, status new/mapped; unique per site/sector by name; soft-delete enabled.
  • ContentIdeas: status new/queued/completed, content_type/structure choices, estimated word count, optional keyword objects M2M, keyword_cluster FK; soft-delete enabled.
• Viewsets:
  • KeywordViewSet: search by seed_keyword.keyword; filter by status, cluster, seed intent; ordering by created_at, seed volume/difficulty; custom range filters for difficulty/volume; requires site_id/sector_id on create; bulk_delete; two bulk_update actions (status); bulk_add_from_seed to create Keywords from SeedKeywords with site/sector validation.
  • ClusterViewSet: site/sector filtered; CRUD; status updates; inherits filtering from base with developer/admin/system override.
  • ContentIdeasViewSet: CRUD; filters by status/cluster; requires site_id/sector_id on create.
• Serializers:
  • KeywordSerializer demands seed_keyword_id on create; derives read-only keyword/volume/difficulty/intent from seed; supports volume/difficulty overrides; exposes cluster/sector names; write-only site_id/sector_id.
  • ClusterSerializer exposes sector name; write-only site_id/sector_id; counts/volume/mapped_pages read-only.
  • ContentIdeasSerializer exposes cluster/sector names; write-only site_id/sector_id.
• Services:
  • ClusteringService and IdeasService (not expanded here) are used by automation/AI flows for clustering and idea generation.

Execution Flow

• Planner CRUD/bulk requests → DRF auth → SiteSectorModelViewSet filtering → serializer validation (seed/site/sector) → model save → unified response.
• Bulk operations act on the filtered queryset (account/site/sector scoped).
• Automation stages 1–3 consume planner data and advance statuses.

Cross-Module Interactions

• Writer tasks and content reference clusters/ideas; automation transforms planner data into tasks/content/images.
• Billing credit checks occur in automation/AI calls that process planner entities.

State Transitions

• Keywords: new → mapped; Clusters: new → mapped; ContentIdeas: new → queued → completed.
• Disabled flag excludes records from automation queries.

Error Handling

• Validation errors for missing site/sector or seed keyword; industry/sector mismatch raises validation errors in Keywords.
• Bulk operations return 400 when IDs/status missing; generic errors return unified 500 responses.

Tenancy Rules

• All planner models inherit tenant/site/sector fields; base viewsets filter accordingly. Admin/developer/system accounts can bypass filtering; persisted data retains tenant/site/sector ownership.
• Create paths require explicit site/sector; account set from site/user/middleware.

Billing Rules

• Planner endpoints do not directly deduct credits; AI-based clustering/idea generation uses billing when invoked via services/automation.

Background Tasks / Schedulers

• None in planner endpoints; automation runs stages asynchronously using planner data.

Key Design Considerations

• Strict site/sector + seed alignment prevents cross-site contamination.
• Read-only seed-derived fields avoid drift while allowing per-site overrides.
• Bulk endpoints and range filters support large keyword sets efficiently.

How Developers Should Work With This Module

• Use existing serializers/viewsets to add fields or validations; keep site/sector required on create.
• When adding AI-powered planner actions, ensure credit checks go through billing services and queries respect tenant/site/sector scoping.
• Clean up duplicate bulk_update definitions if extending bulk behaviors to avoid route collisions.