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