salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f255e3c0a02b0ca1c08af73f6a05d3c1ea8ab077
igny8/master-docs/04-BACKEND-IMPLEMENTATION.md

38 KiB
Raw Blame History

IGNY8 Backend Implementation Reference

Last Updated: 2025-01-XX (Added 6 missing modules: Linker, Optimizer, Publisher, Site Builder, Automation, Integration)
Purpose: Complete backend implementation reference covering project structure, models, ViewSets, serializers, Celery tasks, API endpoints, base classes, middleware, and utilities.

Table of Contents

  1. Backend Overview
  2. Tech Stack
  3. Project Structure
  4. Models
  5. ViewSets
  6. Serializers
  7. Celery Tasks
  8. API Endpoints
  9. Base Classes
  10. Middleware
  11. Utilities
  12. Modules

Backend Overview

The IGNY8 backend is a Django 5.2+ application using Django REST Framework (DRF) for API endpoints. The backend follows a modular architecture with clear separation of concerns, automatic account isolation, and support for asynchronous task processing via Celery.

Key Features

  • Multi-Tenancy: Complete account isolation with automatic filtering
  • RESTful API: DRF ViewSets with consistent response format
  • Celery Integration: Asynchronous task processing for long-running operations
  • Account/Site/Sector Hierarchy: Hierarchical data organization
  • AI Integration: Unified AI framework for all AI operations
  • Progress Tracking: Real-time progress updates for Celery tasks

Tech Stack

Core Technologies

  • Django 5.2+: Web framework
  • Django REST Framework: API framework
  • PostgreSQL: Database
  • Celery: Asynchronous task queue
  • Redis: Celery broker and caching

Key Libraries

  • django-filter: Advanced filtering
  • djangorestframework-simplejwt: JWT authentication
  • requests: HTTP client for external APIs
  • python-dotenv: Environment variable management

Project Structure

backend/igny8_core/
├── auth/                     # Multi-tenancy and authentication
│   ├── models.py             # Account, User, Plan, Site, Sector, Industry models
│   ├── views.py              # Account, User, Site, Sector ViewSets
│   ├── serializers.py        # Account, User, Plan serializers
│   └── urls.py               # Auth module URLs
├── modules/                  # Feature modules
│   ├── planner/              # Keywords, Clusters, Ideas
│   │   ├── views.py          # KeywordViewSet, ClusterViewSet, ContentIdeasViewSet
│   │   ├── serializers.py    # Model serializers
│   │   └── urls.py           # Planner module URLs
│   ├── writer/               # Tasks, Content, Images
│   │   ├── views.py          # TasksViewSet, ContentViewSet, ImagesViewSet
│   │   ├── serializers.py    # Model serializers
│   │   └── urls.py           # Writer module URLs
│   ├── linker/               # Internal linking
│   │   ├── views.py          # LinkerViewSet
│   │   ├── serializers.py    # Link serializers
│   │   └── urls.py           # Linker module URLs
│   ├── optimizer/            # Content optimization
│   │   ├── views.py          # OptimizerViewSet
│   │   ├── serializers.py    # Optimizer serializers
│   │   └── urls.py           # Optimizer module URLs
│   ├── publisher/            # Publishing & deployment
│   │   ├── views.py          # PublishingRecordViewSet, DeploymentRecordViewSet, PublisherViewSet
│   │   └── urls.py           # Publisher module URLs
│   ├── site_builder/         # Site blueprint management
│   │   ├── views.py          # SiteBlueprintViewSet, PageBlueprintViewSet, SiteAssetView
│   │   ├── serializers.py    # Site builder serializers
│   │   └── urls.py           # Site Builder module URLs
│   ├── automation/           # Automation rules
│   │   ├── views.py          # AutomationRuleViewSet, ScheduledTaskViewSet
│   │   ├── serializers.py   # Automation serializers
│   │   └── urls.py           # Automation module URLs
│   ├── integration/          # External integrations
│   │   ├── views.py          # IntegrationViewSet
│   │   └── urls.py           # Integration module URLs
│   ├── system/               # Settings, Prompts, Integration
│   │   ├── models.py         # AIPrompt, IntegrationSettings, AuthorProfile, Strategy
│   │   ├── views.py          # AIPromptViewSet, AuthorProfileViewSet
│   │   ├── settings_views.py # SystemSettingsViewSet, AccountSettingsViewSet
│   │   ├── integration_views.py  # IntegrationSettingsViewSet, task_progress
│   │   ├── utils.py          # Default prompts, prompt loading
│   │   └── urls.py           # System module URLs
│   └── billing/              # Credits, Transactions, Usage
│       ├── views.py          # CreditTransactionViewSet, CreditBalanceViewSet, CreditUsageViewSet
│       ├── services.py       # CreditService
│       └── urls.py           # Billing module URLs
├── business/                 # Business logic layer
│   ├── planning/             # Planner models (Keywords, Clusters, ContentIdeas)
│   ├── content/              # Writer models (Tasks, Content, Images)
│   ├── linking/              # Linker services
│   ├── optimization/        # Optimizer services
│   ├── publishing/           # Publisher models (PublishingRecord, DeploymentRecord)
│   ├── site_building/        # Site Builder models (SiteBlueprint, PageBlueprint, etc.)
│   ├── automation/           # Automation models (AutomationRule, ScheduledTask)
│   ├── integration/          # Integration models (SiteIntegration)
│   └── billing/              # Billing models (CreditTransaction, CreditUsageLog)
├── api/                      # API base classes
│   ├── base.py               # AccountModelViewSet, SiteSectorModelViewSet
│   └── pagination.py         # CustomPageNumberPagination
├── utils/                    # Shared utilities
│   ├── ai_processor.py       # Unified AI interface (legacy, see AI functions)
│   └── content_normalizer.py # Content processing utilities
├── middleware/               # Custom middleware
│   ├── account.py            # AccountContextMiddleware (sets request.account)
│   └── resource_tracker.py   # ResourceTrackerMiddleware (API metrics)
├── ai/                       # AI framework
│   ├── base.py               # BaseAIFunction
│   ├── engine.py             # AIEngine
│   ├── tasks.py              # run_ai_task
│   ├── registry.py           # Function registry
│   ├── prompts.py            # PromptRegistry
│   ├── ai_core.py            # AICore
│   ├── settings.py           # Model configuration
│   ├── validators.py         # Validation functions
│   ├── tracker.py            # Progress tracking
│   └── functions/            # AI function implementations
│       ├── auto_cluster.py
│       ├── generate_ideas.py
│       ├── generate_content.py
│       ├── generate_image_prompts.py
│       └── generate_images.py
├── settings.py               # Django settings
├── urls.py                   # Root URL configuration
└── celery.py                 # Celery configuration

