salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9ec1aa894869f562ce850ecac8158006aecf8d0b
igny8/master-docs/06-FUNCTIONAL-BUSINESS-LOGIC.md

42 KiB
Raw Blame History

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
  2. System Overview
  3. Complete User Workflow
  4. Account and User Management
  5. Planner Module - Complete Workflows
  6. Writer Module - Complete Workflows
  7. Thinker Module - Complete Workflows
  8. System Module - Complete Workflows
  9. Billing Module - Complete Workflows
  10. AI Functions - Complete Details
  11. Credit System - How It Works
  12. WordPress Integration
  13. Data Flow and State Management
  14. 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.

Reference in New Issue View Git Blame Copy Permalink