Skip to content

HG Content Generation System - System Architecture Documentation

Last Updated: 2025-12-30

Table of Contents

  1. High-Level Architecture Overview
  2. Module Descriptions and Responsibilities
  3. Data Flow Between Modules
  4. Technology Stack Details
  5. Database Architecture
  6. Deployment Architecture
  7. Security and Authentication
  8. Development Workflow
  9. Monitoring and Observability

High-Level Architecture Overview

The HG Content Generation System is a modern, modular content generation platform designed for multi-tenant use cases, supporting clients like PASCO Scientific and niche marketing agencies. The system follows microservices architecture patterns with clear separation of concerns and independent scalability.

System Architecture Diagram

graph TB
    subgraph "Coolify Platform (apps-vps)"
        subgraph "Frontend Layer"
            FE[Next.js Frontend<br/>hgcontent.com]
        end

        subgraph "API Gateway Layer"
            API[Next.js API Routes<br/>Server Components]
        end

        subgraph "Core Services Layer"
            CPM[Content Production Module<br/>Python FastAPI<br/>cpm.hgcontent.com]
            IM[Instructions Module<br/>Python FastAPI<br/>im.hgcontent.com]
            SMM[Strategy Management Module<br/>Python FastAPI<br/>smm.hgcontent.com]
        end

        REDIS[(Redis<br/>Caching & Queue)]
    end

    subgraph "Database Server (db-vps)"
        DB[(PostgreSQL 16<br/>PgBouncer)]
    end

    subgraph "External AI Services"
        OPENAI[OpenAI API]
        ANTHROPIC[Anthropic API]
        GOOGLE[Google Gemini API]
        GROQ[Groq API]
    end

    FE --> API
    API --> CPM
    API --> SMM
    CPM --> IM
    CPM --> OPENAI
    CPM --> ANTHROPIC
    CPM --> GOOGLE
    CPM --> GROQ
    CPM --> DB
    IM --> DB
    SMM --> DB
    CPM --> REDIS
    IM --> REDIS

Container Architecture Diagram

C4Container
    title Container Diagram - HG Content System

    Person(user, "Content Managers", "Agency staff, PASCO admins")

    Container_Boundary(frontend, "Frontend") {
        Container(webapp, "Next.js Web App", "React, TypeScript", "User interface for content management")
        Container(api, "API Routes", "Next.js API", "Frontend API gateway")
    }

    Container_Boundary(services, "Backend Services") {
        Container(cpm, "Content Production Module", "Python, FastAPI", "Handles content generation via LLMs")
        Container(im, "Instructions Module", "Python, FastAPI", "Manages prompts and directives")
        Container(smm, "Strategy Management", "Python, FastAPI", "Client strategies and configurations")
    }

    Container_Boundary(data, "Data Layer") {
        ContainerDb(db, "Database Database", "PostgreSQL", "Jobs, clients, strategies, content")
        ContainerDb(cache, "Redis Cache", "Redis", "Job queues and caching")
    }

    Container_Boundary(external, "External Services") {
        Container(llms, "LLM Providers", "OpenAI, Anthropic, etc.", "AI content generation")
    }

    Rel(user, webapp, "Uses", "HTTPS")
    Rel(webapp, api, "Makes API calls", "HTTPS")
    Rel(api, cpm, "Content requests", "HTTPS/REST")
    Rel(api, smm, "Strategy queries", "HTTPS/REST")
    Rel(cpm, im, "Prompt requests", "HTTPS/REST")
    Rel(cpm, llms, "Generation requests", "HTTPS/REST")
    Rel(cpm, db, "Job tracking", "SQL/TCP")
    Rel(smm, db, "Strategy data", "SQL/TCP")
    Rel(cpm, cache, "Queue jobs", "Redis Protocol")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="2")

Module Descriptions and Responsibilities

Frontend UI Module (/apps/frontend/)

Technology: Next.js 14 with TypeScript, React 18, Tailwind CSS Deployment: Coolify on apps-vps (hgcontent.com) Primary Responsibilities:

  • User Interface: Provides responsive web interface for content management
  • Authentication: Handles user login/logout via Database Auth
  • Client Management: Multi-tenant client selection and switching
  • Content Requests: Forms for submitting content generation requests
  • Job Monitoring: Real-time job status tracking and results display
  • Analytics Dashboard: Usage metrics, cost tracking, and performance insights
  • Settings Management: API key configuration, notification preferences

