igny8/docs/planning/ARCHITECTURE_CONTEXT.md

# IGNY8 Complete Architecture Context
**Created:** 2025-01-XX  
**Purpose:** Comprehensive context document for understanding the complete IGNY8 system architecture, workflows, and implementation details.

---

## Executive Summary

IGNY8 is a full-stack SaaS platform for SEO keyword management and AI-driven content generation. The system operates on a multi-tenant architecture with complete account isolation, hierarchical organization (Account > Site > Sector > Content), and unified AI processing framework.

**Key Characteristics:**
- Multi-tenant SaaS with account isolation
- Django 5.2+ backend with DRF API
- React 19 frontend with TypeScript
- PostgreSQL 15 database
- Celery + Redis for async tasks
- Docker-based containerization
- Caddy reverse proxy for HTTPS

---

## System Architecture Overview

### High-Level Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Client Layer (Browser)                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Main App   │  │  Marketing   │  │   Admin     │     │
│  │ (app.igny8)  │  │  (igny8.com) │  │   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) │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└──────────────────────────────────────────────────────────┘
```

### Current Infrastructure Status

**Running Containers:**
- `igny8_backend` - Django API (Port 8011, healthy)
- `igny8_frontend` - React app (Port 8021)
- `igny8_marketing_dev` - Marketing site (Port 8023)
- `igny8_celery_worker` - Async task processor
- `igny8_celery_beat` - Scheduled tasks
- `igny8_postgres` - Database (healthy)
- `igny8_redis` - Cache/Broker (healthy)
- `igny8_caddy` - Reverse proxy (Ports 80, 443)
- `igny8_pgadmin` - DB admin (Port 5050)
- `igny8_filebrowser` - File manager (Port 8080)
- `portainer` - Container management (Ports 8000, 9443)

**Network:** `igny8_net` (bridge network, external)

---

## Technology Stack

### Backend Stack
- **Framework:** Django 5.2.7+
- **API:** Django REST Framework
- **Database:** PostgreSQL 15
- **Task Queue:** Celery 5.3.0+ with Redis 7
- **Auth:** JWT (PyJWT 2.8.0+)
- **Server:** Gunicorn
- **Static Files:** WhiteNoise

### Frontend Stack
- **Framework:** React 19.0.0
- **Language:** TypeScript 5.7.2
- **Build Tool:** Vite 6.1.0
- **Styling:** Tailwind CSS 4.0.8
- **State:** Zustand 5.0.8
- **Routing:** React Router v7.9.5
- **Icons:** @heroicons/react 2.2.0

### Infrastructure
- **Containerization:** Docker + Docker Compose
- **Reverse Proxy:** Caddy (HTTPS termination)
- **Container Management:** Portainer

---

## Core Architecture Principles

### 1. Multi-Tenancy Foundation
- **Account Isolation:** All models inherit `AccountBaseModel` with `account` ForeignKey
- **Automatic Filtering:** All ViewSets inherit `AccountModelViewSet` with automatic filtering
- **Middleware:** `AccountContextMiddleware` sets `request.account` from JWT token
- **Hierarchy:** Account > Site > Sector > Content

### 2. Configuration-Driven Everything
- **Frontend:** Config files in `/config/pages/` and `/config/snippets/`
- **Backend:** DRF serializers and ViewSet actions
- **Templates:** 4 universal templates (Dashboard, Table, Form, System)

### 3. Unified AI Framework
- **Single Interface:** All AI operations use `AIEngine` orchestrator
- **Base Class:** All AI functions inherit from `BaseAIFunction`
- **Execution Pipeline:** 6 phases (INIT, PREP, AI_CALL, PARSE, SAVE, DONE)
- **Progress Tracking:** Real-time updates via Celery

### 4. Module-Based Organization
- **Planner:** Keywords, Clusters, Ideas
- **Writer:** Tasks, Content, Images
- **Thinker:** Prompts, Author Profiles, Strategies
- **System:** Settings, Integrations, AI Configuration
- **Billing:** Credits, Transactions, Usage
- **Auth:** Accounts, Users, Sites, Sectors

---

## System Hierarchy

### Entity Relationships

```
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
Cluster (1) ──< (N) Keywords (Many-to-Many)
Cluster (1) ──< (N) ContentIdeas
ContentIdeas (1) ──< (N) Tasks
Task (1) ──> (1) Content
Task (1) ──< (N) Images
```

### Hierarchy Details

**Account Level:**
- Top-level organization/workspace
- Contains users, sites, subscriptions, and all data
- Has credit balance and plan assignment
- Status: active, suspended, trial, cancelled

**User Level:**
- Individual user accounts within an account
- Has role (developer, owner, admin, editor, viewer)
- Can belong to only one account
- Access controlled by role and site permissions

**Site Level:**
- Workspace within an account (1-N relationship)
- Can have multiple active sites simultaneously
- Has WordPress integration settings (URL, username, password)
- Can be associated with an industry
- Status: active, inactive, suspended

**Sector Level:**
- Content category within a site (1-5 per site)
- Organizes keywords, clusters, ideas, and tasks
- Can reference an industry sector template
- Status: active, inactive

**Content Level:**
- Keywords, Clusters, ContentIdeas belong to Sector
- Tasks, Content, Images belong to Sector
- All content is automatically associated with Account and Site

---

## User Roles & Access Control

### Role Hierarchy
```
developer > owner > admin > editor > viewer > system_bot
```

### Role Permissions

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

### Access Control Implementation

**Automatic Access:**
- Owners and Admins: Automatic access to all sites in their account
- Developers and System Bot: Access to all sites across all accounts

**Explicit Access:**
- Editors and Viewers: Require explicit `SiteUserAccess` records
- Access granted by Owner or Admin
- Access can be revoked at any time

---

## Complete Workflows

### 1. Account Setup Workflow

**Steps:**
1. User signs up via `/signup`
2. Account created with default plan
3. Owner user created and linked to account
4. User signs in via `/signin`
5. JWT token generated and returned
6. Frontend stores token and redirects to dashboard
7. User creates first site (optional)
8. User creates sectors (1-5 per site, optional)
9. User configures integration settings (OpenAI, Runware)
10. System ready for use

**Data Created:**
- 1 Account record
- 1 User record (owner role)
- 1 Subscription record (default plan)
- 0-N Site records
- 0-N Sector records (per site)
- 1 IntegrationSettings record (per integration type)

### 2. Keyword Management Workflow

**Steps:**
1. User navigates to `/planner/keywords`
2. User imports keywords via CSV or manual entry
3. Keywords validated and stored in database
4. Keywords displayed in table with filters
5. User filters keywords by sector, status, intent, etc.
6. User selects keywords for clustering
7. User clicks "Auto Cluster" action
8. Backend validates keyword IDs
9. Celery task queued (`run_ai_task` with function `auto_cluster`)
10. Task ID returned to frontend
11. Frontend polls progress endpoint
12. Celery worker processes task:
    - Loads keywords from database
    - Builds AI prompt with keyword data
    - Calls OpenAI API for clustering
    - Parses cluster response
    - Creates Cluster records
    - Links keywords to clusters
13. Progress updates sent to frontend
14. Task completes
15. Frontend displays new clusters
16. Credits deducted from account

**AI Function:** Auto Cluster Keywords

### 3. Content Generation Workflow

**Steps:**
1. User navigates to `/planner/ideas`
2. User selects content ideas
3. User clicks "Create Tasks" action
4. Task records created for each idea
5. User navigates to `/writer/tasks`
6. User selects tasks for content generation
7. User clicks "Generate Content" action
8. Backend validates task IDs
9. Celery task queued (`run_ai_task` with function `generate_content`)
10. Task ID returned to frontend
11. Frontend polls progress endpoint
12. Celery worker processes task:
    - Loads tasks and related data (cluster, keywords, idea)
    - Builds AI prompt with task data
    - Calls OpenAI API for content generation
    - Parses HTML content response
    - Creates/updates Content records
    - Updates task status
13. Progress updates sent to frontend
14. Task completes
15. Frontend displays generated content
16. Credits deducted from account

**AI Function:** Generate Content

### 4. WordPress Publishing Workflow

**Steps:**
1. User navigates to `/writer/content`
2. User selects content to publish
3. User clicks "Publish to WordPress" action
4. Backend validates:
    - Site has WordPress URL configured
    - Site has WordPress credentials
    - Content is ready (status: review or draft)
5. Backend calls WordPress REST API:
    - Creates post with content HTML
    - Uploads featured image (if available)
    - Uploads in-article images (if available)
    - Sets post status (draft, publish)
6. WordPress post ID stored in Content record
7. Content status updated to "published"
8. Frontend displays success message

**Integration:** WordPress REST API

---

## AI Framework Architecture

### Unified Execution Pipeline

**Entry Point:** `run_ai_task` (Celery task)
- Location: `backend/igny8_core/ai/tasks.py`
- Parameters: `function_name`, `payload`, `account_id`
- Flow: Loads function from registry → Creates AIEngine → Executes function

**Engine Orchestrator:** `AIEngine`
- Location: `backend/igny8_core/ai/engine.py`
- Purpose: Central orchestrator managing lifecycle, progress, logging, cost tracking
- Methods:
  - `execute` - Main execution pipeline (6 phases)
  - `_handle_error` - Centralized error handling
  - `_log_to_database` - Logs to AITaskLog model

**Base Function Class:** `BaseAIFunction`
- Location: `backend/igny8_core/ai/base.py`
- Purpose: Abstract base class defining interface for all AI functions
- Abstract Methods:
  - `get_name()` - Returns function name
  - `prepare()` - Loads and prepares data
  - `build_prompt()` - Builds AI prompt
  - `parse_response()` - Parses AI response
  - `save_output()` - Saves results to database

### AI Function Execution Flow

```
1. API Endpoint (views.py)
   ↓
