# topmate-io/top-chat architecture

> Architecture diagram of the GitHub repository topmate-io/top-chat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/topmate-io/top-chat
- Repository: https://github.com/topmate-io/top-chat

## Overview

##### Project Type & Purpose
- This is a full-stack, AI-powered chat interface built with Next.js (App Router) and Vercel AI SDK.
- It combines a React/Next.js frontend, Next.js API routes (backend), a PostgreSQL database, an optional custom MCP server, and integrations with external LLM providers and OAuth services.

##### Top-Level Architectural Zones
a. Client (Browser & Static Assets)
b. App Server (Next.js)
c. Infrastructure & External Services

##### Main Components
a. Client Layer
- Browser UI
- React components in src/app and src/components (chat UI, popups, tool selectors, voice, etc.)
- Global CSS, public assets (sounds), localization JSON (messages/).
- Client-side store (Zustand in src/app/store.ts)
- Hook modules (src/hooks/)

b. App Server Layer
- Next.js App Router & API Routes (src/app/api/)
- Authentication middleware & Better Auth integration (src/lib/auth/, middleware.ts)
- Business logic modules (src/lib/):
- AI orchestrator and MCP manager (src/lib/ai/mcp/, create-mcp-client, config storage)
- LLM prompts & speech modules (src/lib/ai/models.ts, speech/openai)
- Cache layer (memory + optional Redis)
- DB access via Drizzle ORM & custom repositories (src/lib/db/pg/, src/lib/db/repository.ts)
- Utility libraries (utils, logger, load-env)
- Scripts & tooling (scripts/, drizzle.config.ts, .husky hooks)
- Dockerfile & compose.yml to containerize the app + Postgres + (optionally) custom-mcp-server

c. Infrastructure & External Services
- PostgreSQL (HOST: POSTGRES_URL)
- Optional custom MCP server (custom-mcp-server/index.ts)
- External AI Providers: OpenAI, Anthropic, Google Generative AI, etc.
- OAuth Providers: Google, GitHub
- (Optional) Redis for caching
- Vercel hosting or local Docker Compose

##### Interactions & Data Flow
1. User → Browser UI (React pages)
2. UI → Next.js API routes (REST/JSON calls)
3. API routes → Auth module → Token/session store
4. API routes → DB layer for user, thread, chat history
5. API routes → Cache layer (memory or Redis)
6. Chat endpoints → AI orchestrator/MCP manager → calls to external LLMs or MCP servers
7. Responses propagate back to the browser store → UI updates

##### Architectural Patterns & Principles
- App Router with separation of “(auth)” and “(chat)” segments
- React Server Components + Client Components
- Layered application: UI / API / Business Logic / Persistence
- Adapter pattern for external tools (MCP clients, AI providers, cache, DB)
- Configuration via environment variables and Drizzle config

##### Technologies & Frameworks
- Next.js (App Router)
- Vercel AI SDK
- React + Zustand store
- Drizzle ORM + PostgreSQL
- Better Auth (session management)
- Node.js + TypeScript
- Docker & Docker Compose
- Optional Redis cache
- Vercel / Playwright integration examples

##### Layer-Specific Advice
- Frontend: Highlight the App Router structure (`(auth)`, `(chat)`) and major UI components (chat window, tool dropdown, voice UI).
- Backend: Show API route hierarchy under `/api/*` and connect them to their respective lib modules (chat, mcp, user/preferences).
- External Integrations: Illustrate calls to AI provider endpoints, MCP server endpoints, OAuth flows, and DB migrations via scripts.

