igny8/docs/20-API/WRITER-ENDPOINTS.md

Writer Endpoints

Purpose

Document writer API endpoints for tasks, content, images, and taxonomies, including bulk actions and AI content generation triggers.

Code Locations (exact paths)

• Routing: backend/igny8_core/modules/writer/urls.py
• Views: backend/igny8_core/modules/writer/views.py
• Serializers: backend/igny8_core/modules/writer/serializers.py
• Services: backend/igny8_core/business/content/services/content_generation_service.py

High-Level Responsibilities

• CRUD for writer entities scoped by account/site/sector.
• Provide bulk operations and AI content generation for tasks.
• Manage images and taxonomy terms linked to content/tasks.

Detailed Behavior

• Base path: /api/v1/writer/
• Viewsets (inherit SiteSectorModelViewSet, throttled writer, paginated):
  • TasksViewSet (/tasks/):
    • Filters: status, cluster_id, content_type, content_structure; search title/keywords; ordering by title/created_at/status.
    • Bulk: bulk_delete, bulk_update (status).
    • auto_generate_content: accepts task IDs (max 10), requires account, enforces credit checks via ContentGenerationService, returns async task_id or synchronous result; 402 on insufficient credits.
    • Create requires site_id/sector_id; validates site/sector alignment; sets account/site/sector explicitly.
  • ImagesViewSet (/images/):
    • Filters: task_id, content_id, image_type, status; ordering by created_at/position/id.
    • perform_create enforces site/sector presence (from request or defaults), sets account/site/sector; serves local files via file action with existence checks.
  • ContentViewSet (/content/):
    • Filters/order/search defined in viewset (titles, status, etc.); manages taxonomy relationships; exposes status, SEO fields, cluster link, external IDs/URLs.
  • ContentTaxonomyViewSet (/taxonomies/):
    • CRUD for taxonomy terms (category/tag) scoped to site/sector.
• Serializers enforce required fields on create (e.g., cluster/content_type/content_structure for tasks; site/sector for content) and expose read-only derived fields (cluster/sector names, image/taxonomy info).
• Error handling: unified responses; validation errors return 400; missing resources return 404; auto_generate_content can return 402/500 on credits/other errors.

Data Structures / Models Involved (no code)

• Tasks, Content, Images, ContentTaxonomy, and related domain models; Account, Site, Sector.

Execution Flow

• Requests → DRF auth → base viewset filtering (account/site/sector) → serializer validation → model save → unified response; bulk/AI actions invoke services.

Cross-Module Interactions

• Planner clusters/ideas feed tasks; automation stages 3–6 operate on writer data; publishing/integration uses content/taxonomies/images.
• Billing credits enforced during AI content generation via ContentGenerationService.

State Transitions

• Tasks: queued → completed; Content: draft → review → published; Images: pending → generated.

Error Handling

• Standard unified responses; credit errors mapped to 402 in auto_generate_content; file serving returns 404 for missing images.

Tenancy Rules

• All endpoints scoped to account/site/sector; base viewset and permissions enforce access; admin/developer/system may bypass filtering but records retain tenant/site/sector fields.

Billing Rules

• AI generation actions check/deduct credits via billing services; other CRUD does not alter credits.

Background Tasks / Schedulers

• auto_generate_content may enqueue Celery AI tasks when returning task_id; automation uses writer endpoints indirectly via services.

Key Design Considerations

• Strict site/sector validation on create; max 10 tasks per auto_generate_content to manage load/credits.
• Image file serving is permissive but guarded by existence checks.

How Developers Should Work With This Module

• Supply site_id/sector_id on create; use bulk actions for batch changes.
• When extending AI flows, keep credit checks and account/site scoping intact.
• Reuse existing viewsets/serializers for new fields; ensure filters/throttles stay aligned with module scope.