Key Components: - ContentRequestForm: Main content generation interface - JobStatusTable: Real-time job monitoring with WebSocket updates - AnalyticsDashboard: Cost and usage visualization - ClientSelector: Multi-tenant client switching - StrategyEditor: Client-specific strategy configuration

Content Production Module (CPM) (/apps/cpm/)

Technology: Python 3.12+, FastAPI, AsyncIO Deployment: Coolify on apps-vps (cpm.hgcontent.com) Primary Responsibilities:

  • Content Generation: Orchestrates LLM-based content creation
  • Multi-LLM Support: Integrates with OpenAI, Anthropic, Google Gemini, Groq
  • Job Queue Management: Async job processing with Redis-backed queues
  • Cost Tracking: Token usage monitoring and cost estimation
  • Error Handling: Retry logic, fallback providers, graceful degradation
  • Performance Optimization: Request batching, response caching

Key Features: - Async Processing: Background tasks using FastAPI BackgroundTasks - Provider Abstraction: Unified interface for multiple LLM providers - Token Optimization: Smart prompt engineering to minimize costs - Quality Control: Content validation and formatting

API Endpoints: - POST /generate - Queue content generation job - GET /jobs/{job_id} - Get job status and results - GET /jobs - List jobs with filtering - GET /health - Service health check

Instructions Module (IM) (/apps/im/)

Technology: Python 3.12+, FastAPI Deployment: Coolify on apps-vps (im.hgcontent.com) Primary Responsibilities:

  • Prompt Engineering: Dynamic prompt generation based on client strategies
  • Template Management: Client-specific prompt templates
  • Context Injection: Dynamic parameter substitution in prompts
  • Quality Assurance: Prompt validation and optimization
  • A/B Testing: Prompt variant testing and performance tracking

Key Features: - Dynamic Prompts: Context-aware prompt generation - Client Customization: Per-client prompt strategies - Template Versioning: Version control for prompt templates - Performance Analytics: Prompt effectiveness tracking

Integration Pattern: 

# CPM calls IM for customized prompts
im_response = await httpx.post(
    f"{IM_BASE_URL}/generate-prompt",
    json={
        "topic": request.topic,
        "client_id": request.client_id,
        "content_type": request.content_type,
        "keywords": request.keywords
    }
)

Strategy Management Module (SMM) (/smm/)

Technology: Python 3.12+, FastAPI Deployment: Coolify on apps-vps (smm.hgcontent.com) Primary Responsibilities:

  • Client Hierarchy Management: Multi-tier client relationships (Root → Agency → Customer)
  • Strategy Configuration: SEO rules, content preferences, brand guidelines
  • Template Management: Client-specific content templates
  • Access Control: Role-based permissions and data isolation
  • Analytics Integration: Strategy performance tracking

Key Features: - Hierarchical Clients: Support for agency-customer relationships - Row-Level Security: Database RLS for data isolation - Dynamic Configuration: Runtime strategy updates - Audit Logging: Complete change tracking

Client Hierarchy Model: 

Root Client (HG Content)
├── PASCO Scientific (Direct Client)
├── Heaviside Digital (Agency)
│   ├── Cincinnati Electrician Co. (Customer)
│   └── Local Business Group (Customer)
├── Paving Marketers (Agency)
│   ├── Ohio Paving Co. (Customer)
│   └── Regional Contractors (Customer)

Data Flow Between Modules

Content Generation Flow

sequenceDiagram
    participant User as User Interface
    participant API as Next.js API
    participant CPM as Content Production
    participant IM as Instructions Module
    participant SMM as Strategy Management
    participant LLM as LLM Provider
    participant DB as Database DB

    User->>API: Submit content request
    API->>SMM: Get client strategy
    SMM->>DB: Query strategy config
    DB->>SMM: Return strategy
    SMM->>API: Strategy data
    API->>CPM: Generate content request
    CPM->>DB: Create job record
    CPM->>IM: Request customized prompt
    IM->>DB: Get prompt template
    IM->>CPM: Return prompt
    CPM->>LLM: Generate content
    LLM->>CPM: Content response
    CPM->>DB: Update job with results
    CPM->>API: Job completion notification
    API->>User: Content ready notification

Real-time Job Status Updates

sequenceDiagram
    participant UI as Frontend UI
    participant WS as WebSocket/SSE
    participant API as API Routes
    participant CPM as CPM Service
    participant DB as Database

    UI->>API: Subscribe to job updates
    API->>WS: Establish connection
    CPM->>DB: Update job status
    DB->>WS: Real-time notification
    WS->>UI: Status update
    UI->>UI: Update job display

Technology Stack Details

