83 lines
6.6 KiB
Markdown
83 lines
6.6 KiB
Markdown
# Writer Overview
|
||
|
||
## Purpose
|
||
Describe how the writer module manages tasks, content, images, and taxonomies, including validations, tenancy, and API behaviors.
|
||
|
||
## Code Locations (exact paths)
|
||
- Models: `backend/igny8_core/business/content/models.py`
|
||
- Serializers: `backend/igny8_core/modules/writer/serializers.py`
|
||
- Views: `backend/igny8_core/modules/writer/views.py`
|
||
- URLs: `backend/igny8_core/modules/writer/urls.py`
|
||
- Services: `backend/igny8_core/business/content/services/content_generation_service.py`, `validation_service.py`, `metadata_mapping_service.py`
|
||
- Automation linkages: `backend/igny8_core/business/automation/services/automation_service.py` (stages 3–6)
|
||
|
||
## High-Level Responsibilities
|
||
- Manage tenant/site/sector-scoped tasks, generated/imported content, images, and taxonomies.
|
||
- Provide CRUD and bulk operations for tasks and images; content generation triggers; taxonomy CRUD.
|
||
- Enforce site/sector alignment on creation and propagate account/site/sector to related records.
|
||
- Feed automation and publishing flows with content and images, and integrate with billing credits for AI operations.
|
||
|
||
## Detailed Behavior
|
||
- Models (all inherit tenant/site/sector bases; many soft-deletable):
|
||
- `Tasks`: queued work items tied to clusters/ideas/taxonomy; content type/structure; keywords text; word_count target; status `queued/completed`.
|
||
- `Content`: generated/imported content with HTML, SEO fields, cluster link, content type/structure, taxonomy M2M, external IDs/URLs/metadata, sync status, source (`igny8/wordpress`), status (`draft/review/published`), word_count, timestamps.
|
||
- `Images`: linked to content or task; auto-sets account/site/sector from provider; tracks type, URL/path, prompt, status, position.
|
||
- `ContentTaxonomy`: site/sector taxonomy terms (category/tag) with external taxonomy/id, sync status, description, count, metadata; unique per site by slug+type and by external id+taxonomy.
|
||
- Supporting: `ContentClusterMap`, `ContentAttribute` (documented in domain models).
|
||
- Serializers:
|
||
- `TasksSerializer`: requires cluster/content_type/content_structure on create; exposes cluster/sector names; write-only site_id/sector_id; defaults status to queued if absent.
|
||
- `ImagesSerializer`: exposes task/content titles; read-only derived fields; creation requires site/sector (validated, with fallback to request user active site default sector); sets account/site/sector via base perform_create.
|
||
- `ContentSerializer`: exposes cluster/sector names; taxonomy terms grouped (tags/categories); image status flags; write-only site_id/sector_id; validates presence of required fields and status transitions.
|
||
- Group serializers for images support grouped responses by content.
|
||
- Views:
|
||
- `TasksViewSet`: filters/search/order; bulk_delete, bulk_update status; `auto_generate_content` triggers `ContentGenerationService.generate_content` for up to 10 tasks, enforcing account presence and credit checks (returns 402 on `InsufficientCreditsError`); inherits tenant/site/sector filtering.
|
||
- `ImagesViewSet`: CRUD with ordering/filtering; perform_create enforces site/sector and populates context; `serve_image_file` serves local files with basic checks.
|
||
- `ContentViewSet`: CRUD for content; ordering/filtering; handles taxonomy assignments; exposes status/SEO fields; uses base scoping.
|
||
- `ContentTaxonomyViewSet`: CRUD for taxonomy terms (category/tag) scoped to site/sector; inherits base scoping.
|
||
- Services:
|
||
- `ContentGenerationService`: invoked by `auto_generate_content`; orchestrates AI content generation for tasks, returns async task_id when queued or synchronous result; raises `InsufficientCreditsError` on low balance.
|
||
- `ContentValidationService`, `MetadataMappingService`: additional processing/validation/mapping (used in writer flows and publishing).
|
||
- Automation linkage:
|
||
- Stage 3 creates tasks from ideas; Stage 4 generates content; Stage 5 generates image prompts; Stage 6 generates images and moves content to review.
|
||
|
||
## Data Structures / Models Involved (no code)
|
||
- `Tasks`, `Content`, `Images`, `ContentTaxonomy`, plus `ContentClusterMap`/`ContentAttribute`.
|
||
- Tenancy entities: `Account`, `Site`, `Sector`.
|
||
|
||
## Execution Flow
|
||
- Requests → DRF auth → `SiteSectorModelViewSet` filtering → serializer validation (site/sector required on create) → model save → unified response.
|
||
- `auto_generate_content` validates task IDs/account, calls service → service may enqueue Celery AI tasks or run synchronously → response with task_id or result.
|
||
- Images creation auto-inherits account/site/sector from linked task/content; local file serving bypasses account filter for read-only access.
|
||
|
||
## Cross-Module Interactions
|
||
- Planner clusters/ideas feed tasks; tasks/content/images feed publishing and automation stages.
|
||
- Billing credits enforced via `ContentGenerationService` when AI is used; automation aggregates credits used per stage from AI task logs.
|
||
- Integration/publishing sync uses content/taxonomy/image data when pushing to external platforms.
|
||
|
||
## State Transitions
|
||
- Tasks: `queued` → `completed`; Content: `draft` → `review` → `published`; Images: `pending` → `generated`; Taxonomies created/updated/deleted via CRUD.
|
||
|
||
## Error Handling
|
||
- Viewsets return unified errors; bulk operations validate IDs/status; `auto_generate_content` returns 400/404/402/500 depending on validation, missing tasks, insufficient credits, or unexpected errors.
|
||
- Images file serving returns 404 on missing file/image.
|
||
|
||
## Tenancy Rules
|
||
- Base viewset filters enforce account/site/sector scoping; admins/developers/system can bypass filtering; persisted records retain tenant/site/sector ownership.
|
||
- Creation requires site/sector; account set from request/site/user; Images perform_create validates presence of site/sector.
|
||
|
||
## Billing Rules
|
||
- AI content generation is guarded by credit checks; InsufficientCredits returns HTTP 402; credit logging occurs in billing services at AI call sites.
|
||
|
||
## Background Tasks / Schedulers
|
||
- AI generation may run via Celery when `ContentGenerationService` returns a task_id; automation stages run inside Celery workers for bulk flows.
|
||
|
||
## Key Design Considerations
|
||
- Strict site/sector requirements prevent cross-site contamination.
|
||
- Bulk limits (max 10 tasks in auto_generate_content) to control credit burn and processing load.
|
||
- Image serving permits public access via endpoint while still performing existence checks.
|
||
|
||
## How Developers Should Work With This Module
|
||
- Use existing serializers/viewsets; keep site/sector required on create.
|
||
- When extending AI generation, ensure billing checks (`CreditService`) and account/site scoping are preserved.
|
||
- For new bulk actions, follow current patterns: validate input, operate on filtered queryset, return unified responses.
|