# System Architecture

**Last Verified:** December 25, 2025  
**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 | 18 | 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 API (GPT-4, DALL-E)  │  Runware  │  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
│   └── 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
│   ├── 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)
│
├── store/                   # Zustand stores
│   ├── authStore.ts         # Authentication state
│   ├── siteStore.ts         # Active site
│   ├── sectorStore.ts       # Active sector
│   ├── billingStore.ts      # Billing state
│   ├── moduleStore.ts       # Module enable/disable
│   └── ...
│
├── pages/                   # Route pages
│   ├── Dashboard/
│   ├── Planner/
│   ├── Writer/
│   ├── Automation/
│   ├── Linker/
│   ├── Optimizer/
│   ├── Settings/
│   ├── Billing/
│   └── Auth/
│
├── components/              # Reusable components
│   ├── ProgressModal.tsx    # AI progress display
│   ├── ConfirmDialog.tsx
│   └── ...
│
├── layout/                  # Layout components
│   ├── AppLayout.tsx
│   └── AppSidebar.tsx
│
├── hooks/                   # Custom hooks
├── 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

```python
# 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:

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

Error responses:
```json
{
  "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    │                               │
│  └─────────────┘  └─────────────┘                               │
└─────────────────────────────────────────────────────────────────┘
```

---

## Planned Changes

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