Models

Base Models

AccountBaseModel

File: auth/models.py

Purpose: Base model for all account-isolated models.

Fields:

  • account: ForeignKey to Account
  • created_at: DateTimeField (auto_now_add)
  • updated_at: DateTimeField (auto_now)

Usage: All models that need account isolation inherit from this.

SiteSectorBaseModel

File: auth/models.py

Purpose: Base model for models that belong to Site and Sector.

Fields:

  • Inherits from AccountBaseModel
  • site: ForeignKey to Site
  • sector: ForeignKey to Sector

Methods:

  • save(): Automatically sets account from site.account and validates sector belongs to site

Usage: Models like Keywords, Clusters, ContentIdeas, Tasks inherit from this.

Auth Models

Account

Table: igny8_accounts

Fields:

  • name: CharField
  • slug: SlugField (unique)
  • owner: ForeignKey to User
  • plan: ForeignKey to Plan
  • credits: IntegerField (default: 0)
  • status: CharField (choices: active, suspended, trial, cancelled)

Methods:

  • is_system_account(): Returns True if account is a system account

User

Table: igny8_users

Inherits: AbstractUser

Fields:

  • email: EmailField (unique)
  • account: ForeignKey to Account
  • role: CharField (choices: developer, owner, admin, editor, viewer, system_bot)

Methods:

  • has_role(role): Checks if user has role
  • is_owner_or_admin(): Checks if user is owner or admin
  • is_developer(): Checks if user is developer
  • is_admin_or_developer(): Checks if user is admin or developer
  • is_system_account_user(): Checks if user belongs to system account
  • get_accessible_sites(): Returns queryset of accessible sites

Plan

Table: igny8_plans

Fields: Extensive fields for limits (users, sites, keywords, clusters, content ideas, AI requests, word count, images, credits)

Methods:

  • clean(): Validates plan limits
  • get_effective_credits_per_month(): Returns included_credits or credits_per_month

Site

Table: igny8_sites

Inherits: AccountBaseModel

Fields:

  • name: CharField
  • slug: SlugField (unique per account)
  • domain: URLField (optional)
  • industry: ForeignKey to Industry (optional)
  • is_active: BooleanField
  • status: CharField
  • wp_url: URLField (optional)
  • wp_username: CharField (optional)
  • wp_app_password: CharField (optional)

Methods:

  • get_active_sectors_count(): Returns count of active sectors
  • can_add_sector(): Returns True if site can add another sector (max 5)

Sector

Table: igny8_sectors

Inherits: AccountBaseModel

Fields:

  • site: ForeignKey to Site
  • industry_sector: ForeignKey to IndustrySector (optional)
  • name: CharField
  • slug: SlugField (unique per site)
  • is_active: BooleanField
  • status: CharField

