salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

DOCS

Browse Source
This commit is contained in:
Desktop
2025-11-12 20:22:08 +05:00
parent 14534dc3ee
commit e4a6bd1160
16 changed files with 2519 additions and 6392 deletions
Download Patch File Download Diff File Expand all files Collapse all files

795
docs/02-APP-ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,795 @@
# IGNY8 Application Architecture
**Last Updated:** 2025-01-XX
**Purpose:** Complete application architecture documentation covering system hierarchy, modules, workflows, features, and data flow.
---
## Table of Contents
1. [System Overview](#system-overview)
2. [System Hierarchy](#system-hierarchy)
3. [User Roles & Access Control](#user-roles--access-control)
4. [Module Organization](#module-organization)
5. [Complete Workflows](#complete-workflows)
6. [Data Models & Relationships](#data-models--relationships)
7. [Multi-Tenancy Architecture](#multi-tenancy-architecture)
8. [API Architecture](#api-architecture)
9. [Security Architecture](#security-architecture)
10. [Integration Points](#integration-points)
---
## System Overview
**IGNY8** is a full-stack SaaS platform for SEO keyword management and AI-driven content generation. The system provides a scalable, multi-account platform that enables users to manage keywords, generate content ideas, create AI-powered content, and publish to WordPress.
### Platform Capabilities
| Capability | Description | Module |
|------------|-------------|--------|
| **Keyword Management** | Import, organize, filter, and manage SEO keywords | Planner |
| **Keyword Clustering** | AI-powered semantic clustering of related keywords | Planner |
| **Content Ideas** | Generate content ideas from keyword clusters | Planner |
| **Content Generation** | AI-powered blog post and article generation | Writer |
| **Image Generation** | AI-powered image generation (DALL-E, Runware) | Writer |
| **WordPress Integration** | Direct publishing to WordPress sites | Writer |
| **Account Management** | Multi-account SaaS with user roles | Auth |
| **Billing & Credits** | Credit-based billing system | Billing |
| **AI Configuration** | Customizable AI prompts and settings | System |
---
## System Hierarchy
### Entity Relationships
```
Account (1) ──< (N) User
Account (1) ──< (1) Subscription ──> (1) Plan
Account (1) ──< (N) Site
Site (1) ──< (1-5) Sector
Sector (1) ──< (N) Keywords, Clusters, ContentIdeas, Tasks
Cluster (1) ──< (N) Keywords (Many-to-Many)
Cluster (1) ──< (N) ContentIdeas
ContentIdeas (1) ──< (N) Tasks
Task (1) ──> (1) Content
Task (1) ──< (N) Images
```
### Hierarchy Details
**Account Level**:
- Top-level organization/workspace
- Contains users, sites, subscriptions, and all data
- Has credit balance and plan assignment
- Status: active, suspended, trial, cancelled
**User Level**:
- Individual user accounts within an account
- Has role (developer, owner, admin, editor, viewer)
- Can belong to only one account
- Access controlled by role and site permissions
**Site Level**:
- Workspace within an account (1-N relationship)
- Can have multiple active sites simultaneously
- Has WordPress integration settings (URL, username, password)
- Can be associated with an industry
- Status: active, inactive, suspended
**Sector Level**:
- Content category within a site (1-5 per site)
- Organizes keywords, clusters, ideas, and tasks
- Can reference an industry sector template
- Status: active, inactive
**Content Level**:
- Keywords, Clusters, ContentIdeas belong to Sector
- Tasks, Content, Images belong to Sector
- All content is automatically associated with Account and Site
---
## User Roles & Access Control
### User Roles
| Role | Access Level | Description | Permissions |
|------|--------------|-------------|-------------|
| **Developer** | System-wide | Full system access, bypasses all restrictions | All accounts, all sites, all data, system settings |
| **Owner** | Account-wide | Full account access, can manage users and billing | All sites in account, user management, billing |
| **Admin** | Account-wide | Account admin access, can manage content and users | All sites in account, content management, user management |
| **Editor** | Site-specific | Content editing access, can manage clusters/tasks | Granted sites only, content editing |
| **Viewer** | Site-specific | Read-only access | Granted sites only, read-only |
| **System Bot** | System-wide | System automation user | All accounts, all sites, all data |
### Access Control Matrix
| User Role | Account Access | Site Access | Data Access | User Management | Billing |
|-----------|----------------|-------------|-------------|------------------|---------|
| Developer | All accounts | All sites | All data | Yes | Yes |
| System Bot | All accounts | All sites | All data | No | No |
| Owner | Own account | All sites in account | All data in account | Yes | Yes |
| Admin | Own account | All sites in account | All data in account | Yes | No |
| Editor | Own account | Granted sites only | Data in granted sites | No | No |
| Viewer | Own account | Granted sites only | Read-only in granted sites | No | No |
### Site Access Control
**Automatic Access**:
- Owners and Admins: Automatic access to all sites in their account
- Developers and System Bot: Access to all sites across all accounts
**Explicit Access**:
- Editors and Viewers: Require explicit `SiteUserAccess` records
- Access granted by Owner or Admin
- Access can be revoked at any time
### Account Isolation
**Principle**: All data is automatically filtered by account.
**Implementation**:
- All models inherit `AccountBaseModel` with `account` ForeignKey
- All ViewSets inherit `AccountModelViewSet` with automatic filtering
- Middleware sets `request.account` from JWT token
- Queries automatically filter by account (except for Developer/System Bot)
---
## Module Organization
### Module Structure
| Module | Purpose | Models | ViewSets | Celery Tasks |
|--------|---------|--------|----------|--------------|
| **Planner** | Keyword management & content planning | Keywords, Clusters, ContentIdeas | KeywordViewSet, ClusterViewSet, ContentIdeasViewSet | auto_cluster_keywords_task, auto_generate_ideas_task |
| **Writer** | Content generation & management | Tasks, Content, Images | TasksViewSet, ImagesViewSet | auto_generate_content_task, auto_generate_images_task |
| **System** | Settings, prompts, integrations | AIPrompt, IntegrationSettings, AuthorProfile, Strategy | AIPromptViewSet, IntegrationSettingsViewSet, AuthorProfileViewSet | - |
| **Billing** | Credits, transactions, usage | CreditTransaction, CreditUsageLog | CreditTransactionViewSet, CreditUsageLogViewSet | - |
| **Auth** | Multi-tenancy, users, accounts | Account, User, Plan, Site, Sector | AccountViewSet, UserViewSet, SiteViewSet, SectorViewSet | - |
### Module Dependencies
```
Auth (Core)
├── Planner (depends on Auth)
├── Writer (depends on Auth, Planner)
├── System (depends on Auth)
└── Billing (depends on Auth)
```
### Module Features
#### Planner Module
**Purpose**: Keyword research, clustering, and content idea generation
**Features**:
- Keyword import (CSV/manual)
- Keyword filtering and organization
- AI-powered keyword clustering
- Content idea generation from clusters
- Keyword-to-cluster mapping
- Cluster metrics and analytics
**Models**:
- `Keywords`: Individual keywords with metrics (volume, difficulty, intent)
- `Clusters`: Groups of related keywords
- `ContentIdeas`: Content ideas generated from clusters
#### Writer Module
**Purpose**: Content generation, image generation, and publishing
**Features**:
- Task creation from content ideas
- AI-powered content generation
- Content editing and review
- Image prompt extraction
- AI-powered image generation
- WordPress publishing
**Models**:
- `Tasks`: Content generation tasks
- `Content`: Generated HTML content
- `Images`: Generated images (featured, in-article)
#### System Module
**Purpose**: System configuration and AI settings
**Features**:
- AI prompt management
- Integration settings (OpenAI, Runware)
- Author profile management
- Content strategy management
- System status and monitoring
**Models**:
- `AIPrompt`: AI prompt templates
- `IntegrationSettings`: API keys and configuration
- `AuthorProfile`: Writing style profiles
- `Strategy`: Content strategies
#### Billing Module
**Purpose**: Credit management and usage tracking
**Features**:
- Credit balance tracking
- Credit transactions
- Usage logging
- Cost tracking
**Models**:
- `CreditTransaction`: Credit additions and deductions
- `CreditUsageLog`: Usage tracking with cost
#### Auth Module
**Purpose**: Multi-tenancy and user management
**Features**:
- Account management
- User management
- Plan management
- Site and sector management
- Industry templates
**Models**:
- `Account`: Top-level organization
- `User`: User accounts
- `Plan`: Subscription plans
- `Site`: Sites within accounts
- `Sector`: Sectors within sites
- `Industry`: Global industry templates
- `IndustrySector`: Industry sector templates
---
## Complete Workflows
### 1. Account Setup Workflow
**Purpose**: Onboard a new account and user
**Steps**:
1. User signs up via `/signup`
2. Account created with default plan
3. Owner user created and linked to account
4. User signs in via `/signin`
5. JWT token generated and returned
6. Frontend stores token and redirects to dashboard
7. User creates first site (optional)
8. User creates sectors (1-5 per site, optional)
9. User configures integration settings (OpenAI, Runware)
10. System ready for use
**Data Created**:
- 1 Account record
- 1 User record (owner role)
- 1 Subscription record (default plan)
- 0-N Site records
- 0-N Sector records (per site)
- 1 IntegrationSettings record (per integration type)
### 2. Keyword Management Workflow
**Purpose**: Import, organize, and cluster keywords
**Steps**:
1. User navigates to `/planner/keywords`
2. User imports keywords via CSV or manual entry
3. Keywords validated and stored in database
4. Keywords displayed in table with filters
5. User filters keywords by sector, status, intent, etc.
6. User selects keywords for clustering
7. User clicks "Auto Cluster" action
8. Backend validates keyword IDs
9. Celery task queued (`auto_cluster_keywords_task`)
10. Task ID returned to frontend
11. Frontend polls progress endpoint
12. Celery worker processes task:
- Loads keywords from database
- Builds AI prompt with keyword data
- Calls OpenAI API for clustering
- Parses cluster response
- Creates Cluster records
- Links keywords to clusters
13. Progress updates sent to frontend
14. Task completes
15. Frontend displays new clusters
16. User can view clusters, edit cluster names, add/remove keywords
**Data Created**:
- N Keyword records (if imported)
- M Cluster records (created by AI)
- N-M Keyword-to-Cluster relationships
**AI Function**: Auto Cluster Keywords
### 3. Content Idea Generation Workflow
**Purpose**: Generate content ideas from keyword clusters
**Steps**:
1. User navigates to `/planner/clusters`
2. User selects one or more clusters
3. User clicks "Generate Ideas" action
4. Backend validates cluster IDs
5. Celery task queued (`auto_generate_ideas_task`)
6. Task ID returned to frontend
7. Frontend polls progress endpoint
8. Celery worker processes task:
- Loads clusters and keywords
- Builds AI prompt with cluster data
- Calls OpenAI API for idea generation
- Parses idea response
- Creates ContentIdeas records
- Links ideas to clusters
9. Progress updates sent to frontend
10. Task completes
11. Frontend displays new content ideas
12. User can view ideas, edit titles, prioritize ideas
**Data Created**:
- N ContentIdeas records (created by AI)
- N ContentIdeas-to-Cluster relationships
**AI Function**: Generate Ideas
### 4. Content Generation Workflow
**Purpose**: Generate AI-powered content from content ideas
**Steps**:
1. User navigates to `/planner/ideas`
2. User selects one or more content ideas
3. User clicks "Create Tasks" action
4. Task records created for each idea
5. User navigates to `/writer/tasks`
6. User selects tasks for content generation
7. User clicks "Generate Content" action
8. Backend validates task IDs
9. Celery task queued (`auto_generate_content_task`)
10. Task ID returned to frontend
11. Frontend polls progress endpoint
12. Celery worker processes task:
- Loads tasks and related data (cluster, keywords, idea)
- Builds AI prompt with task data
- Calls OpenAI API for content generation
- Parses HTML content response
- Creates/updates Content records
- Updates task status
13. Progress updates sent to frontend
14. Task completes
15. Frontend displays generated content
16. User can review and edit content
17. User navigates to `/writer/content` to view content
**Data Created**:
- N Task records (from ideas)
- N Content records (generated HTML)
**AI Function**: Generate Content
### 5. Image Generation Workflow
**Purpose**: Generate images for content
**Steps**:
1. User navigates to `/writer/content`
2. User selects content items
3. User clicks "Generate Image Prompts" action (optional, can skip)
4. Backend validates content IDs
5. Celery task queued (`auto_generate_image_prompts_task`)
6. Task processes:
- Loads content HTML
- Builds AI prompt for prompt extraction
- Calls OpenAI API
- Parses image prompts (featured, in-article)
- Creates/updates Images records with prompts
7. User clicks "Generate Images" action
8. Backend validates image IDs
9. Celery task queued (`auto_generate_images_task`)
10. Task processes:
- Loads images with prompts
- Builds image generation prompt
- Calls OpenAI DALL-E or Runware API
- Receives image URLs
- Updates Images records with URLs
11. Images displayed in frontend
12. User can view images, regenerate, or delete
**Data Created**:
- N Images records (with prompts)
- N Images records (with image URLs)
**AI Functions**: Generate Image Prompts, Generate Images
### 6. WordPress Publishing Workflow
**Purpose**: Publish content to WordPress
**Steps**:
1. User navigates to `/writer/content`
2. User selects content to publish
3. User clicks "Publish to WordPress" action
4. Backend validates:
- Site has WordPress URL configured
- Site has WordPress credentials
- Content is ready (status: review or draft)
5. Backend calls WordPress REST API:
- Creates post with content HTML
- Uploads featured image (if available)
- Uploads in-article images (if available)
- Sets post status (draft, publish)
6. WordPress post ID stored in Content record
7. Content status updated to "published"
8. Frontend displays success message
9. User can view published content in WordPress
**Data Updated**:
- Content record: `wp_post_id`, `status` = "published"
**Integration**: WordPress REST API
### 7. User Management Workflow
**Purpose**: Add users to account and manage permissions
**Steps**:
1. Owner/Admin navigates to `/settings/users`
2. User clicks "Add User" action
3. User enters email and selects role
4. Backend creates User record:
- Email validated (unique per account)
- Role assigned
- Account linked
- Password set (or invitation sent)
5. If role is Editor/Viewer:
- Owner/Admin grants site access
- SiteUserAccess records created
6. New user receives invitation email
7. New user signs in and accesses granted sites
**Data Created**:
- 1 User record
- 0-N SiteUserAccess records (for Editor/Viewer roles)
### 8. Integration Configuration Workflow
**Purpose**: Configure AI service integrations
**Steps**:
1. User navigates to `/settings/integration`
2. User selects integration type (OpenAI, Runware)
3. User enters API key
4. User clicks "Test Connection" (optional)
5. Backend validates API key:
- Makes test API call
- Returns connection status
6. User saves integration settings
7. Backend stores API key in IntegrationSettings
8. Integration ready for use in AI functions
**Data Created/Updated**:
- 1 IntegrationSettings record (per integration type)
**Test Functions**: Test OpenAI, Test Runware
---
## Data Models & Relationships
### Core Models
**Account Model**:
- Fields: name, slug, owner, plan, credits, status
- Relationships: Users (1-N), Sites (1-N), Subscription (1-1)
**User Model**:
- Fields: email, account, role
- Relationships: Account (N-1), SiteUserAccess (N-M via SiteUserAccess)
**Plan Model**:
- Fields: name, price, limits (users, sites, keywords, clusters, etc.), credits
- Relationships: Accounts (1-N via Subscription)
**Site Model**:
- Fields: name, slug, domain, industry, status, wp_url, wp_username, wp_app_password
- Relationships: Account (N-1), Sectors (1-N), Industry (N-1)
**Sector Model**:
- Fields: name, slug, site, industry_sector, status
- Relationships: Site (N-1), IndustrySector (N-1), Keywords/Clusters/Ideas/Tasks (1-N)
### Planner Models
**Keywords Model**:
- Fields: keyword, volume, difficulty, intent, cluster (M-N)
- Relationships: Sector (N-1), Clusters (M-N)
**Clusters Model**:
- Fields: name, description, keywords_count, volume
- Relationships: Sector (N-1), Keywords (M-N), ContentIdeas (1-N)
**ContentIdeas Model**:
- Fields: idea_title, description, cluster, status
- Relationships: Sector (N-1), Cluster (N-1), Tasks (1-N)
### Writer Models
**Tasks Model**:
- Fields: title, description, cluster, idea, status, content
- Relationships: Sector (N-1), Cluster (N-1), ContentIdeas (N-1), Content (1-1), Images (1-N)
**Content Model**:
- Fields: task, html_content, word_count, status, wp_post_id
- Relationships: Task (1-1), Images (1-N)
**Images Model**:
- Fields: task, content, image_type, prompt, image_url, status
- Relationships: Task (N-1), Content (N-1)
### System Models
**AIPrompt Model**:
- Fields: prompt_type, prompt_value, account
- Relationships: Account (N-1)
**IntegrationSettings Model**:
- Fields: integration_type, config (JSON), account
- Relationships: Account (N-1)
**AuthorProfile Model**:
- Fields: name, description, tone, language, account
- Relationships: Account (N-1)
**Strategy Model**:
- Fields: name, description, sector, prompt_types, account
- Relationships: Account (N-1), Sector (N-1)
### Billing Models
**CreditTransaction Model**:
- Fields: account, transaction_type, amount, balance_after
- Relationships: Account (N-1)
**CreditUsageLog Model**:
- Fields: account, operation_type, credits_used, cost_usd
- Relationships: Account (N-1)
---
## Multi-Tenancy Architecture
### Account Isolation
**Implementation Levels**:
1. **Model Level**: All models inherit `AccountBaseModel` with `account` ForeignKey
2. **ViewSet Level**: All ViewSets inherit `AccountModelViewSet` with automatic filtering
3. **Middleware Level**: `AccountContextMiddleware` sets `request.account` from JWT
**Filtering**:
- All queries automatically filter by `account = request.account`
- Developer and System Bot users bypass account filtering
- System accounts bypass account filtering
### Site/Sector Hierarchy
**Purpose**: Organize content within accounts
**Structure**:
```
Account
└── Site 1 (Active)
├── Sector 1 (Active)
│ ├── Keywords
│ ├── Clusters
│ ├── ContentIdeas
│ └── Tasks
├── Sector 2 (Active)
└── Sector 3 (Inactive)
└── Site 2 (Active)
└── Sector 1 (Active)
```
**Constraints**:
- Maximum 5 active sectors per site
- Multiple sites can be active simultaneously
- All content must belong to a site and sector
### Data Isolation Flow
```
Request with JWT Token
↓
AccountContextMiddleware
├── Extract Account ID from JWT
├── Load Account Object
└── Set request.account
↓
ViewSet.get_queryset()
├── Check User Role
├── Filter by Account (if not admin/developer)
└── Filter by Accessible Sites (if not owner/admin)
↓
Database Query
↓
Results (Account-Isolated)
```
---
## API Architecture
### API Structure
**Base URL**: `/api/v1/`
**Module Endpoints**:
- `/api/v1/auth/` - Accounts, users, sites, sectors, plans
- `/api/v1/planner/` - Keywords, clusters, ideas
- `/api/v1/writer/` - Tasks, content, images
- `/api/v1/system/` - Prompts, integrations, author-profiles, strategies
- `/api/v1/billing/` - Credits, transactions, usage
### Authentication Flow
```
1. User Signs In
↓
2. Backend Validates Credentials
↓
3. JWT Token Generated
↓
4. Token Returned to Frontend
↓
5. Frontend Stores Token (localStorage)
↓
6. Frontend Includes Token in Requests (Authorization: Bearer {token})
↓
7. Backend Validates Token
↓
8. Account Context Set
↓
9. Request Processed
```
### Response Format
**Success Response**:
- `success`: true
- `data`: Response data
- `message`: Optional message
**Error Response**:
- `success`: false
- `message`: Error message
- `errors`: Validation errors (if applicable)
**Pagination Response**:
- `count`: Total count
- `next`: Next page URL
- `previous`: Previous page URL
- `results`: Array of results
---
## Security Architecture
### Authentication
**Methods**:
- JWT (JSON Web Tokens) - Primary method
- Session-based auth - Fallback for admin
**Token Management**:
- Tokens stored in localStorage
- Tokens included in `Authorization: Bearer {token}` header
- Token refresh mechanism (future implementation)
### Authorization
**Role-Based Access Control (RBAC)**:
- Role checked on every request
- Permissions enforced at ViewSet level
- Action-level permissions for sensitive operations
**Data Access Control**:
- Account-level: Automatic filtering by account
- Site-level: Filtering by accessible sites
- Action-level: Permission checks in ViewSet actions
### Data Security
**Account Isolation**:
- All queries filtered by account
- Admin/Developer override for system accounts
- No cross-account data leakage
**Site Access Control**:
- Users can only access granted sites
- Admin/Developer override for all sites
- Explicit access grants for Editor/Viewer roles
**API Security**:
- CORS configured for frontend domain
- CSRF enabled for session-based auth
- Input validation via DRF serializers
- Rate limiting (future implementation)
---
## Integration Points
### OpenAI Integration
**Purpose**: Text generation and image generation
**Configuration**:
- API key stored per account in `IntegrationSettings`
- Model selection per account
- Cost tracking per request
**Services Used**:
- GPT models for text generation
- DALL-E for image generation
### 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
---
## Summary
The IGNY8 application architecture provides:
1. **Multi-Tenancy**: Complete account isolation with automatic filtering
2. **Hierarchical Organization**: Account > Site > Sector > Content structure
3. **Role-Based Access**: Granular permissions for different user roles
4. **Module-Based Design**: Clear separation of concerns across modules
5. **Complete Workflows**: End-to-end workflows from keyword import to publishing
6. **AI Integration**: Unified AI framework for all AI operations
7. **WordPress Integration**: Direct publishing to WordPress sites
8. **Credit System**: Credit-based billing and usage tracking
9. **Security First**: JWT auth, RBAC, data isolation
10. **Scalable Design**: Supports multiple accounts, sites, and users
This architecture ensures scalability, maintainability, and extensibility while providing a robust foundation for the IGNY8 platform.