# IGNY8 Architecture & Technology Stack

**Last Updated:** 2025-01-XX  
**Purpose:** Complete technology stack and architecture overview for the IGNY8 platform.

---

## Table of Contents

1. [Executive Summary](#executive-summary)
2. [Technology Stack](#technology-stack)
3. [System Architecture](#system-architecture)
4. [Core Architecture Principles](#core-architecture-principles)
5. [Infrastructure Components](#infrastructure-components)
6. [External Service Integrations](#external-service-integrations)
7. [Deployment Architecture](#deployment-architecture)

---

## Executive Summary

**IGNY8** is a full-stack SaaS platform for SEO keyword management and AI-driven content generation. The system is built with modern technologies and follows a multi-tenant architecture with complete account isolation.

### 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
- **Reverse Proxy**: Caddy (HTTPS termination)
- **AI Functions**: 5 primary AI operations
- **Modules**: 4 core modules (Planner, Writer, System, Billing)

---

## 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) |

---

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

---

## 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 `AIEngine` class orchestrates all AI operations
- All AI functions inherit from `BaseAIFunction`
- Manual and automated workflows use same functions
- 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
- **Auth**: Accounts, Users, Sites, Sectors

---

## Infrastructure Components

### Docker Architecture

The system uses a two-stack Docker architecture:

1. **Infrastructure Stack (`igny8-infra`)**: Shared services
2. **Application Stack (`igny8-app`)**: Application-specific services

### Infrastructure Stack Services

| Service | Container Name | Port | Purpose |
|---------|----------------|------|---------|
| **PostgreSQL** | `igny8_postgres` | 5432 (internal) | Database |
| **Redis** | `igny8_redis` | 6379 (internal) | Cache & Celery broker |
| **pgAdmin** | `igny8_pgadmin` | 5050:80 | Database administration |
| **FileBrowser** | `igny8_filebrowser` | 8080:80 | File management |
| **Caddy** | `igny8_caddy` | 80:80, 443:443 | Reverse proxy & HTTPS |
| **Setup Helper** | `setup-helper` | - | Utility container |

### Application Stack Services

| Service | Container Name | Port | Purpose |
|---------|----------------|------|---------|
| **Backend** | `igny8_backend` | 8011:8010 | Django REST API |
| **Frontend** | `igny8_frontend` | 8021:5173 | React application |
| **Celery Worker** | `igny8_celery_worker` | - | Async task processing |
| **Celery Beat** | `igny8_celery_beat` | - | Scheduled tasks |

### Network Configuration

- **Network Name**: `igny8_net`
- **Type**: External bridge network
- **Purpose**: Inter-container communication
- **Creation**: Must be created manually before starting stacks

### Volume Management

**Infrastructure Volumes**:
- `pgdata`: PostgreSQL database data
- `redisdata`: Redis data
- `pgadmin_data`: pgAdmin configuration
- `filebrowser_db`: FileBrowser database
- `caddy_data`: Caddy SSL certificates
- `caddy_config`: Caddy configuration

**Application Volumes**:
- Host mounts for application code
- Host mounts for logs
- Docker socket for container management

### Port Allocation

| Service | External Port | Internal Port | Access |
|---------|---------------|---------------|--------|
| **pgAdmin** | 5050 | 80 | http://localhost:5050 |
| **FileBrowser** | 8080 | 80 | http://localhost:8080 |
| **Caddy** | 80, 443 | 80, 443 | https://domain.com |
| **Backend** | 8011 | 8010 | http://localhost:8011 |
| **Frontend** | 8021 | 5173 | http://localhost:8021 |

---

## External Service Integrations

### OpenAI Integration

**Purpose**: Text generation and image generation

**Services Used**:
- GPT models for text generation
- DALL-E for image generation

**Configuration**:
- API key stored per account in `IntegrationSettings`
- Model selection per account
- Cost tracking per request

### Runware Integration

**Purpose**: Alternative image generation service

**Configuration**:
- API key stored per account
- Model selection (e.g., `runware:97@1`)
- Image type selection (realistic, artistic, cartoon)

### WordPress Integration

**Purpose**: Content publishing

**Configuration**:
- WordPress URL per site
- Username and password stored per site
- REST API integration for publishing

**Workflow**:
1. Content generated in IGNY8
2. Images attached
3. Content published to WordPress via REST API
4. Status updated in IGNY8

### Stripe Integration (Planned)

**Purpose**: Payment processing

**Status**: Planned for future implementation

**Features**:
- Subscription management
- Payment processing
- Webhook integration

---

## Deployment Architecture

### Deployment Model

**Container-Based**: All services run in Docker containers

**Stack Separation**:
- Infrastructure stack runs independently
- Application stack depends on infrastructure stack
- Both stacks share the same Docker network

### Environment Configuration

**Backend Environment Variables**:
- Database connection (PostgreSQL)
- Redis connection
- Django settings (DEBUG, SECRET_KEY, etc.)
- JWT settings
- Celery configuration

**Frontend Environment Variables**:
- Backend API URL
- Environment (development/production)

**Infrastructure Environment Variables**:
- PostgreSQL credentials
- pgAdmin credentials
- FileBrowser configuration

### Health Checks

**Backend Health Check**:
- Endpoint: `/api/v1/system/status/`
- Interval: 30 seconds
- Timeout: 10 seconds
- Retries: 3

**PostgreSQL Health Check**:
- Command: `pg_isready`
- Interval: 20 seconds
- Timeout: 3 seconds
- Retries: 5

**Redis Health Check**:
- Command: `redis-cli ping`
- Interval: 20 seconds
- Timeout: 3 seconds
- Retries: 5

### Scaling Considerations

**Horizontal Scaling**:
- Multiple Celery workers can be added
- Multiple backend instances can be added (with load balancer)
- Frontend can be scaled independently

**Vertical Scaling**:
- Database can be scaled with more resources
- Redis can be scaled with more memory
- Containers can be allocated more CPU/memory

### Backup & Recovery

**Database Backups**:
- PostgreSQL dumps stored in `/data/backups`
- Automated backup scripts
- Point-in-time recovery support

**Volume Backups**:
- Docker volume backups
- Application code backups
- Configuration backups

---

## Summary

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

- **Django 5.2+** for the backend API
- **React 19** for the frontend
- **PostgreSQL 15** for data storage
- **Celery & Redis** for async processing
- **Docker** for containerization
- **Caddy** for reverse proxy and HTTPS

The architecture follows principles of:
- Configuration-driven development
- Multi-tenancy with account isolation
- Module-based organization
- Unified AI processing
- Template-based UI rendering

This architecture supports scalability, maintainability, and rapid feature development while ensuring data security and isolation.