Validation: Maximum 5 active sectors per site

Planner Models

Keywords

Table: igny8_keywords

Inherits: SiteSectorBaseModel

Fields:

  • keyword: CharField
  • volume: IntegerField (optional)
  • difficulty: IntegerField (optional)
  • intent: CharField (optional)
  • status: CharField
  • cluster: ManyToManyField to Clusters

Clusters

Table: igny8_clusters

Inherits: SiteSectorBaseModel

Fields:

  • name: CharField
  • description: TextField (optional)
  • keywords_count: IntegerField (calculated)
  • volume: IntegerField (calculated)
  • status: CharField
  • keywords: ManyToManyField to Keywords

ContentIdeas

Table: igny8_content_ideas

Inherits: SiteSectorBaseModel

Fields:

  • idea_title: CharField
  • description: TextField
  • content_type: CharField
  • content_structure: CharField
  • target_keywords: TextField
  • keyword_cluster: ForeignKey to Clusters
  • estimated_word_count: IntegerField
  • status: CharField

Writer Models

Tasks

Table: igny8_tasks

Inherits: SiteSectorBaseModel

Fields:

  • title: CharField
  • description: TextField
  • cluster: ForeignKey to Clusters (optional)
  • idea: ForeignKey to ContentIdeas (optional)
  • content_type: CharField
  • content_structure: CharField
  • status: CharField

Content

Table: igny8_content

Inherits: SiteSectorBaseModel

Fields:

  • task: OneToOneField to Tasks
  • html_content: TextField
  • word_count: IntegerField
  • status: CharField
  • wp_post_id: IntegerField (optional)
  • meta_title: CharField (optional)
  • meta_description: TextField (optional)
  • primary_keyword: CharField (optional)
  • secondary_keywords: TextField (optional)

Images

Table: igny8_images

Inherits: SiteSectorBaseModel

Fields:

  • task: ForeignKey to Tasks (optional)
  • content: ForeignKey to Content (optional)
  • image_type: CharField (choices: featured, in_article, desktop, mobile)
  • prompt: TextField
  • image_url: CharField
  • status: CharField

System Models

AIPrompt

Table: igny8_ai_prompts

Inherits: AccountBaseModel

Fields:

  • prompt_type: CharField
  • prompt_value: TextField
  • function_name: CharField (optional)

IntegrationSettings

Table: igny8_integration_settings

Inherits: AccountBaseModel

Fields:

  • integration_type: CharField (choices: openai, runware, image_generation)
  • config: JSONField

AuthorProfile

Table: igny8_author_profiles

Inherits: AccountBaseModel

Fields:

  • name: CharField
  • description: TextField
  • tone: CharField
  • language: CharField

Strategy

Table: igny8_strategies

Inherits: AccountBaseModel

Fields:

  • name: CharField
  • description: TextField
  • sector: ForeignKey to Sector (optional)
  • prompt_types: JSONField
  • section_logic: JSONField
  • is_active: BooleanField

Billing Models

CreditTransaction

Table: igny8_credit_transactions

Inherits: AccountBaseModel

Fields:

  • transaction_type: CharField (choices: purchase, usage, refund, adjustment)
  • amount: IntegerField
  • balance_after: IntegerField
  • description: TextField (optional)

CreditUsageLog

Table: igny8_credit_usage_logs

Inherits: AccountBaseModel

Fields:

  • operation_type: CharField
  • credits_used: IntegerField
  • cost_usd: DecimalField
  • details: JSONField (optional)

ViewSets

Base ViewSets

AccountModelViewSet

File: api/base.py

Purpose: Base ViewSet with automatic account filtering.

Methods:

  • get_queryset(): Filters queryset by request.account (with admin/developer override)
  • perform_create(): Sets account on created objects
  • get_serializer_context(): Adds account to serializer context

Access Control:

  • Admin/Developer users: Bypass account filtering
  • System account users: Bypass account filtering
  • Regular users: Only see data from their account

SiteSectorModelViewSet

File: api/base.py

Purpose: Base ViewSet with site/sector filtering and access control.

Inherits: AccountModelViewSet

Methods:

  • get_queryset(): Filters by account, accessible sites, and optional site_id/sector_id
  • perform_create(): Validates site access and sector-site relationship
  • get_serializer_context(): Adds accessible sites and sectors to context

Access Control:

  • Developers: All active sites
  • System account users: All active sites
  • Owners/Admins: All sites in their account
  • Editors/Viewers: Only sites granted via SiteUserAccess

Planner ViewSets

KeywordViewSet

Inherits: SiteSectorModelViewSet

