477 lines
17 KiB
Markdown
477 lines
17 KiB
Markdown
# 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.
|
|
|