2. run_ai_task (tasks.py)
   - Gets account from account_id
   - Gets function instance from registry
   - Creates AIEngine
   ↓
3. AIEngine.execute (engine.py)
   Phase 1: INIT (0-10%)
   - Calls function.validate()
   - Updates progress tracker
   ↓
   Phase 2: PREP (10-25%)
   - Calls function.prepare()
   - Calls function.build_prompt()
   - Updates progress tracker
   ↓
   Phase 3: AI_CALL (25-70%)
   - Gets model config from settings
   - Calls AICore.run_ai_request() or AICore.generate_image()
   - Tracks cost and tokens
   - Updates progress tracker
   ↓
   Phase 4: PARSE (70-85%)
   - Calls function.parse_response()
   - Updates progress tracker
   ↓
   Phase 5: SAVE (85-98%)
   - Calls function.save_output()
   - Logs credit usage
   - Updates progress tracker
   ↓
   Phase 6: DONE (98-100%)
   - Logs to AITaskLog
   - Returns result
```

### AI Functions

1. **Auto Cluster Keywords** (`auto_cluster`)
   - Purpose: Group related keywords into semantic clusters
   - Input: Keyword IDs (max 20)
   - Output: Cluster records created, keywords linked
   - Credits: 1 credit per 30 keywords

2. **Generate Ideas** (`generate_ideas`)
   - Purpose: Generate content ideas from keyword clusters
   - Input: Cluster IDs (max 1 per batch)
   - Output: ContentIdeas records created
   - Credits: 1 credit per idea

3. **Generate Content** (`generate_content`)
   - Purpose: Generate blog post and article content
   - Input: Task IDs (max 50 per batch)
   - Output: Content records created/updated with HTML
   - Credits: 3 credits per content piece

4. **Generate Image Prompts** (`generate_image_prompts`)
   - Purpose: Extract image prompts from content HTML
   - Input: Content IDs
   - Output: Images records updated with prompts
   - Credits: Included in content generation

5. **Generate Images** (`generate_images`)
   - Purpose: Generate images using OpenAI DALL-E or Runware
   - Input: Image IDs (with prompts)
   - Output: Images records updated with image URLs
   - Credits: 1 credit per image

---

## Frontend Architecture

### Application Structure

**Dual Application Architecture:**
1. **Main Application** (`app.igny8.com`): Authenticated SaaS platform
2. **Marketing Site** (`igny8.com`): Public-facing marketing website

**Entry Points:**
- Main App: `src/main.tsx` → `src/App.tsx`
- Marketing: `src/marketing/index.tsx` → `src/marketing/MarketingApp.tsx`

### State Management

**Zustand Stores:**
- `authStore` - Authentication & user
- `siteStore` - Active site management
- `sectorStore` - Active sector management
- `plannerStore` - Planner module state
- `billingStore` - Billing & credits
- `settingsStore` - Application settings
- `pageSizeStore` - Table pagination
- `columnVisibilityStore` - Table column visibility

**React Contexts:**
- `ThemeContext` - Light/dark theme
- `SidebarContext` - Sidebar state
- `HeaderMetricsContext` - Header metrics
- `ToastProvider` - Toast notifications

### Template System

**4 Universal Templates:**
1. **DashboardTemplate** - Module home pages (KPIs, workflow steps, charts)
2. **TablePageTemplate** - CRUD table pages (filtering, sorting, pagination)
3. **FormPageTemplate** - Settings/form pages (sectioned forms)
4. **SystemPageTemplate** - System/admin pages (status cards, logs)

### API Integration

**API Service Layer:**
- Location: `frontend/src/services/api.ts`
- Function: `fetchAPI()` - Centralized API client
- Features:
  - Automatic token injection
  - Token refresh on 401
  - Site/sector context injection
  - Unified error handling
  - Timeout handling

**Request Flow:**
1. User action in frontend
2. Frontend makes API request via `fetchAPI()`
3. JWT token included in Authorization header
4. Backend middleware extracts account from JWT
5. Backend ViewSet processes request
6. Backend returns JSON response (unified format)
7. Frontend updates state
8. Frontend updates UI

---

## Backend Architecture

### Multi-Tenancy Implementation

**Account Isolation:**
- **Model Level:** All models inherit `AccountBaseModel` with `account` ForeignKey
- **ViewSet Level:** All ViewSets inherit `AccountModelViewSet` with automatic filtering
- **Middleware Level:** `AccountContextMiddleware` sets `request.account` from JWT

**Middleware Flow:**
```
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)
```

### Base Classes

**AccountModelViewSet:**
- Location: `backend/igny8_core/api/base.py`
- Purpose: Base ViewSet with automatic account filtering
- Features:
  - Automatic account filtering
  - Admin/Developer override
  - Account context in serializers

**SiteSectorModelViewSet:**
- Location: `backend/igny8_core/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

