81 lines
5.8 KiB
Markdown
81 lines
5.8 KiB
Markdown
# Planner Overview
|
||
|
||
## Purpose
|
||
Explain how the planner module manages keywords, clusters, and content ideas, including tenancy, validation, and API behaviors.
|
||
|
||
## 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`
|
||
- URLs: `backend/igny8_core/modules/planner/urls.py`
|
||
- Services: `backend/igny8_core/business/planning/services/clustering_service.py`, `ideas_service.py`
|
||
|
||
## High-Level Responsibilities
|
||
- Store site/sector-scoped keywords, clusters, and content ideas linked to global seed keywords.
|
||
- Provide CRUD and bulk operations for keywords/clusters/ideas with search, filter, and ordering.
|
||
- Validate industry/sector alignment between seed keywords and site/sector.
|
||
- Feed downstream writer/automation stages with structured ideas and clusters.
|
||
|
||
## Detailed Behavior
|
||
- Models (site/sector scoped via `SiteSectorBaseModel` and soft-delete):
|
||
- `Keywords`: references global `SeedKeyword`; optional volume/difficulty overrides; optional cluster; status `new/mapped`; disabled flag; validation ensures seed keyword industry/sector match the site/sector.
|
||
- `Clusters`: topic groups with counts, volume, mapped_pages, status `new/mapped`; unique per site/sector by name.
|
||
- `ContentIdeas`: ideas tied to clusters and optional keyword objects; status `new/queued/completed`; content_type/structure and estimated_word_count; disabled flag.
|
||
- Serializers:
|
||
- `KeywordSerializer` enforces `seed_keyword_id` on create; exposes seed keyword-derived fields (keyword/volume/difficulty/intent) read-only; optional overrides; includes site_id/sector_id write-only; provides cluster/sector names via getters; optional `attribute_values` when `USE_SITE_BUILDER_REFACTOR` flag is enabled.
|
||
- `ClusterSerializer` exposes site/sector IDs, sector name, read-only counts/volume/mapped_pages.
|
||
- `ContentIdeasSerializer` exposes cluster/sector names, content type/structure, keyword/target fields, site/sector write-only.
|
||
- Views (`KeywordViewSet`, `ClusterViewSet`, `ContentIdeasViewSet`):
|
||
- Inherit `SiteSectorModelViewSet` for tenant/site/sector filtering and unified responses.
|
||
- Permissions: `IsAuthenticatedAndActive` + viewer-or-above (search/list CRUD).
|
||
- Pagination: `CustomPageNumberPagination`; throttle scope `planner`.
|
||
- Filters/Search/Ordering: keywords searchable by seed_keyword.keyword; filter by status, cluster_id, seed intent; ordering by created_at, volume, difficulty; custom range filters for difficulty/volume; clusters filter by status; ideas filter by status/cluster.
|
||
- Creation requires explicit `site_id` and `sector_id`; viewsets validate site/sector existence and alignment; set `account/site/sector` explicitly on save.
|
||
- Bulk endpoints:
|
||
- Keywords: `bulk_delete`, two definitions of `bulk_update` (status update) present; `bulk_add_from_seed` to create Keywords from SeedKeywords with site/sector validation.
|
||
- Clusters: bulk update endpoints in view (not shown above) adjust status.
|
||
- Ideas: creation and status updates follow standard CRUD; not shown as bulk endpoints in code snippet.
|
||
- Error handling: viewsets wrap errors into unified responses; return 400/404/500 as appropriate.
|
||
- Services:
|
||
- `ClusteringService` and `IdeasService` (not detailed here) provide additional business logic for clustering/idea generation when invoked by automation or endpoints.
|
||
|
||
## Data Structures / Models Involved (no code)
|
||
- `Keywords`, `Clusters`, `ContentIdeas`; global `SeedKeyword`.
|
||
- Tenancy entities: `Account`, `Site`, `Sector`.
|
||
|
||
## Execution Flow
|
||
- Requests → DRF auth → `SiteSectorModelViewSet` filters by account/site/sector → serializers validate seed/site/sector alignment → models persisted → responses returned via unified helpers; bulk actions operate on filtered querysets.
|
||
|
||
## Cross-Module Interactions
|
||
- Automation stages 1–3 consume planner data (keywords → clusters → ideas → tasks).
|
||
- Writer tasks reference clusters/ideas produced here.
|
||
- Billing credits may be checked upstream for AI clustering/idea generation (via services invoked in automation or planner actions).
|
||
|
||
## State Transitions
|
||
- Keywords: `new` → `mapped`; Clusters: `new` → `mapped`; ContentIdeas: `new` → `queued` → `completed`.
|
||
- Disabled flag can exclude records from processes.
|
||
|
||
## Error Handling
|
||
- Validation enforces seed/site/sector industry alignment; missing site/sector on create raises validation errors.
|
||
- Bulk operations return 400 on missing IDs/status; general errors return unified 500 responses.
|
||
|
||
## Tenancy Rules
|
||
- All planner models inherit `SiteSectorBaseModel`; queries are filtered by account/site/sector; admin/developer/system roles can bypass filtering via base viewset logic.
|
||
- Create requires explicit site and sector; viewsets fetch and set account from site/user/middleware.
|
||
|
||
## Billing Rules
|
||
- None directly in the planner endpoints; credit costs for clustering/idea generation are enforced where those services are called (automation or planner service usage).
|
||
|
||
## Background Tasks / Schedulers
|
||
- Planner endpoints run synchronously; automation may batch planner data into AI tasks via Celery (documented in automation).
|
||
|
||
## Key Design Considerations
|
||
- Strict site/sector validation prevents cross-tenant or cross-site leaks.
|
||
- Seed keyword linkage centralizes keyword metadata; overrides allow per-site tuning.
|
||
- Pagination/filtering/search are optimized for large keyword sets.
|
||
|
||
## How Developers Should Work With This Module
|
||
- Use provided viewsets and serializers; ensure site_id/sector_id are supplied on create.
|
||
- When adding fields, extend serializers with read-only/write-only behavior consistent with current patterns.
|
||
- For new bulk operations, follow existing patterns: validate IDs, operate on filtered queryset, return unified responses.
|