Frontend Stack

  • Framework: Next.js 14 with App Router
  • Language: TypeScript 5.4+
  • Styling: Tailwind CSS 3.4+
  • UI Components: Radix UI primitives
  • State Management: Zustand + React Query
  • Forms: React Hook Form + Zod validation
  • Charts: Recharts for analytics
  • Authentication: Database Auth with NextAuth.js integration

Backend Stack

  • Language: Python 3.12+
  • Web Framework: FastAPI 0.111+
  • Async Runtime: AsyncIO with Uvicorn
  • Database ORM: Database Python client
  • HTTP Client: httpx for service communication
  • Task Queue: Redis with async workers
  • Logging: Structured logging with structlog
  • Monitoring: Prometheus metrics
  • Testing: pytest with async support

AI/ML Integration

  • OpenAI: GPT-4, GPT-4-Turbo, GPT-3.5-Turbo
  • Anthropic: Claude 3.5 Sonnet, Claude 3 Haiku
  • Google: Gemini 1.5 Pro, Gemini 1.5 Flash
  • Groq: Llama 3.1 70B (high-speed inference)
  • Cost Optimization: Dynamic provider routing based on cost/quality

Development Tools

  • Monorepo: Turborepo for build orchestration
  • Package Manager: pnpm with workspaces
  • Code Quality: ESLint, Prettier, Black (Python)
  • Testing: Jest (Frontend), pytest (Backend)
  • CI/CD: GitHub Actions with path-based triggering
  • Documentation: TypeDoc, Sphinx

Database Architecture (Database)

Core Tables Schema

-- Jobs table for content generation tracking
CREATE TABLE jobs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    client_id VARCHAR(255) NOT NULL,
    content_type VARCHAR(100) NOT NULL,
    prompt TEXT NOT NULL,
    llm_provider VARCHAR(50) NOT NULL DEFAULT 'openai',
    status job_status NOT NULL DEFAULT 'pending',
    parameters JSONB DEFAULT '{}',
    result JSONB DEFAULT NULL,
    error_message TEXT DEFAULT NULL,

    -- Cost tracking
    input_tokens INTEGER DEFAULT NULL,
    output_tokens INTEGER DEFAULT NULL,
    total_tokens INTEGER DEFAULT NULL,
    estimated_cost DECIMAL(10,6) DEFAULT NULL,
    provider_model VARCHAR(100) DEFAULT NULL,

    -- Timestamps
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    started_at TIMESTAMP WITH TIME ZONE DEFAULT NULL,
    completed_at TIMESTAMP WITH TIME ZONE DEFAULT NULL
);