### API Response Format

**Unified Format:**
```json
{
  "success": true,
  "data": {...},
  "message": "Optional message",
  "request_id": "uuid"
}
```

**Error Format:**
```json
{
  "success": false,
  "error": "Error message",
  "errors": {
    "field_name": ["Field-specific errors"]
  },
  "request_id": "uuid"
}
```

**Paginated Format:**
```json
{
  "success": true,
  "count": 120,
  "next": "url",
  "previous": "url",
  "results": [...],
  "request_id": "uuid"
}
```

---

## Module Organization

### Planner Module
- **Purpose:** Keyword management & content planning
- **Models:** Keywords, Clusters, ContentIdeas
- **ViewSets:** KeywordViewSet, ClusterViewSet, ContentIdeasViewSet
- **Celery Tasks:** `auto_cluster_keywords_task`, `auto_generate_ideas_task`
- **Features:**
  - Keyword import (CSV/manual)
  - Keyword filtering and organization
  - AI-powered keyword clustering
  - Content idea generation from clusters
  - Keyword-to-cluster mapping

### Writer Module
- **Purpose:** Content generation & management
- **Models:** Tasks, Content, Images
- **ViewSets:** TasksViewSet, ImagesViewSet
- **Celery Tasks:** `auto_generate_content_task`, `auto_generate_images_task`
- **Features:**
  - Task creation from content ideas
  - AI-powered content generation
  - Content editing and review
  - Image prompt extraction
  - AI-powered image generation
  - WordPress publishing