Actions:

  • list(): List keywords with filtering
  • create(): Create keyword
  • retrieve(): Get keyword details
  • update(): Update keyword
  • destroy(): Delete keyword
  • auto_cluster(): Auto-cluster keywords using AI
  • bulk_delete(): Bulk delete keywords
  • bulk_update_status(): Bulk update keyword status
  • export_csv(): Export keywords to CSV
  • import_csv(): Import keywords from CSV

Filtering:

  • Search: keyword field
  • Filters: status, cluster_id, intent
  • Custom: difficulty_min, difficulty_max, volume_min, volume_max
  • Ordering: created_at, volume, difficulty

ClusterViewSet

Inherits: SiteSectorModelViewSet

Actions:

  • list(): List clusters
  • create(): Create cluster
  • retrieve(): Get cluster details
  • update(): Update cluster
  • destroy(): Delete cluster
  • auto_generate_ideas(): Auto-generate content ideas for clusters

ContentIdeasViewSet

Inherits: SiteSectorModelViewSet

Actions:

  • list(): List content ideas
  • create(): Create content idea
  • retrieve(): Get content idea details
  • update(): Update content idea
  • destroy(): Delete content idea

Writer ViewSets

TasksViewSet

Inherits: SiteSectorModelViewSet

Actions:

  • list(): List tasks
  • create(): Create task
  • retrieve(): Get task details
  • update(): Update task
  • destroy(): Delete task
  • auto_generate_content(): Auto-generate content for tasks
  • generate_images(): Generate images for image records
  • bulk_delete(): Bulk delete tasks
  • bulk_update(): Bulk update task status

Filtering:

  • Search: title, keywords
  • Filters: status, cluster_id, content_type, content_structure
  • Ordering: title, created_at, word_count, status

ContentViewSet

Inherits: SiteSectorModelViewSet

Actions:

  • list(): List content
  • create(): Create content
  • retrieve(): Get content details
  • update(): Update content
  • destroy(): Delete content
  • publish_to_wordpress(): Publish content to WordPress

ImagesViewSet

Inherits: SiteSectorModelViewSet

Actions:

  • list(): List images
  • create(): Create image
  • retrieve(): Get image details
  • update(): Update image
  • destroy(): Delete image
  • generate_images(): Generate images using AI

Linker ViewSets

LinkerViewSet

Inherits: viewsets.ViewSet

Actions:

  • process(): Process a single content item for internal linking
  • batch_process(): Process multiple content items for internal linking

Purpose: AI-powered internal linking suggestions based on cluster matches

Optimizer ViewSets

OptimizerViewSet

Inherits: viewsets.ViewSet

Actions:

  • optimize(): Optimize content (auto-detects entry point)
  • batch_optimize(): Batch optimize multiple content items
  • analyze(): Analyze content without optimization

Purpose: Content optimization and scoring

Publisher ViewSets

PublishingRecordViewSet

Inherits: SiteSectorModelViewSet

Actions:

  • list(): List publishing records
  • create(): Create publishing record
  • retrieve(): Get publishing record details
  • update(): Update publishing record
  • destroy(): Delete publishing record

DeploymentRecordViewSet

Inherits: SiteSectorModelViewSet

Actions:

  • list(): List deployment records
  • create(): Create deployment record
  • retrieve(): Get deployment record details
  • update(): Update deployment record
  • destroy(): Delete deployment record

PublisherViewSet

Inherits: viewsets.ViewSet

Actions:

  • publish(): Publish content to destination
  • deploy(): Deploy site blueprint
  • check_readiness(): Check deployment readiness

SiteDefinitionView

Inherits: APIView

Purpose: Public endpoint for Sites Renderer to fetch site definitions

Site Builder ViewSets

SiteBlueprintViewSet

Inherits: SiteSectorModelViewSet

Actions:

  • list(): List site blueprints
  • create(): Create site blueprint
  • retrieve(): Get site blueprint details
  • update(): Update site blueprint
  • destroy(): Delete site blueprint
  • generate_structure(): Generate site structure using AI
  • generate_all_pages(): Generate all pages for blueprint
  • create_tasks(): Create Writer tasks for pages
  • progress(): Get cluster-level completion status
  • attach_clusters(): Attach planner clusters to blueprint
  • detach_clusters(): Detach clusters from blueprint
  • list_taxonomies(): List taxonomies for blueprint
  • create_taxonomy(): Create taxonomy for blueprint
  • import_taxonomies(): Import taxonomies from external source
  • bulk_delete(): Bulk delete blueprints

PageBlueprintViewSet

Inherits: SiteSectorModelViewSet

Actions:

  • list(): List page blueprints
  • create(): Create page blueprint
  • retrieve(): Get page blueprint details
  • update(): Update page blueprint
  • destroy(): Delete page blueprint
  • generate_content(): Generate content for page
  • regenerate(): Regenerate page content

