309 lines
14 KiB
Markdown
309 lines
14 KiB
Markdown
# System Architecture
|
|
|
|
**Last Verified:** December 27, 2025
|
|
**Version:** 1.2.0
|
|
**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
|
|
│ ├── 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
|
|
├── 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 |
|