igny8/docs/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](#executive-summary)
2. [System Overview](#system-overview)
3. [Technology Stack](#technology-stack)
4. [Core Architecture Principles](#core-architecture-principles)
5. [System Architecture](#system-architecture)
6. [Module Organization](#module-organization)
7. [Workflows & Functions](#workflows--functions)
8. [Data Flow & Processing](#data-flow--processing)
9. [Multi-Tenancy Architecture](#multi-tenancy-architecture)
10. [API Architecture](#api-architecture)
11. [Frontend Architecture](#frontend-architecture)
12. [Backend Architecture](#backend-architecture)
13. [AI Framework](#ai-framework)
14. [Infrastructure & Deployment](#infrastructure--deployment)
15. [Security Architecture](#security-architecture)
16. [Database Architecture](#database-architecture)
17. [Integration Points](#integration-points)
18. [System Diagrams](#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**:
```json
{
  "success": true,
  "data": { ... },
  "message": "Optional message"
}
```

**Error Response**:
```json
{
  "success": false,
  "message": "Error message",
  "errors": { ... }
}
```

**Pagination Response**:
```json
{
  "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**:
```python
@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**:
```json
{
  "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