### Thinker Module
- **Purpose:** AI configuration and strategy
- **Models:** AIPrompt, AuthorProfile, Strategy
- **ViewSets:** AIPromptViewSet, AuthorProfileViewSet
- **Features:**
  - AI prompt management
  - Author profile management
  - Content strategy management
  - Image testing

### System Module
- **Purpose:** System configuration and AI settings
- **Models:** IntegrationSettings, AIPrompt, AuthorProfile, Strategy
- **ViewSets:** IntegrationSettingsViewSet, AIPromptViewSet, AuthorProfileViewSet
- **Features:**
  - Integration settings (OpenAI, Runware)
  - AI prompt management
  - System status and monitoring

### Billing Module
- **Purpose:** Credit management and usage tracking
- **Models:** CreditTransaction, CreditUsageLog
- **ViewSets:** CreditTransactionViewSet, CreditUsageLogViewSet
- **Services:** CreditService
- **Features:**
  - Credit balance tracking
  - Credit transactions
  - Usage logging
  - Cost tracking

### Auth Module
- **Purpose:** Multi-tenancy and user management
- **Models:** Account, User, Plan, Site, Sector, Industry
- **ViewSets:** AccountViewSet, UserViewSet, SiteViewSet, SectorViewSet
- **Features:**
  - Account management
  - User management
  - Plan management
  - Site and sector management
  - Industry templates

