igny8/master-docs/10-backend/writer/WRITER-OVERVIEW.md

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.