igny8/docs/Architecture/MASTER-ARCHITECTURE.md

IGNY8 Master Architecture Document

Version: 1.0
Last Updated: 2025-01-XX
Purpose: Comprehensive master architecture document covering all aspects of the IGNY8 platform including workflows, functions, tech stack, infrastructure, and system design.

---

Table of Contents

1. Executive Summary
2. System Overview
3. Technology Stack
4. Core Architecture Principles
5. System Architecture
6. Module Organization
7. Workflows & Functions
8. Data Flow & Processing
9. Multi-Tenancy Architecture
10. API Architecture
11. Frontend Architecture
12. Backend Architecture
13. AI Framework
14. Infrastructure & Deployment
15. Security Architecture
16. Database Architecture
17. Integration Points
18. System Diagrams

---

Executive Summary

IGNY8 is a full-stack SaaS platform for SEO keyword management and AI-driven content generation. The system provides a scalable, multi-account platform that enables users to:

• Manage SEO Keywords: Import, organize, and cluster keywords
• Plan Content: Generate content ideas from keyword clusters
• Generate Content: AI-powered blog post and article generation
• Create Images: AI-powered image generation for content
• Publish Content: Direct WordPress integration for publishing

Key Metrics

• Architecture: Multi-tenant SaaS with account isolation
• Backend: Django 5.2+ with Django REST Framework
• Frontend: React 19 with TypeScript
• Database: PostgreSQL 15
• Task Queue: Celery with Redis
• Deployment: Docker-based containerization
• AI Functions: 8 primary AI operations
• Modules: 4 core modules (Planner, Writer, System, Billing)

---

System Overview

Platform Capabilities

Capability	Description	Module
Keyword Management	Import, organize, filter, and manage SEO keywords	Planner
Keyword Clustering	AI-powered semantic clustering of related keywords	Planner
Content Ideas	Generate content ideas from keyword clusters	Planner
Content Generation	AI-powered blog post and article generation	Writer
Image Generation	AI-powered image generation (DALL-E, Runware)	Writer
WordPress Integration	Direct publishing to WordPress sites	Writer
Account Management	Multi-account SaaS with user roles	Auth
Billing & Credits	Credit-based billing system	Billing
AI Configuration	Customizable AI prompts and settings	System

System Hierarchy

Account (1) ──< (N) User
Account (1) ──< (1) Subscription ──> (1) Plan
Account (1) ──< (N) Site
Site (1) ──< (1-5) Sector
Sector (1) ──< (N) Keywords, Clusters, ContentIdeas, Tasks

User Roles

Role	Access Level	Description
Developer	System-wide	Full system access, bypasses all restrictions
Owner	Account-wide	Full account access, can manage users and billing
Admin	Account-wide	Account admin access, can manage content and users
Editor	Site-specific	Content editing access, can manage clusters/tasks
Viewer	Site-specific	Read-only access
System Bot	System-wide	System automation user

---

Technology Stack

Backend Stack

Component	Technology	Version	Purpose
Framework	Django	5.2+	Web framework
API Framework	Django REST Framework	Latest	RESTful API
Database	PostgreSQL	15	Primary database
Task Queue	Celery	Latest	Asynchronous tasks
Cache/Broker	Redis	7	Celery broker & caching
Authentication	JWT	SimpleJWT	Token-based auth
HTTP Client	Requests	Latest	External API calls
WSGI Server	Gunicorn	Latest	Production server

Frontend Stack

Component	Technology	Version	Purpose
Framework	React	19	UI library
Language	TypeScript	Latest	Type safety
Build Tool	Vite	Latest	Build tool & dev server
Styling	Tailwind CSS	Latest	Utility-first CSS
State Management	Zustand	Latest	Lightweight state
Routing	React Router	v6	Client-side routing
HTTP Client	Fetch API	Native	API communication

Infrastructure Stack

Component	Technology	Purpose
Containerization	Docker	Application containers
Orchestration	Docker Compose	Multi-container orchestration
Reverse Proxy	Caddy	HTTPS termination & routing
Database Admin	pgAdmin	PostgreSQL administration
File Management	FileBrowser	Web-based file management
Container Management	Portainer	Docker container management

External Services