SiteAssetView

Inherits: APIView

Actions:

  • GET: List files for site
  • POST: Upload file
  • DELETE: Delete file

SiteBuilderMetadataView

Inherits: APIView

Actions:

  • GET: Get metadata (business types, audience profiles, brand personalities, hero imagery)

Automation ViewSets

AutomationRuleViewSet

Inherits: SiteSectorModelViewSet

Actions:

  • list(): List automation rules
  • create(): Create automation rule
  • retrieve(): Get automation rule details
  • update(): Update automation rule
  • destroy(): Delete automation rule
  • execute(): Manually execute automation rule

ScheduledTaskViewSet

Inherits: AccountModelViewSet

Actions:

  • list(): List scheduled tasks
  • create(): Create scheduled task
  • retrieve(): Get scheduled task details
  • update(): Update scheduled task
  • destroy(): Delete scheduled task

Integration ViewSets

IntegrationViewSet

Inherits: SiteSectorModelViewSet

Actions:

  • list(): List site integrations
  • create(): Create site integration
  • retrieve(): Get integration details
  • update(): Update integration
  • destroy(): Delete integration
  • test_connection(): Test connection to integrated platform
  • sync(): Sync content with integrated platform
  • sync_health(): Check sync health status

System ViewSets

IntegrationSettingsViewSet

Inherits: viewsets.ViewSet

Actions:

  • list(): List integrations
  • retrieve(): Get integration settings
  • update(): Save integration settings
  • save_post(): Save integration settings (POST)
  • test_connection(): Test API connection
  • test_openai(): Test OpenAI connection
  • test_runware(): Test Runware connection
  • generate_image(): Test image generation
  • task_progress(): Get Celery task progress

AIPromptViewSet

Inherits: AccountModelViewSet

Actions:

  • list(): List prompts
  • create(): Create prompt
  • retrieve(): Get prompt details
  • update(): Update prompt
  • destroy(): Delete prompt
  • reset_to_default(): Reset prompt to default value

AuthorProfileViewSet

Inherits: AccountModelViewSet

Actions:

  • list(): List author profiles
  • create(): Create author profile
  • retrieve(): Get author profile details
  • update(): Update author profile
  • destroy(): Delete author profile

Serializers

Planner Serializers

KeywordSerializer

Fields: All Keyword model fields

Validation: Validates keyword uniqueness, cluster belongs to same sector

ClusterSerializer

Fields: All Cluster model fields

Read-Only Fields: keywords_count, volume (calculated)

ContentIdeasSerializer

Fields: All ContentIdeas model fields

Writer Serializers

TasksSerializer

Fields: All Tasks model fields

ContentSerializer

Fields: All Content model fields

ImagesSerializer

Fields: All Images model fields

System Serializers

AIPromptSerializer

Fields: All AIPrompt model fields

IntegrationSettingsSerializer

Fields: All IntegrationSettings model fields

Linker Serializers

LinkContentSerializer

Fields: content_id

BatchLinkContentSerializer

Fields: content_ids (array)

Optimizer Serializers

OptimizeContentSerializer

Fields: content_id, entry_point (optional)

BatchOptimizeContentSerializer

Fields: content_ids (array), entry_point (optional)

AnalyzeContentSerializer

Fields: content_id

Publisher Serializers

PublishingRecordSerializer

Fields: All PublishingRecord model fields

DeploymentRecordSerializer

Fields: All DeploymentRecord model fields

Site Builder Serializers

SiteBlueprintSerializer

Fields: All SiteBlueprint model fields, includes nested pages

PageBlueprintSerializer

Fields: All PageBlueprint model fields

SiteBuilderMetadataSerializer

Fields: business_types, audience_profiles, brand_personalities, hero_imagery_directions

Automation Serializers

AutomationRuleSerializer

Fields: All AutomationRule model fields

ScheduledTaskSerializer

Fields: All ScheduledTask model fields

Integration Serializers

SiteIntegrationSerializer

Fields: All SiteIntegration model fields

Celery Tasks

AI Task Entry Point

run_ai_task

File: ai/tasks.py

Purpose: Unified Celery task entrypoint for all AI functions

Parameters:

  • function_name: Function name (e.g., 'auto_cluster')
  • payload: Function-specific payload
  • account_id: Account ID

Flow:

  1. Gets account from account_id
  2. Gets function instance from registry
  3. Creates AIEngine
  4. Executes function via AIEngine

Planner Tasks

auto_cluster_keywords_task

File: modules/planner/tasks.py (legacy, now uses run_ai_task)

Purpose: Auto-cluster keywords using AI

