igny8/docs/00-SYSTEM/ARCHITECTURE.md

System Architecture

Last Verified: January 20, 2026
Version: 1.8.4
Backend Path: backend/igny8_core/
Frontend Path: frontend/src/

---

Tech Stack

Layer	Technology	Version	Purpose
Backend Framework	Django	5.1	Web framework
API Layer	Django REST Framework	3.15	REST API
Database	PostgreSQL	16	Primary data store
Cache/Queue	Redis	7	Caching, Celery broker
Task Queue	Celery	5.4	Async task processing
Frontend Framework	React	19	UI framework
Build Tool	Vite	5	Frontend bundler
Styling	Tailwind CSS	3	Utility CSS
State Management	Zustand	4	React state
Language	TypeScript	5	Frontend typing
Web Server	Caddy	2	Reverse proxy, SSL
Containerization	Docker	-	Deployment

---

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        CLIENTS                                   │
│    React SPA (app.igny8.com)  │  WordPress Plugin  │  Admin     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     CADDY (Reverse Proxy)                        │
│              SSL termination, routing, static files              │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    DJANGO REST FRAMEWORK                         │
│                                                                  │
│  Middleware Stack:                                               │
│  SecurityMiddleware → WhiteNoise → CORS → Session → CSRF →      │
│  DjangoAuth → RequestIDMiddleware → AccountContextMiddleware →   │
│  ResourceTrackingMiddleware                                      │
│                                                                  │
│  API: /api/v1/* → ViewSets → Services → Models                  │
└─────────────────────────────────────────────────────────────────┘
          │                              │
          ▼                              ▼
┌─────────────────────┐    ┌─────────────────────────────────────┐
│     PostgreSQL      │    │              Redis                   │
│   Primary Database  │    │  Sessions, Cache, Celery Broker     │
└─────────────────────┘    └─────────────────────────────────────┘
                                         │
                                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                      CELERY WORKERS                              │
│       AI Tasks, Automation, Publishing, Background Jobs          │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    EXTERNAL SERVICES                             │
│  OpenAI  │  Anthropic  │  Runware  │  Bria  │  WordPress Sites  │
└─────────────────────────────────────────────────────────────────┘

---

Backend Structure

backend/igny8_core/
├── settings.py              # Django settings, all config
├── urls.py                  # Root URL routing
├── celery.py                # Celery configuration
├── wsgi.py / asgi.py        # WSGI/ASGI entry points
│
├── auth/                    # Authentication & tenancy
│   ├── models.py            # User, Account, Site, Sector, Plan
│   ├── views.py             # Login, register, password reset
│   ├── middleware.py        # AccountContextMiddleware
│   └── urls.py              # /api/v1/auth/*
│
├── api/                     # API infrastructure
│   ├── base.py              # AccountModelViewSet, SiteSectorModelViewSet
│   ├── authentication.py    # JWT, API key auth classes
│   └── pagination.py        # Unified pagination
│
├── ai/                      # AI engine
│   ├── engine.py            # AIEngine orchestrator
│   ├── functions/           # AutoCluster, GenerateIdeas, GenerateContent, etc.
│   ├── registry.py          # Function registry
│   ├── model_registry.py    # Model Registry service (v1.3.0)
│   └── progress.py          # Progress tracking
│
├── modules/                 # Feature modules (API layer)
│   ├── planner/             # Keywords, Clusters, Ideas
│   ├── writer/              # Tasks, Content, Images
│   ├── billing/             # Credits, usage, transactions
│   ├── integration/         # WordPress integration
│   ├── system/              # Settings, prompts, AI config
│   ├── linker/              # Internal linking (inactive)
│   ├── optimizer/           # Content optimization (inactive)
│   └── publisher/           # Publishing pipeline
│
├── business/                # Business logic (services)
│   ├── automation/          # 7-stage automation pipeline
│   ├── billing/             # Credit service, payment processing
│   ├── content/             # Content generation orchestration
│   ├── integration/         # Sync services
│   ├── linking/             # Link processing
│   ├── notifications/       # Notification system (v1.2.0)
│   ├── optimization/        # Content optimization
│   ├── planning/            # Clustering, idea generation
│   └── publishing/          # Publishing orchestration
│
├── middleware/              # Custom middleware
│   ├── request_id.py        # X-Request-ID header
│   └── resource_tracker.py  # Resource tracking for admins
│
└── tasks/                   # Celery tasks
    └── *.py                 # Background job definitions

---

Frontend Structure

frontend/src/
├── main.tsx                 # Entry point
├── App.tsx                  # Root component, routing
├── index.css                # Global styles, Tailwind
│
├── api/                     # API clients
│   ├── linker.api.ts
│   ├── optimizer.api.ts
│   └── ...
│
├── services/
│   ├── api.ts               # Main API service (2500+ lines)
│   └── notifications.api.ts # Notification API (v1.2.0)
│
├── store/                   # Zustand stores
│   ├── authStore.ts         # Authentication state
│   ├── siteStore.ts         # Active site
│   ├── sectorStore.ts       # Active sector
│   ├── billingStore.ts      # Billing state
│   ├── moduleStore.ts       # Module enable/disable
│   ├── notificationStore.ts # Notifications (v1.2.0)
│   └── ...
│
├── pages/                   # Route pages
│   ├── Dashboard/
│   ├── Planner/
│   ├── Writer/
│   ├── Automation/
│   ├── Linker/
│   ├── Optimizer/
│   ├── Settings/
│   ├── Billing/
│   └── Auth/
│
├── components/              # Reusable components
│   ├── common/
│   │   ├── ProgressModal.tsx    # AI progress display
│   │   ├── SearchModal.tsx      # Global search (v1.1.9)
│   │   └── ...
│   ├── dashboard/           # Dashboard widgets (v1.2.0)
│   │   ├── WorkflowPipelineWidget.tsx
│   │   ├── AIOperationsWidget.tsx
│   │   ├── RecentActivityWidget.tsx
│   │   ├── ContentVelocityWidget.tsx
│   │   ├── AutomationStatusWidget.tsx
│   │   ├── ThreeWidgetFooter.tsx
│   │   └── ...
│   └── header/
│       └── NotificationDropdown.tsx
│
├── context/                 # React contexts (v1.1.9)
│   └── PageContext.tsx      # Page-level state
│
├── layout/                  # Layout components
│   ├── AppLayout.tsx
│   ├── AppHeader.tsx
│   └── AppSidebar.tsx
│
├── hooks/                   # Custom hooks
│   └── useWorkflowStats.ts  # Automation stats hook (v1.3.0)
├── context/                 # React contexts
└── utils/                   # Utility functions

---

Key Design Patterns

1. Multi-Tenant Data Isolation

All data is scoped to Account, with optional Site and Sector filtering:

Account (Tenant)
  └── Site (e.g., myblog.com)
      └── Sector (e.g., Technology, Health)
          └── Keywords/Clusters/Ideas/Content

Implementation:

• AccountBaseModel - Base class for account-scoped models
• SiteSectorBaseModel - Base class for site/sector-scoped models
• AccountModelViewSet - Auto-filters queryset by request.account
• SiteSectorModelViewSet - Auto-filters by account + site + sector

2. Middleware-First Tenant Resolution

# Order in settings.py MIDDLEWARE
1. SecurityMiddleware
2. WhiteNoiseMiddleware
3. CorsMiddleware
4. SessionMiddleware
5. DjangoAuthenticationMiddleware
6. RequestIDMiddleware        # Assigns X-Request-ID
7. AccountContextMiddleware   # Sets request.account from session/JWT
8. ResourceTrackingMiddleware # Optional admin profiling

3. Unified API Responses

All API responses follow this structure:

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

Error responses:

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

4. Credit-Based Operations

All AI operations check and deduct credits:

1. Pre-check: CreditService.check_credits()
2. Execute: AI function runs
3. Post-deduct: CreditService.deduct_credits_for_operation()

---

Environment Configuration

Key environment variables (from settings.py):

Variable	Purpose
DATABASE_URL	PostgreSQL connection
REDIS_URL	Redis connection
SECRET_KEY	Django secret
JWT_SECRET_KEY	JWT signing key
CORS_ALLOWED_ORIGINS	Allowed frontend origins
CELERY_BROKER_URL	Celery broker (Redis)

AI keys are stored in GlobalIntegrationSettings (database), not env vars.

---

Deployment Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Docker Compose                               │
│                                                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   Frontend  │  │   Backend   │  │   Worker    │              │
│  │   (Caddy)   │  │  (Django)   │  │  (Celery)   │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│         │                │                │                      │
│         └────────────────┼────────────────┘                      │
│                          │                                       │
│  ┌─────────────┐  ┌─────────────┐                               │
│  │ PostgreSQL  │  │    Redis    │                               │
│  └─────────────┘  └─────────────┘                               │
└─────────────────────────────────────────────────────────────────┘

---

Model Registry (v1.3.0)

The Model Registry provides centralized AI model configuration with database-stored pricing and settings:

# backend/igny8_core/ai/model_registry.py
from igny8_core.modules.system.models import AIModelConfig

class ModelRegistry:
    """Centralized AI model configuration service"""
    
    @classmethod
    def get_model(cls, model_id: str) -> AIModelConfig:
        """Get model config by ID"""
        return AIModelConfig.objects.get(model_id=model_id)
    
    @classmethod
    def get_active_models_by_type(cls, model_type: str) -> QuerySet:
        """Get all active models for a type (text, image, etc.)"""
        return AIModelConfig.objects.filter(
            model_type=model_type,
            is_active=True
        )

Supported Providers:

Provider	Types	Integration
OpenAI	Text, Image	GPT-4o, GPT-4-turbo, DALL-E 3
Anthropic	Text	Claude 3.5 Sonnet, Claude 3 Opus
Runware	Image	RunwareFLUX, SD 3.5
Bria	Image	Bria 2.3

---

Planned Changes

Feature	Status	Description
AIModelConfig Database	✅ v1.3.0	Move AI model pricing from constants to database
Multi-provider AI	✅ v1.3.0	Support for Anthropic, Bria
Module Guard Extension	🔜 Planned	Extend linker/optimizer disable to all pages (currently sidebar only)
Google AI Integration	🔜 Planned	Support for Gemini models