---

## Credit System

### Credit Balance Management

**Account Credits:**
- Each account has a `credits` field (integer)
- Credits start at 0 or plan-included credits
- Credits are deducted for AI operations
- Credits can be added via transactions

**Credit Checking:**
- Before AI operation: System checks if account has sufficient credits
- If insufficient: Operation fails with `InsufficientCreditsError`
- If sufficient: Operation proceeds

**Credit Deduction:**
- After AI operation completes: Credits deducted via `CreditService.deduct_credits()`
- Account credits field updated
- CreditTransaction record created (type: deduction, amount: negative)
- CreditUsageLog record created with operation details

### Credit Costs per Operation

- **Clustering:** 1 credit per 30 keywords (base: 1 credit)
- **Ideas:** 1 credit per idea (base: 1 credit)
- **Content:** 3 credits per content piece (base: 3 credits)
- **Images:** 1 credit per image (base: 1 credit)
- **Reparse:** 1 credit per reparse (base: 1 credit)

---

## WordPress Integration

### Publishing Process

**Workflow:**
1. User selects content to publish
2. System validates WordPress configuration
3. System authenticates with WordPress REST API
4. System creates WordPress post:
   - Title: Content meta_title or task title
   - Content: Content HTML
   - Status: Draft or Publish (based on content status)
   - Featured image: Uploaded if available
   - In-article images: Uploaded if available
   - Meta fields: Primary keyword, secondary keywords
5. WordPress returns post ID
6. System updates Content record:
   - Sets `wp_post_id` field
   - Sets `status` to "published"

**Requirements:**
- Site must have WordPress URL configured (`wp_url`)
- Site must have WordPress username and app password
- Content must have status "review" or "draft"
- WordPress REST API must be accessible

---

## Docker Architecture

### Infrastructure Stack (`igny8-infra`)
- **PostgreSQL** - Database (Port 5432 internal)
- **Redis** - Cache & Celery broker (Port 6379 internal)
- **pgAdmin** - Database admin (Port 5050)
- **FileBrowser** - File management (Port 8080)
- **Caddy** - Reverse proxy (Ports 80, 443)
- **Setup Helper** - Utility container

### Application Stack (`igny8-app`)
- **Backend** - Django API (Port 8011:8010)
- **Frontend** - React app (Port 8021:5173)
- **Marketing Dev** - Marketing site (Port 8023:5174)
- **Celery Worker** - Async task processing
- **Celery Beat** - Scheduled tasks

### Network Configuration
- **Network Name:** `igny8_net`
- **Type:** External bridge network
- **Purpose:** Inter-container communication

---

## Key Files and Locations

### Backend Key Files
- `backend/igny8_core/auth/middleware.py` - AccountContextMiddleware
- `backend/igny8_core/api/base.py` - AccountModelViewSet, SiteSectorModelViewSet
- `backend/igny8_core/ai/engine.py` - AIEngine orchestrator
- `backend/igny8_core/ai/base.py` - BaseAIFunction
- `backend/igny8_core/ai/tasks.py` - run_ai_task entrypoint
- `backend/igny8_core/api/response.py` - Unified response helpers

### Frontend Key Files
- `frontend/src/services/api.ts` - API client
- `frontend/src/store/authStore.ts` - Authentication state
- `frontend/src/store/siteStore.ts` - Site management
- `frontend/src/templates/` - 4 universal templates
- `frontend/src/config/pages/` - Page configurations