Service	Purpose	Integration
OpenAI API	Text generation (GPT models)	API integration
OpenAI DALL-E	Image generation	API integration
Runware API	Alternative image generation	API integration
WordPress	Content publishing	REST API integration
Stripe	Payment processing	Webhook integration (planned)

---

Core Architecture Principles

1. Configuration-Driven Everything

Principle: Zero HTML/JSX duplication - All UI rendered from configuration.

Implementation:

• Frontend: Config files in /config/pages/ and /config/snippets/
• Backend: DRF serializers and ViewSet actions
• Templates: 4 universal templates (Dashboard, Table, Form, System)

Benefits:

• Single source of truth
• Easy maintenance
• Consistent UI/UX
• Rapid feature development

2. Multi-Tenancy Foundation

Principle: Complete account isolation with automatic filtering.

Implementation:

• All models inherit AccountBaseModel
• All ViewSets inherit AccountModelViewSet
• Middleware injects account context from JWT
• Site > Sector hierarchy for content organization

Benefits:

• Data security
• Scalability
• Resource isolation
• Simplified access control

3. Template System (4 Universal Templates)

Principle: Reusable templates for all page types.

Template	Purpose	Usage
DashboardTemplate	Module home pages	KPIs, workflow steps, charts
TablePageTemplate	CRUD table pages	Keywords, Clusters, Tasks, etc.
FormPageTemplate	Settings/form pages	Settings, Integration, etc.
SystemPageTemplate	System/admin pages	Logs, Status, Monitoring

4. Unified AI Processor

Principle: Single interface for all AI operations.

Implementation:

• Single AIProcessor class handles all AI operations
• Manual and automated workflows use same functions
• Action-based routing: 'clustering', 'ideas', 'content_generation', 'image_generation'
• Account-specific API keys and model configuration

Benefits:

• Code reusability
• Consistent error handling
• Unified logging
• Easy to extend

5. Module-Based Organization

Principle: Clear module boundaries with shared utilities.

Modules:

• Planner: Keywords, Clusters, Ideas
• Writer: Tasks, Content, Images
• System: Settings, Prompts, Integration
• Billing: Credits, Transactions, Usage

---

System Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Client Layer                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Browser    │  │   Mobile     │  │   Admin      │     │
│  │   (React)    │  │   (Future)   │  │   Panel      │     │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘     │
└─────────┼──────────────────┼──────────────────┼─────────────┘
          │                  │                  │
          └──────────────────┼──────────────────┘
                             │
┌────────────────────────────┼──────────────────────────────┐
│                    Reverse Proxy Layer                     │
│                    ┌───────────────┐                       │
│                    │     Caddy     │                       │
│                    │  (HTTPS/443)  │                       │
│                    └───────┬───────┘                       │
└────────────────────────────┼──────────────────────────────┘
                             │
┌────────────────────────────┼──────────────────────────────┐
│                    Application Layer                       │
│  ┌──────────────┐              ┌──────────────┐          │
│  │   Frontend   │              │    Backend   │          │
│  │   (React)    │◄─────────────┤   (Django)   │          │
│  │   Port 8021  │   REST API   │   Port 8011  │          │
│  └──────────────┘              └──────┬───────┘          │
│                                       │                   │
│                              ┌────────┴────────┐         │
│                              │  Celery Worker  │         │
│                              │  (Async Tasks)  │         │
│                              └────────┬────────┘         │
└───────────────────────────────────────┼──────────────────┘
                                        │
┌───────────────────────────────────────┼──────────────────┐
│                    Data Layer                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  PostgreSQL  │  │    Redis     │  │   Storage    │  │
│  │   (Database) │  │ (Cache/Broker)│  │   (Files)    │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└──────────────────────────────────────────────────────────┘
                                        │
┌───────────────────────────────────────┼──────────────────┐
│                  External Services                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   OpenAI     │  │   Runware    │  │  WordPress   │  │
│  │   (GPT/DALL-E)│  │  (Images)   │  │   (Publish)  │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└──────────────────────────────────────────────────────────┘

Request Flow

1. User Request
   ↓
2. Browser (React Frontend)
   ↓
3. Caddy Reverse Proxy (HTTPS Termination)
   ↓
4. Django Backend (API Endpoint)
   ↓
5. AccountContextMiddleware (Account Isolation)
   ↓
6. ViewSet (Business Logic)
   ↓
7. Serializer (Validation)
   ↓
8. Model (Database)
   ↓
