# datdao1998/mcp-chainlit architecture

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

- Interactive diagram: https://gitdiagram.com/datdao1998/mcp-chainlit
- Repository: https://github.com/datdao1998/mcp-chainlit

## Overview

##### Project type and purpose
- This is a microservice-driven application that glues together:
– A Chainlit-based UI (chat front-end)
– An MCP server (event/command orchestrator over Server-Sent Events)
– A FastAPI “mcp_api” microservice (business logic & REST endpoints)
– A PostgreSQL database (persistent storage)
– External LLM service (OpenRouter) and custom tools (e.g. cat facts)

##### File structure
- Top-level:
– requirements.txt, README.md, chainlit.md – global docs & deps
– mcp_api/ – FastAPI app (app.py + controller, routers, schemas)
– mcp_server/ – MCP server & Chainlit UI (server.py, ui.py), setup, tools, DB init, .chainlit config
- Patterns & config:
– mcp_api follows an MVC-style split (routers → controllers → schemas)
– mcp_server uses Server-Sent Events (SSE) transport for MCP and Chainlit’s plugin system
– Docker-Compose under mcp_server/setup for Postgres

##### README for technical stack & workflow
- Python 3.x, FastAPI + Uvicorn, Chainlit framework, MCP CLI
- Postgres in Docker, DB initialized via resources/database/init.py
- Workflow:
1. Start FastAPI (port 8001)
2. Run MCP server (default port 8000, SSE)
3. Launch Chainlit UI (port 8090)
4. Use UI → MCP → plugins (FastAPI, DB utils, external LLM/tools)

##### Main components & interactions (
a. Frontend Layer
– Chainlit UI (ui.py)
– Interacts with MCP server via SSE/websocket plugin endpoints
b. Orchestrator Layer
– MCP Server (server.py + plugin manager)
– Exposes SSE endpoint (/messages) for UI
– Dispatches plugin calls to:
- FastAPI microservice (HTTP 8001)
- Local tools (get_cat_facts.py)
- Database utils (resources/database/utils.py)
- External LLM (OpenRouter API)
c. Microservice Layer
– FastAPI “mcp_api”
- Routers → Controllers → Schemas
- Exposes REST endpoints (e.g., /user)
- May also use Postgres (if configured)
d. Data Layer
– PostgreSQL (Docker-Compose)
– Initialized by init.py
e. External Services
– OpenRouter (LLM API)
– Any third-party APIs used by tools

##### Architectural patterns & design principles
- Microservices (separate FastAPI API)
- Event-driven plugin orchestration (MCP + SSE)
- MVC in the FastAPI service
- Clear separation of concerns: UI vs. orchestrator vs. services vs. data

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        UI["Chainlit UI"]:::frontend
        Config[".chainlit/config.toml"]:::frontend
        Translations[".chainlit/translations/"]:::frontend
    end

    %% Orchestrator Layer
    subgraph "Orchestrator Layer"
        direction TB
        MCP["MCP Server"]:::orchestrator
        ENV[".env"]:::orchestrator
        PyProj["pyproject.toml"]:::orchestrator
    end

    %% Plugin Tools
    subgraph "Plugin Tools"
        direction TB
        CatFacts["get_cat_facts.py"]:::service
    end

    %% Microservice Layer
    subgraph "Microservice Layer"
        direction TB
        FastAPI["mcp_api (FastAPI)"]:::service
        Router["routers/user.py"]:::service
        Controller["controller/user.py"]:::service
        Schema["schemas/user.py"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Init["init.py"]:::service
        Utils["utils.py"]:::service
        Compose["docker-compose.yaml"]:::database
        SetupConf["config.py"]:::database
        Postgres["PostgreSQL"]:::database
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenRouter["OpenRouter LLM API"]:::external
    end

    %% Connections
    UI -->|"SSE/Websocket"| MCP
    MCP -->|"HTTP:8001"| FastAPI
    MCP -->|"exec"| CatFacts
    MCP -->|"call"| Utils
    Utils -->|"TCP:5432"| Postgres
    MCP -->|"HTTPS"| OpenRouter

    %% Click Events
    click UI "https://github.com/datdao1998/mcp-chainlit/blob/main/mcp_server/ui.py"
    click Config "https://github.com/datdao1998/mcp-chainlit/blob/main/mcp_server/.chainlit/config.toml"
    click Translations "https://github.com/datdao1998/mcp-chainlit/tree/main/mcp_server/.chainlit/translations/"
    click MCP "https://github.com/datdao1998/mcp-chainlit/blob/main/mcp_server/server.py"
    click ENV "https://github.com/datdao1998/mcp-chainlit/blob/main/mcp_server/.env"
    click PyProj "https://github.com/datdao1998/mcp-chainlit/blob/main/mcp_server/pyproject.toml"
    click CatFacts "https://github.com/datdao1998/mcp-chainlit/blob/main/mcp_server/tools/get_cat_facts.py"
    click Init "https://github.com/datdao1998/mcp-chainlit/blob/main/mcp_server/resources/database/init.py"
    click Utils "https://github.com/datdao1998/mcp-chainlit/blob/main/mcp_server/resources/database/utils.py"
    click Compose "https://github.com/datdao1998/mcp-chainlit/blob/main/mcp_server/setup/docker-compose.yaml"
    click SetupConf "https://github.com/datdao1998/mcp-chainlit/blob/main/mcp_server/setup/config.py"
    click FastAPI "https://github.com/datdao1998/mcp-chainlit/blob/main/mcp_api/app.py"
    click Router "https://github.com/datdao1998/mcp-chainlit/blob/main/mcp_api/routers/user.py"
    click Controller "https://github.com/datdao1998/mcp-chainlit/blob/main/mcp_api/controller/user.py"
    click Schema "https://github.com/datdao1998/mcp-chainlit/blob/main/mcp_api/schemas/user.py"

    %% Styles
    classDef frontend fill:#D5E8D4,stroke:#333
    classDef orchestrator fill:#FFF2CC,stroke:#333
    classDef service fill:#E1D5E7,stroke:#333
    classDef database fill:#F8CECC,stroke:#333
    classDef external fill:#DAE8FC,stroke:#333
```
