# cgoinglove/better-chatbot architecture

> Architecture diagram of the GitHub repository cgoinglove/better-chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cgoinglove/better-chatbot
- Repository: https://github.com/cgoinglove/better-chatbot

## Overview

##### Project Type and Purpose
- Full-stack web application built on Next.js App Router
- Provides a React-based UI, serverless API routes, Drizzle ORM data layer, and integration with multiple LLMs & tools via the Model Context Protocol (MCP)

##### Core Architectural Components
a. Client (Browser)
- React/Next.js app running in the browser
- Uses React Server Components & Client Components (src/app, components/)
- Hooks & SWR for client-side data fetching/state (src/hooks)
b. Next.js Server (Node.js Runtime)
- Renders pages, handles API routes under src/app/api
- Business logic in src/lib (auth, ai, workflows, db, file-storage, cache, etc.)
- Authentication via Better-Auth & OAuth connectors (lib/auth + external OAuth providers)
- Drizzle ORM for migrations & queries (drizzle.config.ts + lib/db + migrations)
- File storage abstraction (Vercel Blob / S3 driver in lib/file-storage)
- Optional cache layer (Redis via lib/cache)
c. Database
- PostgreSQL (Docker-compose / external)
- Schema & repositories under lib/db/pg/repositories
d. File Storage
- Vercel Blob (default) or S3
e. External Services & Protocols
- **LLM Providers**: OpenAI, Anthropic, Google Generative AI, xAI, Ollama, etc. (lib/ai)
- **Model Context Protocol (MCP)**: External MCP servers (custom-mcp-server microservice + any remote MCP servers)
- **Web Search**: Exa AI (optional)
- **Tool Execution**: JS/Python code runners (lib/code-runner), data-viz tools (lib/ai/tools/visualization)
- **OAuth Providers**: GitHub, Google, Microsoft for social sign-in
f. Custom-MCP-Server Microservice
- A small Express/Next microservice (custom-mcp-server/index.ts) to host user-defined MCP tools