9. Response (JSON)
   ↓
10. Frontend (UI Update)

AI Task Flow

1. User Action (e.g., "Auto Cluster Keywords")
   ↓
2. Frontend API Call
   ↓
3. Backend Endpoint (ViewSet Action)
   ↓
4. Celery Task Queued
   ↓
5. Task ID Returned to Frontend
   ↓
6. Frontend Polls Progress Endpoint
   ↓
7. Celery Worker Processes Task
   ↓
8. AIProcessor Makes API Calls
   ↓
9. Results Saved to Database
   ↓
10. Progress Updates Sent
   ↓
11. Frontend Displays Results

---

Module Organization

Module Structure

Module	Purpose	Models	ViewSets	Tasks
Planner	Keyword management & content planning	Keywords, Clusters, ContentIdeas	KeywordViewSet, ClusterViewSet, ContentIdeasViewSet	auto_cluster_keywords_task, auto_generate_ideas_task
Writer	Content generation & management	Tasks, Content, Images	TasksViewSet	auto_generate_content_task, auto_generate_images_task
System	Settings, prompts, integrations	AIPrompt, IntegrationSettings, AuthorProfile, Strategy	AIPromptViewSet, IntegrationSettingsViewSet, AuthorProfileViewSet	-
Billing	Credits, transactions, usage	CreditTransaction, UsageLog	CreditTransactionViewSet, UsageLogViewSet	-
Auth	Multi-tenancy, users, accounts	Account, User, Plan, Site, Sector	AccountViewSet, UserViewSet, SiteViewSet, SectorViewSet	-

Module Dependencies

Auth (Core)
  ├── Planner (depends on Auth)
  ├── Writer (depends on Auth, Planner)
  ├── System (depends on Auth)
  └── Billing (depends on Auth)

---

Workflows & Functions

Primary Workflows

1. Keyword Management Workflow

1. Import Keywords (CSV/Manual)
   ↓
2. Keywords Stored in Database
   ↓
3. Filter & Organize Keywords
   ↓
4. Select Keywords for Clustering
   ↓
5. Auto Cluster (AI Function)
   ↓
6. Clusters Created
   ↓
7. Generate Ideas from Clusters
   ↓
8. Content Ideas Created

2. Content Generation Workflow

1. Select Content Idea
   ↓
2. Create Task
   ↓
3. Auto Generate Content (AI Function)
   ↓
4. Content Generated & Saved
   ↓
5. Review & Edit Content
   ↓
6. Auto Generate Images (AI Function)
   ↓
7. Images Generated & Attached
   ↓
8. Publish to WordPress

3. Account Setup Workflow

1. User Signs Up
   ↓
2. Account Created
   ↓
3. Default Plan Assigned
   ↓
4. Site Created
   ↓
5. Sectors Created (1-5 per site)
   ↓
6. Integration Settings Configured
   ↓
7. Ready to Use

AI Functions

Function	Module	Purpose	Input	Output
Auto Cluster Keywords	Planner	Group related keywords	Keyword IDs	Clusters
Auto Generate Ideas	Planner	Generate content ideas	Cluster IDs	Content Ideas
Auto Generate Content	Writer	Generate blog posts	Task IDs	HTML Content
Auto Generate Images	Writer	Generate images	Task IDs	Images
Extract Image Prompts	Writer	Extract prompts from content	Content Text	Image Prompts
Test OpenAI	System	Test OpenAI connection	API Key	Connection Status
Test Runware	System	Test Runware connection	API Key	Connection Status
Generate Image (Test)	System	Test image generation	Prompt	Image URL

AI Function Execution Flow

1. User Initiates AI Function
   ↓
2. Frontend Calls API Endpoint
   ↓
3. Backend Validates Input
   ↓
4. Celery Task Queued
   ↓
5. Task ID Returned
   ↓
6. Frontend Polls Progress
   ↓
7. Celery Worker Executes:
   a. Prepare Data
   b. Build Prompt
   c. Call AI API
   d. Parse Response
   e. Save Results
   ↓
8. Progress Updates Sent
   ↓
9. Task Completes
   ↓
10. Results Displayed

---

Data Flow & Processing

Data Models Hierarchy