Parameters:

  • keyword_ids: List of keyword IDs
  • account_id: Account ID
  • site_id: Site ID
  • sector_id: Sector ID

Progress Tracking: Updates progress with request_steps and response_steps

auto_generate_ideas_task

File: modules/planner/tasks.py (legacy, now uses run_ai_task)

Purpose: Auto-generate content ideas for clusters

Parameters:

  • cluster_ids: List of cluster IDs
  • account_id: Account ID

Progress Tracking: Updates progress for each cluster

Writer Tasks

auto_generate_content_task

File: modules/writer/tasks.py (legacy, now uses run_ai_task)

Purpose: Auto-generate content for tasks

Parameters:

  • task_ids: List of task IDs
  • account_id: Account ID

Progress Tracking: Updates progress for each task

process_image_generation_queue

File: modules/writer/views.py (via ai/tasks.py)

Purpose: Generate images for image records

Parameters:

  • image_ids: List of image IDs
  • account_id: Account ID
  • content_id: Content ID (optional)

Progress Tracking: Updates progress for each image sequentially

API Endpoints

Base URL

/api/v1/

Planner Endpoints

  • GET /api/v1/planner/keywords/ - List keywords
  • POST /api/v1/planner/keywords/ - Create keyword
  • GET /api/v1/planner/keywords/{id}/ - Get keyword
  • PUT /api/v1/planner/keywords/{id}/ - Update keyword
  • DELETE /api/v1/planner/keywords/{id}/ - Delete keyword
  • POST /api/v1/planner/keywords/auto_cluster/ - Auto-cluster keywords
  • POST /api/v1/planner/keywords/bulk_delete/ - Bulk delete keywords
  • POST /api/v1/planner/keywords/bulk_update_status/ - Bulk update status
  • GET /api/v1/planner/keywords/export_csv/ - Export keywords
  • POST /api/v1/planner/keywords/import_csv/ - Import keywords
  • GET /api/v1/planner/clusters/ - List clusters
  • POST /api/v1/planner/clusters/auto_generate_ideas/ - Auto-generate ideas
  • GET /api/v1/planner/ideas/ - List content ideas

Writer Endpoints

  • GET /api/v1/writer/tasks/ - List tasks
  • POST /api/v1/writer/tasks/ - Create task
  • GET /api/v1/writer/tasks/{id}/ - Get task details
  • POST /api/v1/writer/tasks/auto_generate_content/ - Auto-generate content
  • GET /api/v1/writer/content/ - List content
  • GET /api/v1/writer/content/{id}/ - Get content details
  • POST /api/v1/writer/images/generate_images/ - Generate images

Linker Endpoints

  • POST /api/v1/linker/process/ - Process content for internal linking
  • POST /api/v1/linker/batch_process/ - Batch process content for linking

Optimizer Endpoints

  • POST /api/v1/optimizer/optimize/ - Optimize content
  • POST /api/v1/optimizer/batch_optimize/ - Batch optimize content
  • POST /api/v1/optimizer/analyze/ - Analyze content

Publisher Endpoints

  • GET /api/v1/publisher/publishing-records/ - List publishing records
  • POST /api/v1/publisher/publishing-records/ - Create publishing record
  • GET /api/v1/publisher/deployments/ - List deployment records
  • POST /api/v1/publisher/deployments/ - Create deployment record
  • POST /api/v1/publisher/publish/ - Publish content
  • POST /api/v1/publisher/deploy/ - Deploy site blueprint
  • GET /api/v1/publisher/sites/{site_id}/definition/ - Get site definition (public)

Site Builder Endpoints

  • GET /api/v1/site-builder/blueprints/ - List site blueprints
  • POST /api/v1/site-builder/blueprints/ - Create site blueprint
  • GET /api/v1/site-builder/blueprints/{id}/ - Get blueprint details
  • POST /api/v1/site-builder/blueprints/{id}/generate_structure/ - Generate structure
  • POST /api/v1/site-builder/blueprints/{id}/generate_all_pages/ - Generate all pages
  • POST /api/v1/site-builder/blueprints/{id}/create_tasks/ - Create tasks for pages
  • GET /api/v1/site-builder/blueprints/{id}/progress/ - Get progress
  • POST /api/v1/site-builder/blueprints/{id}/clusters/attach/ - Attach clusters
  • POST /api/v1/site-builder/blueprints/{id}/clusters/detach/ - Detach clusters
  • GET /api/v1/site-builder/blueprints/{id}/taxonomies/ - List taxonomies
  • POST /api/v1/site-builder/blueprints/{id}/taxonomies/ - Create taxonomy
  • POST /api/v1/site-builder/blueprints/{id}/taxonomies/import/ - Import taxonomies
  • POST /api/v1/site-builder/blueprints/bulk_delete/ - Bulk delete blueprints
  • GET /api/v1/site-builder/pages/ - List page blueprints
  • POST /api/v1/site-builder/pages/ - Create page blueprint
  • GET /api/v1/site-builder/pages/{id}/ - Get page details
  • POST /api/v1/site-builder/pages/{id}/generate_content/ - Generate content
  • POST /api/v1/site-builder/pages/{id}/regenerate/ - Regenerate page
  • GET /api/v1/site-builder/assets/ - List assets
  • POST /api/v1/site-builder/assets/ - Upload asset
  • DELETE /api/v1/site-builder/assets/ - Delete asset
  • GET /api/v1/site-builder/metadata/ - Get metadata