##### Relationships & Data Flow
1. User interacts in the Browser (UI & React components)
→ API calls to Next.js Server via fetch/route handlers (src/app/api/*)
2. Next.js API routes
→ Authentication layer (lib/auth)
→ Business logic (chat, agents, workflows under lib/ai/workflow, lib/ai/agent)
→ Data access via Drizzle ORM → PostgreSQL
→ File uploads/downloads via File-Storage driver → Blob/S3
→ Caching (optional) → Redis
→ External calls to LLM providers & MCP servers (lib/ai & custom-mcp-server)
3. Real-time features (voice chat, streaming responses)
→ SSE/WebSocket-style streaming from Next.js to client

##### Architectural Patterns & Design Principles
- **Monolithic container** (Next.js) with serverless function style APIs
- **Folder-based routing** (App Router) dividing UI, API, and middleware
- **Separation of Concerns**:
– UI (components/)
– Business Logic (lib/ai, lib/auth, lib/workflow)
– Data Access (lib/db)
– Infrastructure (docker/, scripts/, drizzle migrations)

a. Browser/Client Layer
– React Server/Client Components (src/app, components/)
– Hooks & SWR for data fetching
b. Next.js Server (Single Container)
– App Router & Middleware (src/app/layout.tsx, middleware.ts)
– API Routes (src/app/api/*)
– Business Logic Modules (src/lib/*)
· auth, ai, workflows, file-storage, cache, code-runner
– Drizzle ORM & Migrations (drizzle.config.ts + lib/db)
– File Upload/Download (lib/file-storage)
– Caching Layer (lib/cache → Redis)
– Instrumentation & Logging (src/instrumentation.ts + lib/logger)
c. Custom-MCP-Server Service
– HTTP endpoints (custom-mcp-server/index.ts)
– Manages third-party tool definitions via MCP protocol
d. Data Stores
– PostgreSQL (Docker or external)
– Redis (optional, for rate limiting, ephemeral caching)
– Blob/S3 file storage
e. External Services
– LLM APIs (OpenAI, Claude, Google, xAI, Ollama)
– Exa AI (Web Search)
– OAuth: GitHub, Google, Microsoft

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Browser (Client)" 
        direction TB
        ClientUI["React Components"]:::frontend
        Hooks["Data Hooks (SWR)"]:::frontend
    end

    %% Next.js Server
    subgraph "Next.js Server (SSR + API)" 
        direction TB
        AppRouter["App Router & Middleware"]:::backend
        APIRoutes["API Routes"]:::backend
        AuthLogic["Auth Logic"]:::backend
        AILogic["AI Integrations"]:::backend
        Workflow["Workflow Orchestration"]:::backend
        DBLayer["Drizzle ORM & DB"]:::backend
        FileStorage["File Storage Abstraction"]:::backend
        CacheLayer["Cache Layer"]:::backend
        CodeRunner["Code Runner"]:::backend
        Instrumentation["Logging & Instrumentation"]:::backend
    end

    %% Custom MCP
    CustomMCP["Custom-MCP-Server Service"]:::external

    %% Data Stores
    PostgreSQL["PostgreSQL DB"]:::database
    Redis["Redis Cache"]:::database
    BlobStorage["Blob/S3 Storage"]:::database

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI"]:::external
        Anthropic["Anthropic"]:::external
        GoogleGenAI["Google GenAI"]:::external
        xAI["xAI"]:::external
        Ollama["Ollama"]:::external
        ExaAI["Exa AI (Web Search)"]:::external
        GitHubOAuth["GitHub OAuth"]:::external
        GoogleOAuth["Google OAuth"]:::external
        MicrosoftOAuth["Microsoft OAuth"]:::external
    end

    %% Connections
    ClientUI -->|"fetch API"| APIRoutes
    Hooks -->|"uses"| APIRoutes

    APIRoutes -->|"authenticate"| AuthLogic
    APIRoutes -->|"execute workflows"| Workflow
    APIRoutes -->|"AI calls"| AILogic
    APIRoutes -->|"db queries"| DBLayer
    APIRoutes -->|"file ops"| FileStorage
    APIRoutes -->|"cache ops"| CacheLayer
    APIRoutes -->|"run code"| CodeRunner
    APIRoutes -->|"log metrics"| Instrumentation

    AILogic -->|"/mcp"| CustomMCP
    AILogic -->|"LLM API"| OpenAI
    AILogic -->|"LLM API"| Anthropic
    AILogic -->|"LLM API"| GoogleGenAI
    AILogic -->|"LLM API"| xAI
    AILogic -->|"LLM API"| Ollama
    AILogic -->|"web search"| ExaAI

    AuthLogic -->|"OAuth"| GitHubOAuth
    AuthLogic -->|"OAuth"| GoogleOAuth
    AuthLogic -->|"OAuth"| MicrosoftOAuth

    DBLayer -->|SQL| PostgreSQL
    CacheLayer -->|cache| Redis
    FileStorage -->|store| BlobStorage

    %% Click Events for Component Mapping
    click ClientUI "https://github.com/cgoinglove/better-chatbot/tree/main/src/app/"
    click Hooks "https://github.com/cgoinglove/better-chatbot/tree/main/src/hooks/"
    click APIRoutes "https://github.com/cgoinglove/better-chatbot/tree/main/src/app/api/"
    click AuthLogic "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/auth/"
    click AILogic "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/ai/"
    click Workflow "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/ai/workflow/"
    click DBLayer "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/db/"
    click FileStorage "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/file-storage/"
    click CacheLayer "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/cache/"
    click CodeRunner "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/code-runner/"
    click AppRouter "https://github.com/cgoinglove/better-chatbot/blob/main/src/middleware.ts"
    click Instrumentation "https://github.com/cgoinglove/better-chatbot/blob/main/src/instrumentation.ts"
    click DBLayer "https://github.com/cgoinglove/better-chatbot/blob/main/drizzle.config.ts"
    click DBLayer "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/db/pg/"
    click DBLayer "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/db/migrations/pg/"
    click DBLayer "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/db/migrations/pg/meta/"
    click DBLayer "https://github.com/cgoinglove/better-chatbot/blob/main/src/lib/db/pg/schema.pg.ts"
    click DBLayer "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/db/pg/repositories/"
    click FileStorage "https://github.com/cgoinglove/better-chatbot/blob/main/src/lib/file-storage/vercel-blob-storage.ts"
    click FileStorage "https://github.com/cgoinglove/better-chatbot/blob/main/src/lib/file-storage/s3-file-storage.ts"
    click FileStorage "https://github.com/cgoinglove/better-chatbot/tree/main/src/app/api/storage/"
    click CacheLayer "https://github.com/cgoinglove/better-chatbot/blob/main/src/lib/cache/redis-cache.ts"
    click CacheLayer "https://github.com/cgoinglove/better-chatbot/blob/main/src/lib/cache/memory-cache.ts"
    click CacheLayer "https://github.com/cgoinglove/better-chatbot/blob/main/src/lib/cache/index.ts"
    click AILogic "https://github.com/cgoinglove/better-chatbot/blob/main/src/lib/ai/create-openai-compatiable.ts"
    click AILogic "https://github.com/cgoinglove/better-chatbot/blob/main/src/lib/ai/azure-openai-compatible.ts"
    click AILogic "https://github.com/cgoinglove/better-chatbot/blob/main/src/lib/ai/models.ts"
    click AILogic "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/ai/mcp/"
    click AILogic "https://github.com/cgoinglove/better-chatbot/tree/main/src/app/api/mcp/"
    click AILogic "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/ai/tools/"
    click AILogic "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/ai/tools/code/"
    click AILogic "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/ai/tools/visualization/"
    click CodeRunner "https://github.com/cgoinglove/better-chatbot/tree/main/src/lib/code-runner/"
    click CustomMCP "https://github.com/cgoinglove/better-chatbot/blob/main/custom-mcp-server/index.ts"
    click AILogic "https://github.com/cgoinglove/better-chatbot/blob/main/src/app/api/chat/openai-realtime/route.ts"
    click AILogic "https://github.com/cgoinglove/better-chatbot/blob/main/src/lib/ai/speech/open-ai/use-voice-chat.openai.ts"
    click AILogic "https://github.com/cgoinglove/better-chatbot/tree/main/public/sounds/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#CCE5FF,stroke:#004085,stroke-width:1px
    classDef database fill:#D4EDDA,stroke:#155724,stroke-width:1px
    classDef external fill:#FFE5B4,stroke:#FF8C00,stroke-width:1px
```