AccountBaseModel
  ├── Account
  ├── User
  ├── Plan
  ├── Site
  ├── Sector
  └── SiteSectorBaseModel
      ├── Keywords
      ├── Clusters
      ├── ContentIdeas
      ├── Tasks
      ├── Content
      └── Images

Data Relationships

Parent	Child	Relationship	Constraints
Account	User	One-to-Many	N users per account
Account	Site	One-to-Many	N sites per account (plan limit)
Account	Subscription	One-to-One	1 subscription per account
Subscription	Plan	Many-to-One	1 plan per subscription
Site	Sector	One-to-Many	1-5 sectors per site
Sector	Keywords	One-to-Many	N keywords per sector
Sector	Clusters	One-to-Many	N clusters per sector
Sector	ContentIdeas	One-to-Many	N ideas per sector
Sector	Tasks	One-to-Many	N tasks per sector
Cluster	Keywords	Many-to-Many	N keywords per cluster
Cluster	ContentIdeas	One-to-Many	N ideas per cluster
Task	Content	One-to-One	1 content per task
Task	Images	One-to-Many	N images per task
ContentIdeas	Task	One-to-Many	N tasks per idea

Data Processing Pipeline

Raw Data (CSV/Manual)
   ↓
Import & Validation
   ↓
Database Storage
   ↓
AI Processing (Optional)
   ↓
Enriched Data
   ↓
User Review & Edit
   ↓
Final Data
   ↓
Export/Publish

---

Multi-Tenancy Architecture

Account Isolation

Implementation Levels:

1. Model Level: All models inherit AccountBaseModel with account ForeignKey
2. ViewSet Level: All ViewSets inherit AccountModelViewSet with automatic filtering
3. Middleware Level: AccountContextMiddleware sets request.account from JWT

Access Control Matrix

User Role	Account Access	Site Access	Data Access
Developer	All accounts	All sites	All data
System Bot	All accounts	All sites	All data
Owner	Own account	All sites in account	All data in account
Admin	Own account	All sites in account	All data in account
Editor	Own account	Granted sites only	Data in granted sites
Viewer	Own account	Granted sites only	Read-only in granted sites

Site/Sector Hierarchy

Account
  └── Site 1 (Active)
      ├── Sector 1 (Active)
      │   ├── Keywords
      │   ├── Clusters
      │   ├── ContentIdeas
      │   └── Tasks
      ├── Sector 2 (Active)
      └── Sector 3 (Inactive)
  └── Site 2 (Active)
      └── Sector 1 (Active)

---

API Architecture

API Structure

Base URL: /api/v1/

Module Endpoints:

Module	Base Path	Resources
Auth	/api/v1/auth/	accounts, users, sites, sectors, plans
Planner	/api/v1/planner/	keywords, clusters, ideas
Writer	/api/v1/writer/	tasks, content, images
System	/api/v1/system/	prompts, integrations, author-profiles, strategies
Billing	/api/v1/billing/	credits, transactions, usage

API Endpoints

Planner Endpoints

Method	Endpoint	Purpose
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
GET	/api/v1/planner/keywords/export_csv/	Export CSV
POST	/api/v1/planner/keywords/import_csv/	Import CSV
GET	/api/v1/planner/clusters/	List clusters
POST	/api/v1/planner/clusters/auto_generate_ideas/	Generate ideas
GET	/api/v1/planner/ideas/	List ideas

Writer Endpoints

Method	Endpoint	Purpose
GET	/api/v1/writer/tasks/	List tasks
POST	/api/v1/writer/tasks/auto_generate_content/	Generate content
POST	/api/v1/writer/tasks/auto_generate_images/	Generate images

System Endpoints

Method	Endpoint	Purpose
GET	/api/v1/system/settings/integrations/{id}/	Get integration
PUT	/api/v1/system/settings/integrations/{id}/	Save integration
POST	/api/v1/system/settings/integrations/{id}/test_openai/	Test OpenAI
POST	/api/v1/system/settings/integrations/{id}/test_runware/	Test Runware
GET	/api/v1/system/settings/task_progress/{task_id}/	Get task progress

Authentication Flow

1. User Signs In
   ↓
2. Backend Validates Credentials
   ↓
3. JWT Token Generated
   ↓
4. Token Returned to Frontend
   ↓
5. Frontend Stores Token (localStorage)
   ↓
6. Frontend Includes Token in Requests
   ↓
7. Backend Validates Token
   ↓
8. Account Context Set
   ↓
