Architecture¶

Convergio AI is a full-stack TypeScript application with a React frontend, Express backend, PostgreSQL database, and n8n workflow automation.

High-level overview¶

graph TB
    subgraph Frontend ["Frontend (React + Vite)"]
        Dashboard[Dashboard]
        Boost[Boost Suite]
        Calendar[Calendar]
        Settings[Settings]
        AICopilot[AI Copilot]
    end

    subgraph Backend ["Backend (Express 5)"]
        Auth[Auth & JWT]
        EmailAPI[Email API]
        TaskAPI[Task API]
        AIAPI[AI API]
        CalAPI[Calendar API]
        StreamAPI[StreamBoost API]
        SettingsAPI[Settings API]
    end

    subgraph Automation ["n8n Workflows"]
        EmailAgent[Email Agent]
        LiveDetector[YouTube Live Detector]
        CrossPost[Cross-Platform Poster]
        CalSync[Cal.com Sync]
        AuditWF[Digital Audit]
    end

    subgraph External ["External Services"]
        Claude[Anthropic Claude]
        Gemini[Google Gemini]
        YouTube[YouTube Data API]
        Discord[Discord Webhooks]
        Meta[Meta Graph API]
        XAPI[X / Twitter API]
        CalCom[Cal.com API]
    end

    subgraph Data ["Data Layer"]
        PG[(PostgreSQL)]
    end

    Frontend <-->|REST API| Backend
    Backend <--> PG
    Automation -->|Webhooks| Backend
    Backend --> Claude
    Backend --> Gemini
    Automation --> YouTube
    Automation --> Discord
    Automation --> Meta
    Automation --> XAPI
    Automation --> CalCom

Technology stack¶

Design patterns¶

Multi-model AI adapter¶

The callAI() function routes requests to the active AI provider based on runtime configuration:

graph LR
    Request --> Router[callAI Router]
    Router -->|gemini| Gemini[Google Gemini]
    Router -->|claude| Claude[Anthropic Claude]
    Router -->|qwen| OpenRouter[Qwen via OpenRouter]
    Router -->|qwen3| Bytez[Qwen3 via Bytez]

Users can switch the active model at runtime via /api/ai-model without restarting the server.

Email tag derivation¶

Emails are automatically categorized by the recipient address prefix:

Auto-task creation¶

Every incoming email automatically creates a corresponding task via saveEmailToDB(), ensuring nothing falls through the cracks.

JWT + database sessions¶

Authentication uses a double-check pattern:

1. JWT token must be valid (signature + expiry)
2. Session record must exist and be active in the database

This allows instant session revocation without waiting for JWT expiry.

Deployment architecture¶

graph LR
    User[User Browser] -->|HTTPS| Netlify[Netlify CDN]
    Netlify -->|/api/* proxy| VPS[VPS - Express API]
    VPS --> PG[(PostgreSQL)]
    n8n[n8n Instance] -->|Webhooks| VPS
    n8n --> YouTube[YouTube API]
    n8n --> Discord[Discord]
    n8n --> Email[IMAP/SMTP]