# zaidmukaddam/scira-mcp-chat architecture

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

- Interactive diagram: https://gitdiagram.com/zaidmukaddam/scira-mcp-chat
- Repository: https://github.com/zaidmukaddam/scira-mcp-chat

## Overview

##### Project type and purpose
- This is a full-stack, open-source AI chatbot application built with Next.js (App Router) and the Vercel AI SDK.
- It integrates with external Model Context Protocol (MCP) servers (via SSE or stdio) to expand AI tool capabilities, while persisting chat history in a SQL database using Drizzle ORM.

##### File structure
- Top-level “app” directory: Next.js App Router pages, layouts, global styles, and API endpoints under app/api/chat and app/api/chats.
- “components” and “components/ui”: React UI building blocks (shadcn/ui + Tailwind CSS) for chat, sidebar, model picker, theme, etc.
- “lib”: shared utilities, React contexts, custom hooks (chat-store, local storage, scroll, etc.), database initialization (lib/db), and user-id generation.
- “ai/providers.ts”: abstraction over AI SDK providers and MCP transports.
- “drizzle” + drizzle.config.ts: database migrations and schema (SQL files and snapshot metadata).
- Config files: next.config.ts, tsconfig.json, postcss.config.mjs, railpack.json, eslint.config.mjs, package.json.

##### README for insights
- Confirms use of Next.js, Vercel AI SDK, MCP servers (SSE and stdio), Drizzle ORM, shadcn/ui + Tailwind.
- Describes runtime flows (adding MCP servers, streaming responses).

##### Final recommendations
- Both synchronous API calls and streaming data flows.
- Customization points (adding MCP servers, switching transports).
- Iterate with developers: update as new features or transports are added.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        Browser["User’s Browser"]:::frontend
        UI["React UI Components"]:::frontend
        ContextHooks["React Context & Hooks"]:::frontend
        LocalStorage["Local Storage / Cache"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        direction TB
        ChatAPI["Chat API Route"]:::backend
        ChatsAPI["Chats API Route"]:::backend
        ChatsByIdAPI["ChatsById API Route"]:::backend
        Orchestration["AI Orchestration Layer"]:::backend
        MCPTransport["MCP Transport Layer"]:::backend
        VercelSDK["Vercel AI SDK"]:::external
        subgraph "Database Layer"
            direction TB
            DBInit["DB Init (Drizzle)"]:::db
            DBSchema["DB Schema"]:::db
            DBConfig["drizzle.config.ts"]:::db
            Migrations["SQL Migrations"]:::db
        end
    end

    %% External Services
    MCPServers["External MCP Servers"]:::external

    %% Frontend to Backend Flows
    Browser -->|"renders"| UI
    UI -->|"contexts/hooks"| ContextHooks
    ContextHooks -->|"persists"| LocalStorage
    UI -->|"HTTP calls"| ChatAPI
    UI -->|"HTTP calls"| ChatsAPI

    %% API to Orchestration
    ChatAPI -->|"invoke AI"| Orchestration
    ChatsAPI -->|read/write history| DBInit
    ChatsByIdAPI -->|read/write history| DBInit

    %% Orchestration flows
    Orchestration -->|"use Vercel SDK"| VercelSDK
    Orchestration -->|"use MCP transport"| MCPTransport
    MCPTransport -->|"SSE/stdio"| MCPServers

    %% Database flows
    DBInit -->|apply schema| DBSchema
    DBInit -->|use config| DBConfig
    DBInit -->|run migrations| Migrations

    %% Click Events
    click Browser "https://github.com/zaidmukaddam/scira-mcp-chat/blob/main/app/layout.tsx"
    click UI "https://github.com/zaidmukaddam/scira-mcp-chat/tree/main/components/"
    click ChatAPI "https://github.com/zaidmukaddam/scira-mcp-chat/blob/main/app/api/chat/route.ts"
    click ChatsAPI "https://github.com/zaidmukaddam/scira-mcp-chat/blob/main/app/api/chats/route.ts"
    click ChatsByIdAPI "https://github.com/zaidmukaddam/scira-mcp-chat/blob/main/app/api/chats/[id]/route.ts"
    click Orchestration "https://github.com/zaidmukaddam/scira-mcp-chat/blob/main/ai/providers.ts"
    click MCPTransport "https://github.com/zaidmukaddam/scira-mcp-chat/blob/main/lib/context/mcp-context.tsx"
    click DBInit "https://github.com/zaidmukaddam/scira-mcp-chat/blob/main/lib/db/index.ts"
    click DBSchema "https://github.com/zaidmukaddam/scira-mcp-chat/blob/main/lib/db/schema.ts"
    click DBConfig "https://github.com/zaidmukaddam/scira-mcp-chat/blob/main/drizzle.config.ts"
    click Migrations "https://github.com/zaidmukaddam/scira-mcp-chat/tree/main/drizzle/"
    click ContextHooks "https://github.com/zaidmukaddam/scira-mcp-chat/blob/main/lib/hooks/use-chats.ts"
    click LocalStorage "https://github.com/zaidmukaddam/scira-mcp-chat/blob/main/lib/hooks/use-local-storage.ts"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064,stroke-width:1px;
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20,stroke-width:1px;
    classDef db fill:#EFEBE9,stroke:#5D4037,color:#5D4037,stroke-width:1px;
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A,stroke-width:1px;
```
