docs re-org

docs/10-BACKEND/writer/WRITER-REFERENCE.md

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