##### Detail Granularity
- Do not omit the caching layer or the custom MCP server (even if optional).
- Both code modules (TypeScript files/folders) and runtime services (Docker containers).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        BrowserUI["Browser UI\n(React Components)"]:::frontend
        Store["Zustand Store"]:::frontend
        Hooks["Hook Modules"]:::frontend
        LayoutAuth["Auth Segment\n(src/app/(auth)/)"]:::frontend
        LayoutChat["Chat Segment\n(src/app/(chat)/)"]:::frontend
        StaticAssets["Localization & Static Assets"]:::frontend
    end

    %% App Server Layer
    subgraph "App Server"
        direction TB
        APIRoutes["Next.js API Routes"]:::backend
        AuthMW["Authentication Middleware\n& Better Auth"]:::backend
        subgraph "Business Logic"
            direction TB
            AIOrch["AI Orchestrator & MCP Manager"]:::backend
            subgraph "LLM & Speech"
                Prompts["Prompts & Models"]:::backend
                Speech["Speech Support"]:::backend
            end
            subgraph "Cache Layer"
                MemCache["Memory Cache"]:::backend
                RedisCache["Redis Cache"]:::backend
            end
            subgraph "DB Access"
                DrizzleCfg["Drizzle Config"]:::backend
                PGSetup["PG Setup & Migrations"]:::backend
                Repos["Repositories (Chat, User, MCP)"]:::backend
            end
            subgraph "Utils & Tools"
                EnvLoader["Env Loader"]:::backend
                Logger["Logger"]:::backend
                Utils["General Utils"]:::backend
            end
        end
        Scripts["Scripts & Tooling"]:::backend
        Docker["Docker & Compose"]:::backend
    end

    %% Infrastructure & External
    subgraph "Infrastructure & External"
        direction TB
        Postgres["PostgreSQL"]:::external
        MCPServer["Custom MCP Server"]:::external
        Providers["AI Providers\n(OpenAI, Anthropic, Google)"]:::external
        OAuth["OAuth Providers\n(Google, GitHub)"]:::external
        Vercel["Vercel Hosting"]:::external
        RedisSrv["Redis (optional)"]:::external
    end

    %% Connections
    User["User"]:::external
    User -->|"interacts"| BrowserUI
    BrowserUI -->|"calls API"| APIRoutes
    APIRoutes -->|"auth checks"| AuthMW
    APIRoutes -->|"reads/writes"| Repos
    APIRoutes -->|"uses"| MemCache
    APIRoutes -->|"uses"| RedisCache
    APIRoutes -->|"invokes"| AIOrch
    AIOrch -->|"calls LLMs"| Providers
    AIOrch -->|"calls MCP"| MCPServer
    Providers -->|"responses"| AIOrch
    MCPServer -->|"responses"| AIOrch
    AIOrch -->|"returns"| APIRoutes
    APIRoutes -->|"response"| BrowserUI
    BrowserUI -->|"updates"| Store

    %% Click Events - Client
    click BrowserUI "https://github.com/topmate-io/top-chat/tree/main/src/app/"
    click BrowserUI "https://github.com/topmate-io/top-chat/tree/main/src/components/"
    click Store "https://github.com/topmate-io/top-chat/blob/main/src/app/store.ts"
    click Hooks "https://github.com/topmate-io/top-chat/tree/main/src/hooks/"
    click LayoutAuth "https://github.com/topmate-io/top-chat/tree/main/src/app/(auth)/"
    click LayoutChat "https://github.com/topmate-io/top-chat/tree/main/src/app/(chat)/"
    click StaticAssets "https://github.com/topmate-io/top-chat/blob/main/messages/*.json"
    click StaticAssets "https://github.com/topmate-io/top-chat/tree/main/public/sounds/"

    %% Click Events - Server
    click APIRoutes "https://github.com/topmate-io/top-chat/tree/main/src/app/api/"
    click AuthMW "https://github.com/topmate-io/top-chat/blob/main/src/middleware.ts"
    click AuthMW "https://github.com/topmate-io/top-chat/blob/main/src/lib/auth/client.ts"
    click AuthMW "https://github.com/topmate-io/top-chat/blob/main/src/lib/auth/server.ts"
    click AIOrch "https://github.com/topmate-io/top-chat/blob/main/src/lib/ai/mcp/create-mcp-client.ts"
    click AIOrch "https://github.com/topmate-io/top-chat/blob/main/src/lib/ai/mcp/create-mcp-clients-manager.ts"
    click AIOrch "https://github.com/topmate-io/top-chat/blob/main/src/lib/ai/mcp/mcp-manager.ts"
    click AIOrch "https://github.com/topmate-io/top-chat/blob/main/src/lib/ai/mcp/db-mcp-config-storage.ts"
    click AIOrch "https://github.com/topmate-io/top-chat/blob/main/src/lib/ai/mcp/fb-mcp-config-storage.ts"
    click Prompts "https://github.com/topmate-io/top-chat/blob/main/src/lib/ai/models.ts"
    click Prompts "https://github.com/topmate-io/top-chat/blob/main/src/lib/ai/prompts.ts"
    click Speech "https://github.com/topmate-io/top-chat/tree/main/src/lib/ai/speech/"
    click MemCache "https://github.com/topmate-io/top-chat/blob/main/src/lib/cache/memory-cache.ts"
    click RedisCache "https://github.com/topmate-io/top-chat/blob/main/src/lib/cache/redis-cache.ts"
    click MemCache "https://github.com/topmate-io/top-chat/blob/main/src/lib/cache/index.ts"
    click MemCache "https://github.com/topmate-io/top-chat/blob/main/src/lib/cache/cache.interface.ts"
    click MemCache "https://github.com/topmate-io/top-chat/blob/main/src/lib/cache/cache-keys.ts"
    click DrizzleCfg "https://github.com/topmate-io/top-chat/blob/main/drizzle.config.ts"
    click PGSetup "https://github.com/topmate-io/top-chat/blob/main/src/lib/db/pg/db.pg.ts"
    click PGSetup "https://github.com/topmate-io/top-chat/blob/main/src/lib/db/pg/migrate.pg.ts"
    click PGSetup "https://github.com/topmate-io/top-chat/tree/main/src/lib/db/migrations/pg/"
    click Repos "https://github.com/topmate-io/top-chat/blob/main/src/lib/db/pg/repositories/chat-repository.pg.ts"
    click Repos "https://github.com/topmate-io/top-chat/blob/main/src/lib/db/pg/repositories/mcp-repository.pg.ts"
    click Repos "https://github.com/topmate-io/top-chat/blob/main/src/lib/db/pg/repositories/user-repository.pg.ts"
    click Repos "https://github.com/topmate-io/top-chat/blob/main/src/lib/db/repository.ts"
    click Repos "https://github.com/topmate-io/top-chat/blob/main/src/lib/db/utils.ts"
    click EnvLoader "https://github.com/topmate-io/top-chat/blob/main/src/lib/load-env.ts"
    click Logger "https://github.com/topmate-io/top-chat/blob/main/src/lib/logger.ts"
    click Utils "https://github.com/topmate-io/top-chat/blob/main/src/lib/utils.ts"
    click Utils "https://github.com/topmate-io/top-chat/blob/main/src/lib/utils.test.ts"
    click Utils "https://github.com/topmate-io/top-chat/blob/main/src/lib/keyboard-shortcuts.ts"
    click Utils "https://github.com/topmate-io/top-chat/blob/main/src/lib/fuzzy-search.ts"
    click Utils "https://github.com/topmate-io/top-chat/blob/main/src/lib/fuzzy-search.test.ts"
    click Scripts "https://github.com/topmate-io/top-chat/blob/main/scripts/clean.ts"
    click Scripts "https://github.com/topmate-io/top-chat/blob/main/scripts/db-migrate.ts"
    click Scripts "https://github.com/topmate-io/top-chat/blob/main/scripts/initial-env.ts"
    click Scripts "https://github.com/topmate-io/top-chat/blob/main/scripts/postinstall.ts"
    click Scripts "https://github.com/topmate-io/top-chat/tree/main/.husky/pre-commit"
    click Docker "https://github.com/topmate-io/top-chat/tree/main/docker/Dockerfile"
    click Docker "https://github.com/topmate-io/top-chat/blob/main/docker/compose.yml"

    %% Click Events - Infra
    click Postgres "https://github.com/topmate-io/top-chat/tree/main/POSTGRES_URL"
    click MCPServer "https://github.com/topmate-io/top-chat/blob/main/custom-mcp-server/index.ts"
    click Providers "https://github.com/topmate-io/top-chat/tree/main/External AI Providers"
    click OAuth "https://github.com/topmate-io/top-chat/blob/main/docs/tips-guides/oauth.md"
    click Vercel "https://github.com/topmate-io/top-chat/blob/main/docs/tips-guides/vercel.md"
    click RedisSrv "https://github.com/topmate-io/top-chat/tree/main/Optional Redis"

    %% Styles
    classDef frontend fill:#8ecae6,stroke:#219ebc,color:#023047;
    classDef backend fill:#a6d192,stroke:#2a9d8f,color:#264653;
    classDef external fill:#f4a261,stroke:#e76f51,color:#ffffff;
```
