HG Content Generation System - System Architecture Documentation¶

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 "Frontend Layer"
        FE[Next.js Frontend<br/>Vercel]
    end

    subgraph "API Gateway Layer"
        API[Next.js API Routes<br/>Vercel Edge Functions]
    end

    subgraph "Core Services Layer"
        CPM[Content Production Module<br/>Python FastAPI<br/>Railway]
        IM[Instructions Module<br/>Python FastAPI<br/>Railway]
        SMM[Strategy Management Module<br/>Python FastAPI<br/>Railway]
    end

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

    subgraph "Data Layer"
        SUPABASE[(Supabase PostgreSQL<br/>Auth, Real-time, Storage)]
        REDIS[(Redis<br/>Caching & Queue)]
    end

    subgraph "Monitoring Layer"
        LOGS[Structured Logging<br/>Railway/Vercel]
        METRICS[Prometheus Metrics]
    end

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

    CPM --> LOGS
    IM --> LOGS
    SMM --> LOGS
    CPM --> METRICS

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, "Supabase 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: Vercel Primary Responsibilities:

• User Interface: Provides responsive web interface for content management
• Authentication: Handles user login/logout via Supabase 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: Railway 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) (/app/)¶

Technology: Python 3.12+, FastAPI Deployment: Railway 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, SQLAlchemy Deployment: Railway 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: Supabase 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 Supabase 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 Supabase

    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: Supabase Auth with NextAuth.js integration

Backend Stack¶

• Language: Python 3.12+
• Web Framework: FastAPI 0.111+
• Async Runtime: AsyncIO with Uvicorn
• Database ORM: Supabase 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 (Supabase)¶

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: Supabase connection pooler for high concurrency
• Real-time: Supabase 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 (Vercel + Railway)¶

Production Deployment Overview¶

graph TB
    subgraph "CDN Layer"
        CF[Cloudflare CDN<br/>Global Edge Caching]
    end

    subgraph "Vercel Platform"
        VE[Vercel Edge Network<br/>Global Distribution]
        FE[Next.js Frontend<br/>Static + SSR]
        API[API Routes<br/>Serverless Functions]
    end

    subgraph "Railway Platform"
        CPM_R[CPM Service<br/>Auto-scaling Container]
        IM_R[IM Service<br/>Auto-scaling Container]
        SMM_R[SMM Service<br/>Auto-scaling Container]
        REDIS_R[Redis Instance<br/>Managed Cache]
    end

    subgraph "Supabase Platform"
        DB[PostgreSQL Database<br/>Managed + Backups]
        AUTH[Authentication Service<br/>JWT + RLS]
        RT[Real-time Engine<br/>WebSocket API]
        STORAGE[File Storage<br/>S3-compatible]
    end

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

    CF --> VE
    VE --> FE
    VE --> API
    API --> CPM_R
    API --> SMM_R
    CPM_R --> IM_R
    CPM_R --> REDIS_R
    CPM_R --> DB
    SMM_R --> DB
    CPM_R --> OPENAI_EXT
    CPM_R --> ANTHROPIC_EXT
    CPM_R --> GOOGLE_EXT
    CPM_R --> GROQ_EXT
    FE --> AUTH
    FE --> RT

Environment Configuration¶

Vercel Environment Variables (Frontend)¶

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Backend Service URLs
NEXT_PUBLIC_CPM_API_URL=https://cpm-service.railway.app
NEXT_PUBLIC_SMM_API_URL=https://smm-service.railway.app

# Analytics & Monitoring
NEXT_PUBLIC_POSTHOG_KEY=your-posthog-key
VERCEL_ANALYTICS_ID=your-analytics-id

Railway Environment Variables (Backend Services)¶

# Database Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Redis Configuration
REDIS_URL=redis://default:password@host:port

# 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_BASE_URL=https://im-service.railway.app
SMM_BASE_URL=https://smm-service.railway.app

# Monitoring
PROMETHEUS_PUSHGATEWAY_URL=your-prometheus-gateway
LOG_LEVEL=INFO

Scaling Configuration¶

Vercel Scaling¶

• Automatic: Serverless functions auto-scale based on demand
• Edge Caching: Static assets cached globally on Vercel Edge Network
• Concurrent Requests: Up to 1,000 concurrent serverless function executions

Railway Scaling¶

• Horizontal Scaling: Auto-scale based on CPU/memory usage
• Resource Limits: Configurable per service (CPU, RAM, replicas)
• Health Checks: HTTP health endpoints for service monitoring

# Railway deployment configuration (railway.json)
{
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "pip install -r requirements.txt"
  },
  "deploy": {
    "startCommand": "uvicorn app:app --host 0.0.0.0 --port $PORT",
    "healthcheckPath": "/health",
    "healthcheckTimeout": 30,
    "restartPolicyType": "ON_FAILURE"
  }
}

Security and Authentication¶

Authentication Flow¶

sequenceDiagram
    participant User as User
    participant Frontend as Next.js Frontend
    participant Supabase as Supabase Auth
    participant Backend as Backend Services
    participant DB as Database

    User->>Frontend: Login request
    Frontend->>Supabase: Authenticate
    Supabase->>Frontend: JWT token + session
    Frontend->>Backend: API request + JWT
    Backend->>Supabase: Verify JWT
    Supabase->>Backend: User claims
    Backend->>DB: Query with RLS
    DB->>Backend: Filtered results
    Backend->>Frontend: API response

Security Features¶

Authentication & Authorization¶

• JWT Tokens: Supabase-issued JWT tokens with automatic refresh
• Row-Level Security: Database-level access control
• 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
• Rate Limiting: Request throttling per user/IP
• Input Validation: Pydantic models for request validation
• SQL Injection Protection: Parameterized queries via Supabase client

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)
├── supabase/            # 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
supabase start          # Start local Supabase
supabase db reset       # Reset local database
supabase 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 Vercel
        uses: amondnet/vercel-action@v25
      - name: Deploy to Railway
        uses: railway-deploy@v1

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 Railway/Vercel dashboards

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

This documentation is maintained as a living document and updated with each major release. Last updated: August 2025