9. Request Processed

Response Format

Success Response:

{
  "success": true,
  "data": { ... },
  "message": "Optional message"
}

Error Response:

{
  "success": false,
  "message": "Error message",
  "errors": { ... }
}

Pagination Response:

{
  "count": 100,
  "next": "http://api.example.com/api/v1/resource/?page=2",
  "previous": null,
  "results": [ ... ]
}

---

Frontend Architecture

Component Hierarchy

App
└── AppLayout
    ├── Sidebar (Navigation)
    ├── Header (User Menu, Notifications)
    └── Main Content
        └── Page Component
            └── Template (DashboardTemplate, TablePageTemplate, etc.)
                └── Components (DataTable, Filters, etc.)

State Management

Store	Purpose	State
authStore	Authentication	user, token, isAuthenticated
siteStore	Site selection	activeSite, sites
sectorStore	Sector selection	activeSector, sectors
plannerStore	Planner module	module-specific state
aiRequestLogsStore	AI logs	request/response logs
pageSizeStore	Table preferences	pageSize

Routing Structure

Route	Component	Template
/	Home	DashboardTemplate
/planner	PlannerDashboard	DashboardTemplate
/planner/keywords	Keywords	TablePageTemplate
/planner/clusters	Clusters	TablePageTemplate
/planner/ideas	Ideas	TablePageTemplate
/writer	WriterDashboard	DashboardTemplate
/writer/tasks	Tasks	TablePageTemplate
/thinker	ThinkerDashboard	DashboardTemplate
/thinker/prompts	Prompts	TablePageTemplate
/billing/credits	Credits	FormPageTemplate
/settings	Settings	FormPageTemplate

Configuration System

Page-Local Config: /config/pages/

• Page-specific table, filter, and action configurations

Shared Snippets: /config/snippets/

• Reusable column definitions
• Reusable filter definitions
• Reusable action definitions

---

Backend Architecture

Model Inheritance Hierarchy

models.Model
└── AccountBaseModel (adds account ForeignKey)
    └── SiteSectorBaseModel (adds site, sector ForeignKeys)
        └── Keywords, Clusters, ContentIdeas, Tasks, etc.

ViewSet Inheritance Hierarchy

viewsets.ModelViewSet
└── AccountModelViewSet (adds account filtering)
    └── SiteSectorModelViewSet (adds site/sector filtering)
        └── KeywordViewSet, ClusterViewSet, TasksViewSet, etc.

Middleware Stack

1. SecurityMiddleware: Django security middleware
2. SessionMiddleware: Session management
3. AuthenticationMiddleware: User authentication
4. AccountContextMiddleware: Sets request.account from JWT
5. ResourceTrackerMiddleware: Tracks API request metrics

Celery Task Architecture

Broker: Redis

Workers: Separate Celery worker processes

Task Structure:

@shared_task(bind=True)
def my_task(self, ...):
    # Update progress
    self.update_state(state='PROGRESS', meta={...})
    # Do work
    result = do_work()
    # Return result
    return result

Progress Tracking:

• Frontend polls /api/v1/system/settings/task_progress/{task_id}/
• Backend returns task state and meta information
• Progress displayed in modal

---

AI Framework

AI Framework Architecture

BaseAIFunction (Abstract)
  ├── AutoClusterFunction
  ├── AutoGenerateIdeasFunction
  ├── AutoGenerateContentFunction
  └── AutoGenerateImagesFunction

AIEngine (Orchestrator)
  ├── INIT Phase (0-10%)
  ├── PREP Phase (10-25%)
  ├── AI_CALL Phase (25-60%)
  ├── PARSE Phase (60-80%)
  ├── SAVE Phase (80-95%)
  └── DONE Phase (95-100%)

AIProcessor (Wrapper)
  ├── cluster_keywords()
  ├── generate_ideas()
  ├── generate_content()
  ├── extract_image_prompts()
  └── generate_image()

AI Function Execution

1. User Action
   ↓
2. API Endpoint
   ↓
3. run_ai_task.delay()
   ↓
4. AIEngine.execute()
   ↓
5. Function.prepare()
   ↓
6. Function.build_prompt()
   ↓
7. AIProcessor API Call
   ↓
8. Function.parse_response()
   ↓
9. Function.save_output()
   ↓
10. Task Complete