-- Clients hierarchy table
CREATE TABLE clients (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    slug VARCHAR(255) UNIQUE NOT NULL,
    type client_type NOT NULL,
    parent_id UUID REFERENCES clients(id),
    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Strategies configuration table
CREATE TABLE strategies (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    client_id UUID NOT NULL REFERENCES clients(id),
    name VARCHAR(255) NOT NULL,
    content_type content_type NOT NULL,
    configuration JSONB NOT NULL,
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Prompt templates table
CREATE TABLE prompt_templates (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    client_id UUID NOT NULL REFERENCES clients(id),
    name VARCHAR(255) NOT NULL,
    content_type content_type NOT NULL,
    template TEXT NOT NULL,
    variables JSONB DEFAULT '{}',
    version INTEGER DEFAULT 1,
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

Database Performance Features

  • Indexing Strategy: Composite indexes on frequently queried columns
  • Partitioning: Jobs table partitioned by created_at for performance
  • Connection Pooling: Database connection pooler for high concurrency
  • Real-time: Database real-time subscriptions for job status updates
  • Row-Level Security: Multi-tenant data isolation

Data Relationships Diagram

erDiagram
    CLIENTS {
        uuid id PK
        string name
        string slug UK
        enum type
        uuid parent_id FK
        jsonb metadata
        timestamp created_at
        timestamp updated_at
    }

    JOBS {
        uuid id PK
        string client_id FK
        string content_type
        text prompt
        string llm_provider
        enum status
        jsonb parameters
        jsonb result
        string error_message
        integer input_tokens
        integer output_tokens
        integer total_tokens
        decimal estimated_cost
        string provider_model
        timestamp created_at
        timestamp updated_at
        timestamp started_at
        timestamp completed_at
    }

    STRATEGIES {
        uuid id PK
        uuid client_id FK
        string name
        enum content_type
        jsonb configuration
        boolean is_active
        timestamp created_at
        timestamp updated_at
    }

    PROMPT_TEMPLATES {
        uuid id PK
        uuid client_id FK
        string name
        enum content_type
        text template
        jsonb variables
        integer version
        boolean is_active
        timestamp created_at
    }

    CLIENTS ||--o{ CLIENTS : "parent-child"
    CLIENTS ||--o{ JOBS : "owns"
    CLIENTS ||--o{ STRATEGIES : "configures"
    CLIENTS ||--o{ PROMPT_TEMPLATES : "defines"

Deployment Architecture (Coolify)

Production Deployment Overview

Infrastructure: All services deployed on Coolify running on apps-vps, with PostgreSQL on db-vps.

graph TB
    subgraph "CDN Layer"
        CF[Cloudflare DNS<br/>Proxy + SSL]
    end

    subgraph "apps-vps (Coolify)"
        FE[hg-content-frontend<br/>Next.js :3000]
        CPM_R[hg-content-cpm<br/>FastAPI :8000]
        IM_R[hg-content-im<br/>FastAPI :8001]
        SMM_R[hg-content-smm<br/>FastAPI :8003]
        REDIS_R[hg-content-redis<br/>Redis :6379]
    end

    subgraph "db-vps"
        PGBOUNCER[PgBouncer :6543]
        DB[PostgreSQL :5432<br/>hg_content database]
    end

    subgraph "External Services"
        OPENAI_EXT[OpenAI API]
        ANTHROPIC_EXT[Anthropic API]
        GOOGLE_EXT[Google AI API]
        GROQ_EXT[Groq API]
    end

    CF --> FE
    FE --> CPM_R
    FE --> SMM_R
    CPM_R --> IM_R
    CPM_R --> REDIS_R
    CPM_R --> PGBOUNCER
    SMM_R --> PGBOUNCER
    IM_R --> PGBOUNCER
    PGBOUNCER --> DB
    CPM_R --> OPENAI_EXT
    CPM_R --> ANTHROPIC_EXT
    CPM_R --> GOOGLE_EXT
    CPM_R --> GROQ_EXT

Service URLs

Service Container Name Internal Port Public URL
Frontend hg-content-frontend 3000 hgcontent.com
CPM hg-content-cpm 8000 cpm.hgcontent.com
IM hg-content-im 8001 im.hgcontent.com
SMM hg-content-smm 8003 smm.hgcontent.com
Redis hg-content-redis 6379 Internal only

Environment Configuration

Frontend Environment Variables (Coolify)

# Database
DATABASE_URL=postgresql://hg_content_app:PASSWORD@db-vps:6543/hg_content

# Backend Service URLs (internal)
CPM_SERVICE_URL=http://hg-content-cpm:8000
IM_SERVICE_URL=http://hg-content-im:8001
SMM_SERVICE_URL=http://hg-content-smm:8003

# Backend Service URLs (public)
NEXT_PUBLIC_CPM_API_URL=https://cpm.hgcontent.com
NEXT_PUBLIC_SMM_API_URL=https://smm.hgcontent.com

# Authentication
NEXTAUTH_URL=https://hgcontent.com
NEXTAUTH_SECRET=secure-random-string
AUTH_SECRET=secure-random-string

# Node
NODE_ENV=production
PORT=3000

Backend Service Environment Variables (Coolify)

# Database Configuration
DATABASE_URL=postgresql://hg_content_app:PASSWORD@db-vps:6543/hg_content

# Redis Configuration
REDIS_URL=redis://hg-content-redis:6379

# LLM API Keys
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
GOOGLE_API_KEY=your-google-ai-key
GROQ_API_KEY=gsk_your-groq-key

# Service URLs (for inter-service communication)
IM_SERVICE_URL=http://hg-content-im:8001
SMM_SERVICE_URL=http://hg-content-smm:8003

# Application
ENVIRONMENT=production
LOG_LEVEL=info
PORT=8000  # or 8001, 8003 for IM/SMM

Coolify Deployment

All services are containerized using Dockerfiles:

Service Dockerfile
Frontend apps/frontend/Dockerfile
CPM apps/cpm/Dockerfile
IM apps/im/Dockerfile
SMM smm/Dockerfile

Health Checks: Each service exposes a /health endpoint for container health monitoring.

Inter-Service Communication: Services communicate via Docker internal DNS using container names (e.g., http://hg-content-cpm:8000).

Security and Authentication

Authentication Flow

sequenceDiagram
    participant User as User
    participant Frontend as Next.js Frontend
    participant NextAuth as NextAuth
    participant Backend as Backend Services
    participant DB as PostgreSQL

    User->>Frontend: Login request
    Frontend->>NextAuth: Authenticate with Credentials
    NextAuth->>DB: Verify password hash
    DB->>NextAuth: User record
    NextAuth->>Frontend: JWT session token
    Frontend->>Backend: API request + x-user-id header
    Backend->>DB: Query with user context
    DB->>Backend: Filtered results
    Backend->>Frontend: API response

Security Features

Authentication & Authorization

  • NextAuth JWT: Stateless JWT tokens with secure cookie storage
  • Row-Level Security: Database-level access control via RLS policies
  • Role-Based Access: Hierarchical permissions (owner, admin, member, viewer)
  • Multi-tenant Isolation: Client-based data separation

API Security

  • CORS Configuration: Restrictive CORS policies for production domains
  • Rate Limiting: Request throttling per user/IP
  • Input Validation: Pydantic models for request validation
  • SQL Injection Protection: Parameterized queries via asyncpg

Infrastructure Security

  • HTTPS Everywhere: TLS 1.3 for all communications
  • Environment Variables: Secure secret management
  • Network Isolation: Private networking between services
  • Audit Logging: Comprehensive access and change logging

Data Privacy & Compliance

  • Data Encryption: At-rest and in-transit encryption
  • GDPR Compliance: Data retention and deletion policies
  • Audit Trails: Complete activity logging
  • Backup Security: Encrypted database backups

Development Workflow

Monorepo Structure

hg-content/
├── apps/
│   ├── frontend/          # Next.js web application
│   ├── cpm/              # Content Production Module (Python)
│   └── im/               # Instructions Module (Python)
├── smm/                  # Strategy Management Module (Python)
├── packages/             # Shared utilities (future)
├── pg/            # Database migrations and config
├── docs/                # Documentation
├── scripts/             # Development and deployment scripts
└── .github/             # CI/CD workflows

Development Commands

# Install dependencies
pnpm install

# Start all services in development mode
pnpm dev

# Run tests
pnpm test

# Build all applications
pnpm build

# Lint and format code
pnpm lint
pnpm format

# Database operations
pg start          # Start local Database
pg db reset       # Reset local database
pg db push        # Push migrations to remote

Git Workflow

  1. Feature Branches: Create feature branches from main
  2. Pull Requests: Require code review and CI checks
  3. Automated Testing: GitHub Actions run tests on all PRs
  4. Deployment: Automatic deployment on merge to main

CI/CD Pipeline

name: CI/CD Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test-frontend:
    if: contains(github.event.head_commit.modified, 'apps/frontend/')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: pnpm install
      - run: pnpm test --filter=frontend

  test-backend:
    if: contains(github.event.head_commit.modified, 'apps/cpm/') || contains(github.event.head_commit.modified, 'smm/')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
      - run: pip install -r requirements.txt
      - run: pytest

  deploy:
    if: github.ref == 'refs/heads/main'
    needs: [test-frontend, test-backend]
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Coolify
        # Coolify auto-deploys on git push to main

Monitoring and Observability

Logging Strategy

  • Structured Logging: JSON format with consistent fields
  • Log Levels: DEBUG, INFO, WARN, ERROR, FATAL
  • Correlation IDs: Track requests across services
  • Centralized Collection: Aggregated in Coolify dashboard and Docker logs

Metrics and Monitoring

  • Application Metrics: Request rate, response time, error rate
  • Business Metrics: Content generation success rate, cost per request
  • Infrastructure Metrics: CPU, memory, database performance
  • Custom Dashboards: Grafana for advanced visualization

Error Tracking

  • Exception Monitoring: Automatic error capture and alerting
  • Performance Monitoring: Slow query detection
  • User Experience Tracking: Frontend performance metrics
  • Alerting: Slack/email notifications for critical issues

Health Checks

@app.get("/health")
async def health_check():
    """Comprehensive health check endpoint"""
    health_status = {
        "status": "healthy",
        "timestamp": datetime.utcnow().isoformat(),
        "services": {
            "database": await check_database_connection(),
            "redis": await check_redis_connection(),
            "external_apis": await check_external_apis()
        },
        "version": "1.0.0"
    }
    return health_status

Performance Optimization

  • Caching Strategy: Redis for frequently accessed data
  • Database Optimization: Query optimization and indexing
  • CDN Utilization: Static asset caching
  • Background Processing: Async job processing for heavy operations

Version: 2.0.0 Platform: Coolify on apps-vps Database: PostgreSQL on db-vps