igny8/master-docs/06-FUNCTIONAL-BUSINESS-LOGIC.md

# IGNY8 Functional Business Logic Documentation

**Last Updated:** 2025-01-XX (Workflow updated - Wizard removed)  
**Purpose:** Complete functional and business logic documentation covering all workflows, functions, features, and how the application works from a business perspective.

---

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [System Overview](#system-overview)
3. [Complete User Workflow](#complete-user-workflow)
4. [Account and User Management](#account-and-user-management)
5. [Planner Module - Complete Workflows](#planner-module---complete-workflows)
6. [Writer Module - Complete Workflows](#writer-module---complete-workflows)
7. [Thinker Module - Complete Workflows](#thinker-module---complete-workflows)
8. [System Module - Complete Workflows](#system-module---complete-workflows)
9. [Billing Module - Complete Workflows](#billing-module---complete-workflows)
10. [AI Functions - Complete Details](#ai-functions---complete-details)
11. [Credit System - How It Works](#credit-system---how-it-works)
12. [WordPress Integration](#wordpress-integration)
13. [Data Flow and State Management](#data-flow-and-state-management)
14. [Complete Feature List](#complete-feature-list)

---

## Prerequisites

### Technology Stack Required

**Backend Technologies:**
- Django
- Django REST Framework
- PostgreSQL
- Celery
- Redis
- Python

**Frontend Technologies:**
- React
- TypeScript
- Vite
- Tailwind CSS
- Zustand
- React Router

**Infrastructure:**
- Docker
- Docker Compose
- Caddy

**External Services:**
- OpenAI API
- Runware API (optional)
- WordPress (optional)

---

## System Overview

IGNY8 is a SaaS platform for SEO keyword management and AI-driven content generation. The system operates on a multi-tenant architecture where each account is completely isolated. Users work within accounts, manage sites, organize content by sectors, and use AI to generate content from keywords.

### Core Business Flow

1. **Account Setup**: User creates account, sets up sites and sectors
2. **Keyword Management**: Import keywords, organize by sector, cluster related keywords
3. **Content Planning**: Generate content ideas from keyword clusters
4. **Content Creation**: Create tasks from ideas, generate AI content
5. **Image Generation**: Generate images for content
6. **Publishing**: Publish content to WordPress sites

### Key Business Concepts

- **Account**: Top-level organization containing all data
- **Site**: Workspace within account (can have multiple sites)
- **Sector**: Content category within site (1-5 per site)
- **Keywords**: SEO keywords organized by sector
- **Clusters**: AI-grouped related keywords
- **Content Ideas**: AI-generated content ideas from clusters
- **Tasks**: Content generation tasks created from ideas
- **Content**: Generated HTML blog posts and articles
- **Images**: AI-generated images for content
- **Credits**: Currency for AI operations

---

## Complete User Workflow

### Current Workflow Path (Updated 2025-01-XX)

The Site Builder Wizard has been removed. The workflow now follows a direct path:

```
PLANNING → WRITER → OPTIMIZE → PUBLISH
```

**Direct Path:** Keywords/Clusters → Ideas → Tasks → Content (no wizard intermediary)

### Phase Flow Summary

```
┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ PLANNING │ --> │  WRITER  │ --> │OPTIMIZE │ --> │ PUBLISH  │
│          │     │          │     │         │     │          │
│Keywords  │     │Content   │     │Link &   │     │Deploy    │
│Clusters  │     │Generate  │     │Optimize │     │Site      │
│ Ideas    │     │ Images   │     │         │     │          │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
```

### Complete Workflow Steps

#### Phase 1: Planning & Keyword Research

1. **Keyword Discovery**
   - Navigate to `/planner/keyword-opportunities`
   - Browse keyword database
   - Identify target keywords

2. **Keyword Import**
   - Navigate to `/planner/keywords`
   - Import CSV or manual entry
   - Keywords stored by sector

3. **Keyword Clustering**
   - Select keywords → "Auto-Cluster"
   - AI clustering (1 credit per 30 keywords)
   - Clusters created automatically

4. **Cluster Management**
   - Navigate to `/planner/clusters`
   - Review & refine clusters
   - Merge/split clusters as needed
   - Clusters ready for content generation

5. **Content Ideas Generation**
   - Navigate to `/planner/ideas`
   - Generate ideas from clusters (1 credit per idea)
   - Review and refine ideas
   - Queue ideas to Writer

#### Phase 2: Content Creation (Writer)

1. **Task Creation**
   - Ideas automatically create tasks
   - Navigate to `/writer/tasks`
   - Review tasks from ideas

2. **Content Generation**
   - Select tasks → "Generate Content"
   - AI content generation (3 credits per content)
   - HTML content with structured blocks
   - Meta tags automatically generated

3. **Content Review**
   - Navigate to `/writer/content`
   - Review & edit HTML content
   - Update metadata (title, description, keywords)
   - Validate content structure

4. **Image Generation**
   - Navigate to `/writer/images`
   - Generate image prompts (optional)
   - Generate images (1 credit per image)
   - Featured and in-article images

#### Phase 3: Optimization & Linking

1. **Internal Linking**
   - Navigate to `/linker/content`
   - System analyzes content
   - Suggests internal links (cluster matches prioritized)
   - Accept/reject link suggestions

2. **Content Optimization**
   - Navigate to `/optimizer/content`
   - System scores content
   - Review optimization suggestions
   - Apply improvements

#### Phase 4: Publishing

1. **Content Validation**
   - Navigate to `/sites/:id/posts/:postId`
   - Validate entity type, cluster mapping, taxonomy
   - Ensure all attributes complete

2. **WordPress Publishing**
   - Select content → "Publish to WordPress"
   - System validates WordPress connection
   - Content published to WordPress site
   - Images uploaded and linked

3. **Site Deployment** (for IGNY8-hosted sites)
   - Navigate to `/sites/:id/deploy`
   - Review cluster coverage
   - Validate content completeness
   - Deploy site to sites.igny8.com/{slug}

### Workflow Variations

#### Workflow A: New IGNY8-Hosted Site
- Complete build from scratch
- Full workflow: Planning → Writer → Optimize → Publish → Deploy

#### Workflow B: Existing Site Management
- Add new content to existing site
- Manage existing content
- Update and republish content

#### Workflow C: WordPress Sync - New Site
- Connect new WordPress site
- Sync existing content
- Continue with normal workflow

#### Workflow D: WordPress Sync - Existing Site
- Connect existing WordPress site
- Import existing posts
- Sync and manage content

### Site Builder Status

**Removed Features:**
- ❌ Site Builder Wizard (6-step guided process)
- ❌ WorkflowState model and services
- ❌ Wizard UI components and routes

**Available Features:**
- ✅ Site Blueprint APIs (create/manage via API)
- ✅ Site Builder models (SiteBlueprint, PageBlueprint, etc.)
- ✅ Direct workflow path (Planning → Writer)

**Note:** Site blueprints can still be created and managed through API endpoints, but there is no guided UI wizard. Users proceed directly from Planning to Writer.

---

## Account and User Management

### Account Creation and Setup

**Workflow:**
1. User visits signup page
2. User provides email and password
3. System creates Account record with default plan
4. System creates User record with "owner" role
5. System creates Subscription record linking account to plan
6. User receives confirmation
7. User signs in and receives JWT token
8. Frontend stores token and redirects to dashboard

**Data Created:**
- Account record (name, slug, owner, plan, credits, status)
- User record (email, account, role: owner)
- Subscription record (account, plan, status)

### User Roles and Permissions

**Roles:**
- **Developer**: Full system access, bypasses all restrictions
- **Owner**: Full account access, manages users and billing
- **Admin**: Account admin, manages content and users
- **Editor**: Content editing access for granted sites only
- **Viewer**: Read-only access for granted sites only
- **System Bot**: System automation user

**Access Control:**
- Owners and Admins: Automatic access to all sites in account
- Editors and Viewers: Require explicit site access grants
- Developers and System Bot: Access to all sites across all accounts

### Site and Sector Management

**Site Creation:**
1. User navigates to Settings → Sites
2. User creates site with name, domain, industry
3. System creates Site record linked to account
4. User can configure WordPress integration (URL, username, password)
5. Site becomes available for content organization

**Sector Creation:**
1. User navigates to site details
2. User creates sector (1-5 active sectors per site)
3. System creates Sector record linked to site
4. Sector becomes available for keyword and content organization

**Constraints:**
- Maximum 5 active sectors per site
- Multiple sites can be active simultaneously
- All content must belong to a site and sector

---

## Planner Module - Complete Workflows

### Keyword Management

**Keyword Import (CSV):**
1. User navigates to Planner → Keywords
2. User clicks "Import CSV" action
3. User uploads CSV file with columns: keyword, volume, difficulty, intent
4. System validates CSV format and data
5. System checks for duplicates
6. System creates Keyword records for each row
7. Keywords are linked to selected site and sector
8. Keywords appear in table with status "active"

**Keyword Import (Manual):**
1. User navigates to Planner → Keywords
2. User clicks "Add Keyword" action
3. User enters keyword, volume, difficulty, intent
4. System validates keyword uniqueness within sector
5. System creates Keyword record
6. Keyword appears in table

**Keyword Filtering:**
- Filter by sector
- Filter by status (active, inactive, archived)
- Filter by intent (informational, navigational, transactional, commercial)
- Filter by cluster (clustered, unclustered)
- Filter by difficulty range (min/max)
- Filter by volume range (min/max)
- Search by keyword text

**Keyword Bulk Operations:**
- Bulk delete: Select multiple keywords, delete all
- Bulk update status: Select multiple keywords, change status
- Bulk add from seed: Add keywords from seed keyword library

**Keyword Export:**
1. User applies filters (optional)
2. User clicks "Export CSV" action
3. System generates CSV file with filtered keywords
4. User downloads CSV file

### Keyword Clustering

**Auto Cluster Workflow:**
1. User navigates to Planner → Keywords
2. User selects keywords (maximum 20 per batch)
3. User clicks "Auto Cluster" action
4. System validates keyword IDs and account credits
5. System queues Celery task (`run_ai_task` with function `auto_cluster`)
6. System returns task ID to frontend
7. Frontend polls progress endpoint (`/api/v1/system/settings/task_progress/{task_id}/`)
8. Celery worker processes task:
   - Loads keywords from database
   - Builds AI prompt with keyword data (keyword, volume, difficulty, intent)
   - Calls OpenAI API with clustering prompt
   - Parses AI response (cluster names and keyword assignments)
   - Creates Cluster records for each cluster
   - Links keywords to clusters (Many-to-Many relationship)
   - Updates cluster metrics (keywords_count, volume)
9. Progress updates sent to frontend (phases: INIT, PREP, AI_CALL, PARSE, SAVE, DONE)
10. Task completes
11. Frontend displays new clusters
12. Credits deducted from account (1 credit per 30 keywords)

**Manual Cluster Management:**
1. User navigates to Planner → Clusters
2. User views clusters with keyword counts and volumes
3. User can edit cluster name and description
4. User can add keywords to cluster
5. User can remove keywords from cluster
6. User can delete cluster (keywords remain, just unlinked)

**Cluster Filtering:**
- Filter by sector
- Filter by status
- Search by cluster name
- Sort by keywords_count, volume, created_at

### Content Idea Generation

**Generate Ideas Workflow:**
1. User navigates to Planner → Clusters
2. User selects one cluster (maximum 1 per batch)
3. User clicks "Generate Ideas" action
4. System validates cluster ID and account credits
5. System queues Celery task (`run_ai_task` with function `generate_ideas`)
6. System returns task ID to frontend
7. Frontend polls progress endpoint
8. Celery worker processes task:
   - Loads cluster and associated keywords
   - Builds AI prompt with cluster data (cluster name, keywords, sector context)
   - Calls OpenAI API with idea generation prompt
   - Parses AI response (idea titles, descriptions, content types, structures)
   - Creates ContentIdeas records for each idea
   - Links ideas to cluster
9. Progress updates sent to frontend
10. Task completes
11. Frontend displays new content ideas
12. Credits deducted from account (1 credit per idea)

**Content Ideas Management:**
1. User navigates to Planner → Ideas
2. User views ideas with titles, descriptions, content types
3. User can edit idea title and description
4. User can change idea status (active, inactive, archived)
5. User can delete idea
6. User can create tasks from ideas (moves to Writer module)

**Idea Filtering:**
- Filter by sector
- Filter by cluster
- Filter by status
- Filter by content type
- Search by idea title

**Bulk Queue to Writer:**
1. User selects multiple ideas
2. User clicks "Queue to Writer" action
3. System creates Task records for each idea
4. Tasks are linked to ideas and clusters
5. Tasks appear in Writer → Tasks page

---

## Writer Module - Complete Workflows

### Task Management

**Task Creation:**
1. User navigates to Writer → Tasks
2. User can create task manually or from content ideas
3. If from ideas: System creates task with idea data (title, description, cluster, idea)
4. If manual: User enters title, description, selects cluster, content type, structure
5. System creates Task record
6. Task appears in table with status "draft"

**Task Filtering:**
- Filter by sector
- Filter by cluster
- Filter by status (draft, in_progress, review, completed, archived)
- Filter by content type
- Filter by content structure
- Search by title or keywords

**Task Bulk Operations:**
- Bulk delete: Select multiple tasks, delete all
- Bulk update status: Select multiple tasks, change status

### Content Generation

**Generate Content Workflow:**
1. User navigates to Writer → Tasks
2. User selects tasks (maximum 50 per batch)
3. User clicks "Generate Content" action
4. System validates task IDs and account credits
5. System queues Celery task (`run_ai_task` with function `generate_content`)
6. System returns task ID to frontend
7. Frontend polls progress endpoint
8. Celery worker processes task (for each task):
   - Loads task and related data (cluster, keywords, idea, sector, site)
   - Builds AI prompt with task data (title, description, keywords, content type, structure)
   - Calls OpenAI API with content generation prompt
   - Parses HTML content response
   - Creates or updates Content record with HTML
   - Calculates word count
   - Updates task status to "review"
9. Progress updates sent to frontend (per task)
10. Task completes
11. Frontend displays generated content
12. Credits deducted from account (3 credits per content piece)

**Content Management:**
1. User navigates to Writer → Content
2. User views content list with titles, word counts, status
3. User clicks content to view full HTML
4. User can edit content HTML directly
5. User can update content status (draft, review, published)
6. User can update meta title and description
7. User can update primary and secondary keywords

**Content Filtering:**
- Filter by sector
- Filter by status
- Filter by content type
- Search by title or keywords
- Sort by word count, created_at, status

**Content Views:**
- Drafts: Content with status "draft"
- Published: Content with status "published" and wp_post_id set
- All Content: All content regardless of status

### Image Generation

**Generate Image Prompts Workflow:**
1. User navigates to Writer → Content
2. User selects content items
3. User clicks "Generate Image Prompts" action (optional)
4. System validates content IDs
5. System queues Celery task (`run_ai_task` with function `generate_image_prompts`)
6. Celery worker processes task:
   - Loads content HTML
   - Builds AI prompt for image prompt extraction
   - Calls OpenAI API
   - Parses image prompts (featured image prompt, 1-6 in-article image prompts)
   - Creates or updates Images records with prompts
   - Sets image_type (featured, in_article)
7. Task completes
8. Images appear in Writer → Images page with prompts ready

**Generate Images Workflow:**
1. User navigates to Writer → Images
2. User selects images with prompts
3. User clicks "Generate Images" action
4. System validates image IDs and account credits
5. System queues Celery task (`run_ai_task` with function `generate_images`)
6. System returns task ID to frontend
7. Frontend polls progress endpoint
8. Celery worker processes task (for each image sequentially):
   - Loads image with prompt
   - Determines image provider (OpenAI DALL-E or Runware) from integration settings
   - Builds image generation request
   - Calls OpenAI DALL-E API or Runware API
   - Receives image URL
   - Updates Images record with image_url
   - Sets image status to "completed"
9. Progress updates sent to frontend (per image)
10. Task completes
11. Frontend displays generated images
12. Credits deducted from account (1 credit per image)

**Image Management:**
1. User navigates to Writer → Images
2. User views images with prompts, URLs, types, status
3. User can view image by clicking
4. User can regenerate image (creates new image with same prompt)
5. User can delete image
6. User can update image status

**Image Filtering:**
- Filter by content
- Filter by image type (featured, in_article, desktop, mobile)
- Filter by status
- Filter by task

**Image Bulk Operations:**
- Bulk update status: Select multiple images, change status

### WordPress Publishing

**Publish to WordPress Workflow:**
1. User navigates to Writer → Content
2. User selects content to publish
3. User clicks "Publish to WordPress" action
4. System validates:
   - Site has WordPress URL configured (wp_url field)
   - Site has WordPress credentials (wp_username, wp_app_password)
   - Content status is "review" or "draft"
5. System calls WordPress REST API:
   - Authenticates with WordPress using credentials
   - Creates post with content HTML (title from content meta_title or task title)
   - Sets post content to content HTML
   - Uploads featured image if available (Images record with image_type="featured")
   - Uploads in-article images if available (Images records with image_type="in_article")
   - Sets post status (draft or publish based on content status)
   - Sets post meta (primary_keyword, secondary_keywords)
6. WordPress returns post ID
7. System updates Content record:
   - Sets wp_post_id field
   - Sets status to "published"
8. Frontend displays success message
9. User can view published content in WordPress

**Publishing Requirements:**
- Site must have WordPress URL configured
- Site must have WordPress username and app password
- Content must have status "review" or "draft"
- Featured image is optional but recommended

---

## Thinker Module - Complete Workflows

### AI Prompts Management

**Prompt Management:**
1. User navigates to Thinker → Prompts
2. User views all AI prompts used in the system
3. User can view prompt details (prompt_type, prompt_value, function_name)
4. User can edit prompt value
5. User can reset prompt to default value
6. System uses prompts in AI function execution

**Prompt Types:**
- `auto_cluster`: Prompt for keyword clustering
- `generate_ideas`: Prompt for content idea generation
- `generate_content`: Prompt for content generation
- `generate_image_prompts`: Prompt for extracting image prompts from content
- `generate_images`: Prompt for image generation

**Prompt Hierarchy:**
1. Account-specific prompt (if exists)
2. Default system prompt (fallback)

### Author Profiles Management

**Author Profile Creation:**
1. User navigates to Thinker → Author Profiles
2. User clicks "Add Profile" action
3. User enters name, description, tone, language
4. System creates AuthorProfile record
5. Profile becomes available for content generation

**Author Profile Usage:**
- Author profiles are used in content generation prompts
- Profile tone and language influence AI-generated content style
- Multiple profiles can be created for different content styles

**Author Profile Management:**
- View all profiles
- Edit profile details
- Delete profile

### Strategies Management

**Strategy Creation:**
1. User navigates to Thinker → Strategies
2. User clicks "Add Strategy" action
3. User enters name, description
4. User selects sector (optional, for sector-specific strategies)
5. User configures prompt types (which prompts this strategy affects)
6. User configures section logic (content structure preferences)
7. System creates Strategy record
8. Strategy becomes active and influences AI generation

**Strategy Usage:**
- Strategies influence content generation when linked to sectors
- Strategy prompt types override default prompts
- Strategy section logic affects content structure

**Strategy Management:**
- View all strategies
- Edit strategy details
- Activate/deactivate strategy
- Delete strategy

### Image Testing

**Image Testing Workflow:**
1. User navigates to Thinker → Image Testing
2. User enters image prompt
3. User selects image provider (OpenAI DALL-E or Runware)
4. User clicks "Generate Test Image" action
5. System calls image generation API
6. System displays generated image
7. User can test different prompts and providers
8. No credits deducted for testing (or minimal test credits)

---

## System Module - Complete Workflows

### Integration Settings

**OpenAI Integration Setup:**
1. User navigates to Settings → Integration
2. User selects "OpenAI" integration type
3. User enters OpenAI API key
4. User clicks "Test Connection" (optional)
5. System makes test API call to OpenAI
6. System returns connection status
7. User saves integration settings
8. System stores API key in IntegrationSettings record
9. OpenAI integration ready for AI functions

**Runware Integration Setup:**
1. User navigates to Settings → Integration
2. User selects "Runware" integration type
3. User enters Runware API key
4. User selects Runware model (e.g., `runware:97@1`)
5. User clicks "Test Connection" (optional)
6. System makes test API call to Runware
7. System returns connection status
8. User saves integration settings
9. System stores API key and model in IntegrationSettings record
10. Runware integration ready for image generation

**Integration Test Functions:**
- Test OpenAI: Makes test API call, returns success/failure
- Test Runware: Makes test API call, returns success/failure
- Generate Test Image: Generates test image using selected provider

### System Settings

**General Settings:**
- Account name and details
- Site management
- Sector management
- Industry selection

**User Management:**
- Add users to account
- Assign roles (owner, admin, editor, viewer)
- Grant site access (for editors/viewers)
- Remove users

**Module Settings:**
- Enable/disable modules
- Configure module-specific settings

**AI Settings:**
- Configure AI model preferences
- Set default models per function
- Configure token limits
- Set cost tracking preferences

### System Status and Monitoring

**Status Endpoint:**
- System health check
- Database connectivity
- Redis connectivity
- Celery worker status
- Service availability

**Request Metrics:**
- API request counts
- Response times
- Error rates
- Resource usage (CPU, memory, I/O)

---

## Billing Module - Complete Workflows

### Credit Management

**Credit Balance:**
- Each account has a credit balance
- Credits are displayed in Billing → Credits page
- Credits are deducted for AI operations
- Credits can be added via transactions

**Credit Transactions:**
1. User navigates to Billing → Transactions
2. User views all credit transactions
3. Transaction types:
   - Purchase: Credits purchased
   - Subscription: Credits from subscription renewal
   - Refund: Credits refunded
   - Deduction: Credits used for AI operations
   - Adjustment: Manual credit adjustments
4. Each transaction shows amount, balance_after, description, timestamp

**Credit Usage Logs:**
1. User navigates to Billing → Usage
2. User views detailed usage logs
3. Each log entry shows:
   - Operation type (clustering, ideas, content, images, reparse)
   - Credits used
   - Cost in USD
   - Model used
   - Input/output tokens
   - Related object (keyword, cluster, task)
   - Timestamp
4. Logs are filterable by operation type, date range

### Credit Costs

**Credit Costs per Operation:**
- Clustering: 1 credit per 30 keywords (base: 1 credit)
- Ideas: 1 credit per idea (base: 1 credit)
- Content: 3 credits per content piece (base: 3 credits)
- Images: 1 credit per image (base: 1 credit)
- Reparse: 1 credit per reparse (base: 1 credit)

**Credit Deduction Process:**
1. User initiates AI operation
2. System checks account credit balance
3. System calculates required credits based on operation type
4. If insufficient credits: Operation fails with error
5. If sufficient credits: Operation proceeds
6. After operation completes: Credits deducted via CreditService
7. CreditTransaction record created (deduction type)
8. CreditUsageLog record created with operation details
9. Account credit balance updated

### Plan Management

**Plan Features:**
- Each account is linked to a plan via subscription
- Plans define limits:
  - Maximum users
  - Maximum sites
  - Maximum keywords
  - Maximum clusters
  - Maximum content ideas
  - Maximum AI requests
  - Maximum word count
  - Maximum images
  - Included credits per month
  - Credits per month (if different from included)

**Plan Limits Enforcement:**
- System checks plan limits before operations
- Operations fail if limits exceeded
- Limits are checked at:
  - Keyword import
  - Cluster creation
  - Idea generation
  - Content generation
  - Image generation

---

## AI Functions - Complete Details

### AI Function Execution Flow

**Unified Entry Point:**
- All AI functions use `run_ai_task` Celery task
- Function name passed as parameter (auto_cluster, generate_ideas, generate_content, generate_image_prompts, generate_images)
- Payload contains function-specific data
- Account ID passed for credit checking and account isolation

**Execution Phases:**
1. **INIT**: Initialize function, validate payload
2. **PREP**: Load data from database, prepare for AI call
3. **AI_CALL**: Make API call to OpenAI or Runware
4. **PARSE**: Parse AI response, extract structured data
5. **SAVE**: Save results to database
6. **DONE**: Task complete, return results

**Progress Tracking:**
- Progress updates sent via Celery task progress
- Frontend polls progress endpoint
- Progress shows current phase and percentage
- Progress shows items processed (e.g., "3 of 10 keywords clustered")

**Error Handling:**
- Validation errors: Returned immediately
- API errors: Logged, error returned to frontend
- Insufficient credits: Operation fails before AI call
- Network errors: Retried with exponential backoff

### Auto Cluster Function

**Function Name:** `auto_cluster`

**Purpose:** Group related keywords into semantic clusters using AI

**Input:**
- Keyword IDs (list, maximum 20)
- Sector ID (optional)

**Process:**
1. Load keywords from database
2. Build prompt with keyword data (keyword, volume, difficulty, intent)
3. Call OpenAI API with clustering prompt
4. Parse response (cluster names, keyword assignments)
5. Create Cluster records
6. Link keywords to clusters
7. Update cluster metrics

**Output:**
- Cluster records created
- Keywords linked to clusters
- Cluster metrics updated (keywords_count, volume)

**Credits:** 1 credit per 30 keywords

### Generate Ideas Function

**Function Name:** `generate_ideas`

**Purpose:** Generate SEO-optimized content ideas from keyword clusters

**Input:**
- Cluster IDs (list, maximum 1 per batch)

**Process:**
1. Load cluster and associated keywords
2. Build prompt with cluster data (name, keywords, sector context)
3. Call OpenAI API with idea generation prompt
4. Parse response (idea titles, descriptions, content types, structures)
5. Create ContentIdeas records
6. Link ideas to cluster

**Output:**
- ContentIdeas records created
- Ideas linked to clusters

**Credits:** 1 credit per idea

### Generate Content Function

**Function Name:** `generate_content`

**Purpose:** Generate article content from task ideas

**Input:**
- Task IDs (list, maximum 50 per batch)

**Process:**
1. Load tasks with relationships (cluster, keywords, idea, sector, site)
2. For each task:
   - Build prompt with task data (title, description, keywords, content type, structure)
   - Call OpenAI API with content generation prompt
   - Parse HTML content response
   - Create or update Content record
   - Calculate word count
   - Update task status
3. Process tasks sequentially or in parallel (configurable)

**Output:**
- Content records created/updated with HTML
- Task status updated to "review"
- Word count calculated

**Credits:** 3 credits per content piece

### Generate Image Prompts Function

**Function Name:** `generate_image_prompts`

**Purpose:** Extract image prompts from content HTML

**Input:**
- Content IDs (list)

**Process:**
1. Load content HTML
2. Build prompt for image prompt extraction
3. Call OpenAI API
4. Parse response (featured image prompt, 1-6 in-article image prompts)
5. Create or update Images records with prompts
6. Set image_type (featured, in_article)

**Output:**
- Images records created/updated with prompts
- Image types set

**Credits:** Included in content generation (no separate charge)

### Generate Images Function

**Function Name:** `generate_images`

**Purpose:** Generate images using OpenAI DALL-E or Runware

**Input:**
- Image IDs (list)

**Process:**
1. Load images with prompts
2. Determine image provider from integration settings
3. For each image:
   - Build image generation request
   - Call OpenAI DALL-E API or Runware API
   - Receive image URL
   - Update Images record with image_url
   - Set status to "completed"
4. Process images sequentially

**Output:**
- Images records updated with image URLs
- Image status updated

**Credits:** 1 credit per image

---

## Credit System - How It Works

### Credit Balance Management

**Account Credits:**
- Each account has a `credits` field (integer)
- Credits start at 0 or plan-included credits
- Credits are deducted for AI operations
- Credits can be added via transactions

**Credit Checking:**
- Before AI operation: System checks if account has sufficient credits
- If insufficient: Operation fails with `InsufficientCreditsError`
- If sufficient: Operation proceeds

**Credit Deduction:**
- After AI operation completes: Credits deducted via `CreditService.deduct_credits()`
- Account credits field updated
- CreditTransaction record created (type: deduction, amount: negative)
- CreditUsageLog record created with operation details

**Credit Addition:**
- Via transactions: `CreditService.add_credits()` called
- Account credits field updated
- CreditTransaction record created (type: purchase/subscription/refund/adjustment, amount: positive)

### Credit Transaction Types

**Purchase:**
- User purchases credits
- Amount: Positive integer
- Description: "Credit purchase"
- Balance after: Account credits + purchase amount

**Subscription:**
- Credits from subscription renewal
- Amount: Plan's included_credits or credits_per_month
- Description: "Subscription renewal credits"
- Balance after: Account credits + subscription credits

**Refund:**
- Credits refunded to account
- Amount: Positive integer
- Description: "Credit refund"
- Balance after: Account credits + refund amount

**Deduction:**
- Credits used for AI operations
- Amount: Negative integer
- Description: Operation-specific (e.g., "Content generation")
- Balance after: Account credits - deduction amount

**Adjustment:**
- Manual credit adjustments by admin
- Amount: Positive or negative integer
- Description: Admin-provided reason
- Balance after: Account credits + adjustment amount

### Credit Usage Logging

**Operation Types:**
- `clustering`: Keyword clustering operations
- `ideas`: Content idea generation
- `content`: Content generation
- `images`: Image generation
- `reparse`: Content reparse operations

**Log Details:**
- Operation type
- Credits used
- Cost in USD (calculated from API costs)
- Model used (e.g., "gpt-4", "dall-e-3")
- Input tokens (if available)
- Output tokens (if available)
- Related object type (keyword, cluster, task, content, image)
- Related object ID
- Metadata (additional context)

---

## WordPress Integration

### WordPress Configuration

**Site-Level Configuration:**
- Each site can have WordPress integration configured
- Fields: `wp_url`, `wp_username`, `wp_app_password`
- Configuration stored in Site model

**WordPress App Password:**
- WordPress requires app password (not regular password)
- App password generated in WordPress user settings
- App password used for REST API authentication

### Publishing Process

**Publishing Workflow:**
1. User selects content to publish
2. System validates WordPress configuration
3. System authenticates with WordPress REST API
4. System creates WordPress post:
   - Title: Content meta_title or task title
   - Content: Content HTML
   - Status: Draft or Publish (based on content status)
   - Featured image: Uploaded if available
   - In-article images: Uploaded if available
   - Meta fields: Primary keyword, secondary keywords
5. WordPress returns post ID
6. System updates Content record:
   - Sets `wp_post_id` field
   - Sets `status` to "published"
7. User can view published content in WordPress

**Image Upload:**
- Featured image: Images record with `image_type="featured"`
- In-article images: Images records with `image_type="in_article"`
- Images uploaded to WordPress media library
- Image URLs updated in WordPress post

**Publishing Requirements:**
- Site must have `wp_url` configured
- Site must have `wp_username` and `wp_app_password`
- Content must have status "review" or "draft"
- WordPress REST API must be accessible

---

## Data Flow and State Management

### Frontend State Management

**Zustand Stores:**
- **Auth Store**: User authentication, JWT token, account info
- **Site Store**: Current site selection, accessible sites
- **Sector Store**: Current sector selection, accessible sectors
- **Planner Store**: Planner module state (keywords, clusters, ideas)
- **Writer Store**: Writer module state (tasks, content, images)
- **Billing Store**: Credit balance, transactions, usage logs
- **Settings Store**: User settings, preferences
- **Page Size Store**: Table page size preferences
- **Column Visibility Store**: Table column visibility preferences

**React Contexts:**
- **Theme Context**: Dark/light theme
- **Sidebar Context**: Sidebar open/closed state
- **Header Metrics Context**: Header KPI metrics
- **Toast Context**: Toast notifications

### API Communication

**API Client:**
- Frontend uses Fetch API for HTTP requests
- Base URL: `/api/v1/`
- JWT token included in Authorization header
- Request/response format: JSON

**Request Flow:**
1. User action in frontend
2. Frontend makes API request
3. Backend middleware extracts account from JWT
4. Backend ViewSet processes request
5. Backend returns JSON response
6. Frontend updates state
7. Frontend updates UI

**Response Format:**
- Success: `{success: true, data: {...}, message: "..."}`
- Error: `{success: false, error: "...", errors: {...}}`
- Pagination: `{count: N, next: "...", previous: "...", results: [...]}`

### Celery Task Flow

**Task Queueing:**
1. User action triggers API request
2. Backend ViewSet action queues Celery task
3. Task ID returned to frontend
4. Frontend stores task ID

**Progress Polling:**
1. Frontend polls progress endpoint every 2-3 seconds
2. Backend returns progress (phase, percentage, items processed)
3. Frontend updates progress UI
4. Polling continues until task completes

**Task Completion:**
1. Celery worker completes task
2. Results saved to database
3. Progress endpoint returns completion status
4. Frontend stops polling
5. Frontend refreshes data
6. Frontend displays results

---

## Complete Feature List

### Planner Module Features

**Keywords:**
- CSV import
- Manual keyword entry
- Keyword filtering (sector, status, intent, cluster, difficulty, volume)
- Keyword search
- Keyword sorting
- Bulk delete
- Bulk status update
- Bulk add from seed keywords
- CSV export
- Auto cluster (AI-powered clustering)
- Keyword-to-cluster linking
- Keyword metrics display (volume, difficulty, intent)

**Clusters:**
- Cluster listing
- Cluster creation (manual)
- Cluster editing (name, description)
- Cluster deletion
- Keyword-to-cluster management (add/remove)
- Cluster metrics (keywords_count, volume)
- Auto generate ideas (AI-powered idea generation)
- Cluster filtering (sector, status)
- Cluster search

**Content Ideas:**
- Idea listing
- Idea creation (manual)
- Idea editing (title, description)
- Idea deletion
- Idea status management
- Bulk queue to writer (create tasks from ideas)
- Idea filtering (sector, cluster, status, content type)
- Idea search

**Keyword Opportunities:**
- Opportunity analysis
- Keyword gap analysis
- Competitive analysis

### Writer Module Features

**Tasks:**
- Task listing
- Task creation (manual or from ideas)
- Task editing (title, description, content type, structure)
- Task deletion
- Task status management
- Auto generate content (AI-powered content generation)
- Task filtering (sector, cluster, status, content type, structure)
- Task search
- Bulk delete
- Bulk status update

**Content:**
- Content listing
- Content viewing (full HTML)
- Content editing (HTML editor)
- Content status management
- Meta title and description editing
- Primary and secondary keywords editing
- Word count display
- Publish to WordPress
- Content filtering (sector, status, content type)
- Content search
- Drafts view
- Published view

**Images:**
- Image listing
- Image viewing
- Image creation (manual)
- Image editing (prompt, type)
- Image deletion
- Generate image prompts (AI-powered prompt extraction)
- Generate images (AI-powered image generation)
- Image filtering (content, type, status, task)
- Image bulk status update
- Image regeneration

### Thinker Module Features

**Prompts:**
- Prompt listing
- Prompt viewing
- Prompt editing
- Prompt reset to default
- Prompt type filtering

**Author Profiles:**
- Profile listing
- Profile creation
- Profile editing
- Profile deletion
- Profile usage in content generation

**Strategies:**
- Strategy listing
- Strategy creation
- Strategy editing
- Strategy activation/deactivation
- Strategy deletion
- Sector-specific strategies
- Strategy prompt type configuration
- Strategy section logic configuration

**Image Testing:**
- Test image generation
- Prompt testing
- Provider testing (OpenAI DALL-E, Runware)
- Image preview

### System Module Features

**Integration Settings:**
- OpenAI integration setup
- Runware integration setup
- API key management
- Connection testing
- Test image generation
- Model selection (Runware)

**Settings:**
- General settings
- Account settings
- User settings
- Module settings
- AI settings

**User Management:**
- User listing
- User creation
- User editing
- User deletion
- Role assignment
- Site access management

**Site Management:**
- Site listing
- Site creation
- Site editing
- Site deletion
- WordPress integration configuration
- Industry assignment

**Sector Management:**
- Sector listing
- Sector creation
- Sector editing
- Sector deletion
- Sector activation/deactivation
- Maximum 5 active sectors per site

### Billing Module Features

**Credits:**
- Credit balance display
- Credit transaction history
- Credit usage logs
- Credit cost display per operation

**Transactions:**
- Transaction listing
- Transaction filtering (type, date range)
- Transaction details
- Balance tracking

**Usage:**
- Usage log listing
- Usage log filtering (operation type, date range)
- Cost tracking
- Token tracking
- Model usage tracking

**Plans:**
- Plan listing
- Plan details
- Plan limits display
- Subscription management

### Authentication Features

**Sign Up:**
- Account creation
- User creation (owner role)
- Subscription creation (default plan)
- Email validation
- Password validation

**Sign In:**
- Email/password authentication
- JWT token generation
- Token storage (localStorage)
- Account context loading

**Password Management:**
- Password change
- Password reset (planned)

**Session Management:**
- Token expiration handling
- Token refresh (planned)
- Logout

### Dashboard Features

**Home Dashboard:**
- Account overview
- KPI metrics
- Recent activity
- Quick actions

**Module Dashboards:**
- Planner Dashboard: Keyword metrics, cluster metrics, idea metrics
- Writer Dashboard: Task metrics, content metrics, image metrics
- Thinker Dashboard: Prompt metrics, strategy metrics
- Billing Dashboard: Credit balance, usage metrics

---

## Summary

IGNY8 operates as a complete SaaS platform for SEO keyword management and AI-driven content generation. The system follows a clear business flow:

1. **Setup**: Users create accounts, set up sites and sectors
2. **Planning**: Users import keywords, cluster them with AI, generate content ideas
3. **Creation**: Users create tasks from ideas, generate AI content, generate images
4. **Publishing**: Users publish content to WordPress sites
5. **Management**: Users manage credits, transactions, settings, and integrations

All operations are account-isolated, credit-based, and AI-powered. The system provides complete workflows from keyword import to WordPress publishing, with comprehensive filtering, search, and bulk operations throughout.