Progress Tracking

Progress Endpoint: /api/v1/system/settings/task_progress/{task_id}/

Response Format:

{
  "state": "PROGRESS",
  "meta": {
    "phase": "AI_CALL",
    "percentage": 45,
    "message": "Processing...",
    "request_steps": [...],
    "response_steps": [...],
    "cost": 0.000123,
    "tokens": 1500
  }
}

---

Infrastructure & Deployment

Docker Architecture

Two-Stack Architecture:

1. Infrastructure Stack (igny8-infra):

   • PostgreSQL
   • Redis
   • pgAdmin
   • FileBrowser
   • Caddy

2. Application Stack (igny8-app):

   • Backend (Django)
   • Frontend (React)
   • Celery Worker
   • Celery Beat

Network Architecture

Single Network: igny8_net (bridge network)

Container Communication: Service names as hostnames

Port Allocation

Service	External Port	Internal Port	Purpose
Backend	8011	8010	Django API
Frontend	8021	5173	React Dev Server
PostgreSQL	-	5432	Database
Redis	-	6379	Cache/Broker
pgAdmin	5050	80	DB Admin
FileBrowser	8080	80	File Manager
Caddy	80, 443	80, 443	Reverse Proxy

Volume Management

Volume	Purpose	Location
pgdata	PostgreSQL data	/var/lib/docker/volumes/igny8-infra_pgdata/
redisdata	Redis data	/var/lib/docker/volumes/igny8-infra_redisdata/
caddy_data	SSL certificates	/var/lib/docker/volumes/igny8-infra_caddy_data/
Application Code	Source code	/data/app/igny8/ (host mount)

---

Security Architecture

Authentication

Methods:

• JWT (JSON Web Tokens) - Primary method
• Session-based auth - Fallback for admin

Flow:

1. User signs in → Backend returns JWT token
2. Frontend stores token in localStorage
3. Frontend includes token in Authorization: Bearer {token} header
4. Backend middleware validates token and sets request.user and request.account

Authorization

Role-Based Access Control (RBAC):

• developer: Full system access
• owner: Full account access
• admin: Account admin access
• editor: Content editing access
• viewer: Read-only access

Access Control:

• Account-level: Automatic filtering by request.account
• Site-level: Filtering by user.get_accessible_sites()
• Action-level: Permission checks in ViewSet actions

Data Isolation

Account Isolation:

• All queries filtered by account
• Admin/Developer override for system accounts

Site Access Control:

• Users can only access granted sites
• Admin/Developer override for all sites

API Security

• CORS: Configured for frontend domain
• CSRF: Enabled for session-based auth
• Input Validation: DRF serializers validate all input
• Rate Limiting: (Future implementation)

---

Database Architecture

Core Tables

Table	Purpose	Key Fields
igny8_accounts	Account information	name, slug, owner, plan, credits, status
igny8_users	User accounts	email, account, role
igny8_plans	Subscription plans	name, price, limits, features
igny8_subscriptions	Active subscriptions	account, plan, status, period
igny8_sites	Sites within accounts	name, slug, account, industry, status
igny8_sectors	Sectors within sites	name, slug, site, status
igny8_industries	Global industry templates	name, slug, description
igny8_industry_sectors	Industry sector templates	name, slug, industry

Planner Tables

Table	Purpose	Key Fields
igny8_keywords	Keywords	keyword, volume, difficulty, intent, cluster
igny8_clusters	Keyword clusters	name, description, keywords_count, volume
igny8_content_ideas	Content ideas	idea_title, description, cluster, status

Writer Tables

Table	Purpose	Key Fields
igny8_tasks	Content generation tasks	title, description, cluster, idea, status, content
igny8_content	Generated content	task, html_content, word_count
igny8_images	Generated images	task, image_type, image_url, prompt

System Tables

Table	Purpose	Key Fields
igny8_ai_prompts	AI prompt templates	prompt_type, prompt_value, account
igny8_integration_settings	API keys and configuration	integration_type, config, account
igny8_author_profiles	Writing style profiles	name, description, tone, language
igny8_strategies	Content strategies	name, description, sector, prompt_types

Billing Tables

Table	Purpose	Key Fields
igny8_credit_transactions	Credit transactions	account, transaction_type, amount, balance_after
igny8_credit_usage_logs	Usage tracking	account, operation_type, credits_used, cost_usd

