salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs re-org

Browse Source
This commit is contained in:
IGNY8 VPS (Salman)
2025-12-09 13:26:35 +00:00
parent 4d13a57068
commit 6a4f95c35a
231 changed files with 11353 additions and 31152 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
docs/90-ARCHIVED/master-docs-original/10-backend/planner/PLANNER-MODELS-AND-FLOW.md Normal file
View File

@@ -0,0 +1,69 @@
# 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.