### Documentation
- `docs/01-TECH-STACK-AND-INFRASTRUCTURE.md` - Tech stack
- `docs/02-APPLICATION-ARCHITECTURE.md` - Application architecture
- `docs/03-FRONTEND-ARCHITECTURE.md` - Frontend architecture
- `docs/04-BACKEND-IMPLEMENTATION.md` - Backend implementation
- `docs/05-AI-FRAMEWORK-IMPLEMENTATION.md` - AI framework
- `docs/06-FUNCTIONAL-BUSINESS-LOGIC.md` - Business logic
- `docs/API-COMPLETE-REFERENCE.md` - Complete API reference

---

## Data Flow Examples

### Request Flow
```
1. User Action (e.g., "Auto Cluster Keywords")
   ↓
2. Frontend API Call (fetchAPI)
   ↓
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
```

### 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 (Authorization: Bearer {token})
   ↓
7. Backend Validates Token
   ↓
8. Account Context Set (AccountContextMiddleware)
   ↓
9. Request Processed
```

---

## Security Architecture

### Authentication
- **Primary:** JWT Bearer tokens
- **Fallback:** Session-based auth (admin panel)
- **Token Storage:** localStorage (frontend)
- **Token Expiry:** 15 minutes (access), 7 days (refresh)

### Authorization
- **Role-Based Access Control (RBAC):** Role checked on every request
- **Data Access Control:**
  - Account-level: Automatic filtering by account
  - Site-level: Filtering by accessible sites
  - Action-level: Permission checks in ViewSet actions

### Account Isolation
- All queries filtered by account
- Admin/Developer override for system accounts
- No cross-account data leakage

---

## External Service Integrations

### OpenAI Integration
- **Purpose:** Text generation and image generation
- **Configuration:** API key stored per account in `IntegrationSettings`
- **Services Used:**
  - GPT models for text generation
  - DALL-E for image generation
- **Cost Tracking:** Tracked per request

### Runware Integration
- **Purpose:** Alternative image generation service
- **Configuration:** API key stored per account
- **Model Selection:** e.g., `runware:97@1`
- **Image Type:** realistic, artistic, cartoon

### WordPress Integration
- **Purpose:** Content publishing
- **Configuration:** WordPress URL per site, username and password stored per site
- **Workflow:**
  1. Content generated in IGNY8
  2. Images attached
  3. Content published to WordPress via REST API
  4. Status updated in IGNY8

---

## Development Workflow

### Local Development
1. **Backend:**
   ```bash
   cd backend
   pip install -r requirements.txt
   python manage.py migrate
   python manage.py runserver
   ```

2. **Frontend:**
   ```bash
   cd frontend
   npm install
   npm run dev
   ```

### Docker Development
1. **Build Images:**
   ```bash
   docker build -t igny8-backend -f backend/Dockerfile ./backend
   docker build -t igny8-frontend-dev -f frontend/Dockerfile.dev ./frontend
   ```

2. **Start Services:**
   ```bash
   docker compose -f docker-compose.app.yml -p igny8-app up -d
   ```

---

## Summary

This context document provides a comprehensive overview of the IGNY8 system architecture, including:

1. **System Architecture:** High-level architecture, infrastructure status, technology stack
2. **Core Principles:** Multi-tenancy, configuration-driven, unified AI framework, module-based
3. **System Hierarchy:** Entity relationships, account/site/sector structure
4. **User Roles:** Role hierarchy, permissions, access control
5. **Workflows:** Complete workflows for account setup, keyword management, content generation, WordPress publishing
6. **AI Framework:** Unified execution pipeline, AI functions, progress tracking
7. **Frontend Architecture:** Dual application structure, state management, templates, API integration
8. **Backend Architecture:** Multi-tenancy implementation, base classes, API response format
9. **Module Organization:** Planner, Writer, Thinker, System, Billing, Auth modules
10. **Credit System:** Credit balance management, costs per operation
11. **WordPress Integration:** Publishing process, requirements
12. **Docker Architecture:** Infrastructure and application stacks
13. **Key Files:** Important file locations
14. **Data Flow:** Request and authentication flows
15. **Security:** Authentication, authorization, account isolation
16. **External Services:** OpenAI, Runware, WordPress integrations
17. **Development:** Local and Docker development workflows

This document serves as a comprehensive reference for understanding the complete IGNY8 system architecture and implementation details.

---

**Last Updated:** 2025-01-XX  
**Version:** 1.0.0