Automation Endpoints

  • GET /api/v1/automation/rules/ - List automation rules
  • POST /api/v1/automation/rules/ - Create automation rule
  • GET /api/v1/automation/rules/{id}/ - Get rule details
  • POST /api/v1/automation/rules/{id}/execute/ - Execute rule
  • GET /api/v1/automation/scheduled-tasks/ - List scheduled tasks
  • POST /api/v1/automation/scheduled-tasks/ - Create scheduled task

Integration Endpoints

  • GET /api/v1/integration/integrations/ - List site integrations
  • POST /api/v1/integration/integrations/ - Create integration
  • GET /api/v1/integration/integrations/{id}/ - Get integration details
  • POST /api/v1/integration/integrations/{id}/test_connection/ - Test connection
  • POST /api/v1/integration/integrations/{id}/sync/ - Sync content
  • GET /api/v1/integration/integrations/{id}/sync_health/ - Get sync health

System Endpoints

  • GET /api/v1/system/settings/integrations/{pk}/ - Get integration settings
  • PUT /api/v1/system/settings/integrations/{pk}/ - Save integration settings
  • POST /api/v1/system/settings/integrations/{pk}/test_openai/ - Test OpenAI
  • POST /api/v1/system/settings/integrations/{pk}/test_runware/ - Test Runware
  • POST /api/v1/system/settings/integrations/{pk}/generate_image/ - Test image generation
  • GET /api/v1/system/settings/task_progress/{task_id}/ - Get task progress

Base Classes

AccountModelViewSet

File: api/base.py

Purpose: Base ViewSet with automatic account filtering

Features:

  • Automatic account filtering
  • Admin/Developer override
  • Account context in serializers

SiteSectorModelViewSet

File: api/base.py

Purpose: Base ViewSet with site/sector filtering

Features:

  • Account filtering (inherited)
  • Site access control
  • Sector validation
  • Accessible sites/sectors in serializer context

Middleware

AccountContextMiddleware

File: middleware/account.py

Purpose: Sets request.account from JWT token

Functionality:

  • Extracts account ID from JWT token
  • Loads Account object
  • Sets request.account

ResourceTrackerMiddleware

File: middleware/resource_tracker.py

Purpose: Tracks API request metrics

Functionality:

  • Tracks CPU, memory, I/O usage
  • Stores metrics in cache
  • Provides metrics endpoint

Utilities

Content Normalizer

File: utils/content_normalizer.py

Purpose: Content processing utilities

Functions:

  • normalize_content(): Converts plain text to HTML
  • _extract_body_content(): Extracts body content from HTML

Modules

Planner Module

Purpose: Keyword management and content planning

Models: Keywords, Clusters, ContentIdeas

ViewSets: KeywordViewSet, ClusterViewSet, ContentIdeasViewSet

Tasks: Auto-cluster keywords, Auto-generate ideas

Writer Module

Purpose: Content generation and management

Models (in business/content/):

  • Tasks: Content generation tasks
  • Content: Generated content pieces
  • Images: Generated images
  • ContentClusterMap: Content-to-cluster mapping
  • ContentTaxonomyMap: Content taxonomy mapping
  • ContentAttributeMap: Content attribute mapping

ViewSets:

  • TasksViewSet: CRUD + auto-generate content, bulk operations
  • ContentViewSet: CRUD + publish to WordPress
  • ImagesViewSet: CRUD + generate images

URLs: /api/v1/writer/

Linker Module

Purpose: Internal linking operations

ViewSets:

  • LinkerViewSet: Process content for internal linking

Actions:

  • process(): Process single content item
  • batch_process(): Process multiple content items

URLs: /api/v1/linker/

Optimizer Module

Purpose: Content optimization and scoring

ViewSets:

  • OptimizerViewSet: Content optimization operations

Actions:

  • optimize(): Optimize content (auto-detects entry point)
  • batch_optimize(): Batch optimize content
  • analyze(): Analyze content without optimization

URLs: /api/v1/optimizer/

Publisher Module

Purpose: Publishing records and site deployment

