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