igny8/docs/01-ARCHITECTURE-TECH-STACK.md

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
2. Technology Stack
3. System Architecture
4. Core Architecture Principles
5. Infrastructure Components
6. External Service Integrations
7. 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.