Models (in business/publishing/):

  • PublishingRecord: Records of content publishing
  • DeploymentRecord: Records of site deployments

ViewSets:

  • PublishingRecordViewSet: CRUD for publishing records
  • DeploymentRecordViewSet: CRUD for deployment records
  • PublisherViewSet: Publishing and deployment actions
  • SiteDefinitionView: Public endpoint for Sites Renderer

Actions:

  • publish(): Publish content to destination
  • deploy(): Deploy site blueprint
  • check_readiness(): Check deployment readiness

URLs: /api/v1/publisher/

Site Builder Module

Purpose: Site blueprint management

Models (in business/site_building/):

  • SiteBlueprint: Site structure definitions
  • PageBlueprint: Page structure definitions
  • SiteBlueprintCluster: Cluster-to-blueprint mapping
  • SiteBlueprintTaxonomy: Taxonomy definitions
  • SiteBuilderOption: Site builder configuration options

ViewSets:

  • SiteBlueprintViewSet: CRUD + structure generation, cluster management
  • PageBlueprintViewSet: CRUD + content generation
  • SiteAssetView: Asset management
  • SiteBuilderMetadataView: Metadata retrieval

Actions:

  • generate_structure(): Generate site structure using AI
  • generate_all_pages(): Generate all pages for blueprint
  • create_tasks(): Create Writer tasks for pages
  • progress(): Get cluster-level completion status
  • attach_clusters(): Attach planner clusters
  • detach_clusters(): Detach clusters
  • generate_content(): Generate content for page
  • regenerate(): Regenerate page content

URLs: /api/v1/site-builder/

Note: Site Builder Wizard UI has been removed. Only API-based blueprint management remains.

Automation Module

Purpose: Automation rules and scheduled tasks

Models (in business/automation/):

  • AutomationRule: Rule-based automation definitions
  • ScheduledTask: Scheduled task definitions

ViewSets:

  • AutomationRuleViewSet: CRUD + execute rule
  • ScheduledTaskViewSet: CRUD for scheduled tasks

Actions:

  • execute(): Manually execute automation rule

URLs: /api/v1/automation/

Integration Module

Purpose: External platform integrations

Models (in business/integration/):

  • SiteIntegration: Site-level integration configurations

ViewSets:

  • IntegrationViewSet: CRUD + sync operations

Actions:

  • test_connection(): Test connection to integrated platform
  • sync(): Sync content with integrated platform
  • sync_health(): Check sync health status

URLs: /api/v1/integration/

System Module

Purpose: System configuration and AI settings

Models:

  • AIPrompt: AI prompt templates
  • IntegrationSettings: Account-level integration settings
  • AuthorProfile: Author profile definitions
  • Strategy: Content strategy definitions

ViewSets:

  • AIPromptViewSet: CRUD + reset to default
  • IntegrationSettingsViewSet: Integration settings management
  • AuthorProfileViewSet: CRUD for author profiles
  • SystemSettingsViewSet: System settings management
  • AccountSettingsViewSet: Account settings management

URLs: /api/v1/system/

Billing Module

Purpose: Credit management and usage tracking

Models (in business/billing/):

  • CreditTransaction: Credit transaction records
  • CreditUsageLog: Credit usage logging

ViewSets:

  • CreditTransactionViewSet: CRUD for transactions
  • CreditBalanceViewSet: Credit balance retrieval
  • CreditUsageViewSet: Credit usage tracking

Services:

  • CreditService: Credit operations (check, deduct, add, calculate)

URLs: /api/v1/billing/

Summary

The IGNY8 backend provides:

  1. Multi-Tenancy: Complete account isolation with automatic filtering
  2. RESTful API: DRF ViewSets with consistent response format
  3. Celery Integration: Asynchronous task processing
  4. Hierarchical Organization: Account > Site > Sector > Content structure
  5. AI Framework: Unified AI framework for all AI operations
  6. Progress Tracking: Real-time progress updates for Celery tasks
  7. Module-Based Design: Clear separation of concerns across 10 modules
  8. Base Classes: Reusable ViewSets for common patterns
  9. Middleware: Account context and resource tracking
  10. Utilities: Content processing and AI integration
  11. Internal Linking: AI-powered internal linking suggestions
  12. Content Optimization: Content optimization and scoring
  13. Publishing System: Multi-destination publishing with deployment tracking
  14. Site Builder: Site blueprint and structure management (API-based)
  15. Automation: Rule-based automation and scheduled tasks
  16. Integration: External platform integrations and synchronization

This architecture ensures scalability, maintainability, and extensibility while providing a robust foundation for the IGNY8 platform with 10 backend modules covering the complete content workflow from planning to publishing.

Reference in New Issue View Git Blame Copy Permalink