Indexes

Account Isolation: All tables have indexes on account

Site/Sector Filtering: Tables with site/sector have composite indexes on (account, site, sector)

Performance: Indexes on frequently queried fields (status, created_at, etc.)

---

Integration Points

External API Integrations

Service	Integration Type	Purpose	Configuration
OpenAI	REST API	Text generation (GPT)	API key in IntegrationSettings
OpenAI DALL-E	REST API	Image generation	API key in IntegrationSettings
Runware	REST API	Alternative image generation	API key in IntegrationSettings
WordPress	REST API	Content publishing	wp_url, wp_username, wp_app_password in Site model

Integration Flow

1. User Configures Integration
   ↓
2. API Key Stored in IntegrationSettings
   ↓
3. Test Connection (Optional)
   ↓
4. Integration Active
   ↓
5. AI Functions Use Integration
   ↓
6. API Calls Made
   ↓
7. Results Returned

---

System Diagrams

System Component Diagram

┌─────────────────────────────────────────────────────────────┐
│                         Frontend                             │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐           │
│  │   React    │  │  Zustand   │  │   Vite     │           │
│  │  (UI)      │  │  (State)   │  │  (Build)   │           │
│  └────────────┘  └────────────┘  └────────────┘           │
└───────────────────────────┬─────────────────────────────────┘
                            │ HTTP/REST
┌───────────────────────────┴─────────────────────────────────┐
│                         Backend                              │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐           │
│  │   Django   │  │    DRF     │  │  Celery    │           │
│  │ (Framework)│  │   (API)    │  │  (Tasks)   │           │
│  └────────────┘  └────────────┘  └────────────┘           │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────┴─────────────────────────────────┐
│                        Database                              │
│  ┌────────────┐  ┌────────────┐                            │
│  │ PostgreSQL │  │   Redis    │                            │
│  │  (Data)    │  │ (Cache)    │                            │
│  └────────────┘  └────────────┘                            │
└─────────────────────────────────────────────────────────────┘

Data Flow Diagram

User Action
    ↓
Frontend (React)
    ↓
API Request (REST)
    ↓
Caddy (Reverse Proxy)
    ↓
Django Backend
    ↓
AccountContextMiddleware (Account Isolation)
    ↓
ViewSet (Business Logic)
    ↓
Serializer (Validation)
    ↓
Model (Database)
    ↓
PostgreSQL
    ↓
Response (JSON)
    ↓
Frontend (UI Update)

AI Function Flow Diagram

User Initiates AI Function
    ↓
Frontend API Call
    ↓
Backend Endpoint
    ↓
Celery Task Queued
    ↓
Task ID Returned
    ↓
Frontend Polls Progress
    ↓
Celery Worker Executes
    ├── Prepare Data
    ├── Build Prompt
    ├── Call AI API (OpenAI/Runware)
    ├── Parse Response
    └── Save Results
    ↓
Progress Updates
    ↓
Task Complete
    ↓
Results Displayed

Multi-Tenancy Flow Diagram

Request with JWT Token
    ↓
AccountContextMiddleware
    ├── Extract Account ID from JWT
    ├── Load Account Object
    └── Set request.account
    ↓
ViewSet.get_queryset()
    ├── Check User Role
    ├── Filter by Account (if not admin/developer)
    └── Filter by Accessible Sites (if not owner/admin)
    ↓
Database Query
    ↓
Results (Account-Isolated)

---

Summary

The IGNY8 platform is built on a modern, scalable architecture that provides:

1. Multi-Tenancy: Complete account isolation with automatic filtering
2. Configuration-Driven UI: Zero duplication, single source of truth
3. Unified AI Framework: Single interface for all AI operations
4. Module-Based Organization: Clear boundaries with shared utilities
5. RESTful API: Consistent API design with DRF
6. Modern Frontend: React + TypeScript with Zustand state management
7. Scalable Backend: Django + Celery for async processing
8. Security First: JWT auth, RBAC, data isolation
9. Docker Deployment: Containerized for easy deployment and scaling
10. Comprehensive Logging: Detailed tracking for all operations

This architecture ensures scalability, maintainability, and extensibility while providing a robust foundation for the IGNY8 platform.

---

Document Version: 1.0
Last Updated: 2025-01-XX
Maintained By: IGNY8 Development Team