# samanhappy/mcphub architecture

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

- Interactive diagram: https://gitdiagram.com/samanhappy/mcphub
- Repository: https://github.com/samanhappy/mcphub

## Overview

##### Project Type & Purpose
- MCPHub is a full-stack web application that provides a centralized dashboard (React/Vite/Tailwind) and a REST/SSE API server (Node.js/Express/TypeScript) for managing multiple external MCP (Model Context Protocol) servers. It also supports “Smart Routing” via vector embeddings stored in PostgreSQL with pgvector, and it can run as a Docker container behind Nginx.

##### Main Components
a. Frontend (React App)
- Served from `frontend/`
- Components, pages, services call API on `/api/*`, `/mcp/*`, `/sse/*`
- AuthContext, ThemeContext, ToastContext manage global state
b. Backend API Server
- Entry point: `src/server.ts` & `src/index.ts`
- Routing layer: `src/routes/index.ts` (express.Router)
- Controllers: `src/controllers/*Controller.ts`
- Services: `src/services/*Service.ts`
- DB Layer: TypeORM entities & repositories under `src/db/`
- Middlewares: auth, error handling (`src/middlewares/`)
- SSE Service: `sseService` streams MCP server output to clients
- Vector Search Service: `vectorSearchService` + OpenAI client + pgvector
c. Database
- PostgreSQL with pgvector extension
- Entities: `VectorEmbedding`, `User`, etc.
- Repositories: custom vector repo + base repo
d. External MCP Servers
- Defined in `mcp_settings.json`
- Spawned/managed via child processes SDK (`src/clients/openapi.ts`)
- Can be accessed via HTTP/SSE by backend
e. External Embedding Service
- OpenAI or any embedding provider called from `vectorSearchService`
f. Deployment & Infrastructure
- Dockerfile + entrypoint.sh
- Nginx reverse proxy (example `nginx.conf.example`)
- CI/CD workflows: GitHub Actions, Dependabot

##### Relationships & Data Flows
- User → Browser (UI)
- UI → Backend API (HTTP/HTTPS)
- UI ← SSE Stream (Real-time logs & MCP responses)
- Backend → PostgreSQL (queries, vector store)
- Backend → OpenAI Embedding API (vectorization)
- Backend → External MCP Servers (child process stdio or SSE)
- Backend ← CLI (`bin/cli.js`) for scripting or batch tasks
- Docker Container encapsulates frontend+backend; sits behind Nginx

##### Architectural Patterns & Design Principles
- Layered (Controller → Service → Repository)
- Dependency Injection via imported modules
- Configuration-driven (mcp_settings.json, environment variables)
- Stream-based processing for real-time data (SSE)
- Modular React hooks & context for separation of concerns

- Use rectangles for logical components (UI, API server, services)
- UI → API (REST calls)
- API → DB (SQL/vector queries)
- API → External services (HTTP calls, child process streams)
- API → UI (SSE streams)
- UI (blue), API server (green), Database (orange), External (gray)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Reverse Proxy
    subgraph "Nginx Reverse Proxy"
        NGINX["Nginx Proxy"]:::infra
    end

    %% Container Boundaries
    subgraph "Docker Container"
        direction TB

        subgraph "Frontend Layer"
            direction TB
            UI["React SPA"]:::ui
            COMPS["Components"]:::ui
            PAGES["Pages"]:::ui
            CTX["Contexts"]:::ui
            FSVC["Frontend Services"]:::ui
        end

        subgraph "Backend Layer (Node.js/Express)"
            direction TB
            ROUTER["Routing Layer"]:::api
            CTL["Controllers"]:::api
            BIZ["Business Logic Services"]:::api
            SVC_SSE["SSE Service"]:::api
            SVC_VEC["Vector Search Service"]:::api
            DBLAYER["DB Layer"]:::api
            MW["Middlewares"]:::api
        end

        subgraph "Infrastructure"
            direction TB
            CONFIG["mcp_settings.json"]:::infra
            CLI["CLI (bin/cli.js)"]:::infra
        end
    end

    %% External Systems
    DB["PostgreSQL + pgvector"]:::db
    OPENAI["OpenAI Embedding API"]:::external
    MCP["External MCP Servers"]:::external

    %% Data Flows
    UI -->|"HTTP /api/*"| ROUTER
    ROUTER -->|"invoke Controllers"| CTL
    CTL -->|"invoke Services"| BIZ
    BIZ -->|"SQL/Vector Queries"| DB
    BIZ -->|"HTTP Embedding"| OPENAI
    BIZ -->|"Child Process/SSE"| MCP
    SVC_SSE -->|"SSE Stream /sse/*"| UI

    %% Click Events for Frontend
    click UI "https://github.com/samanhappy/mcphub/tree/main/frontend/"
    click COMPS "https://github.com/samanhappy/mcphub/tree/main/frontend/src/components/"
    click PAGES "https://github.com/samanhappy/mcphub/tree/main/frontend/src/pages/"
    click CTX "https://github.com/samanhappy/mcphub/tree/main/frontend/src/contexts/"
    click FSVC "https://github.com/samanhappy/mcphub/tree/main/frontend/src/services/"

    %% Click Events for Backend
    click ROUTER "https://github.com/samanhappy/mcphub/blob/main/src/routes/index.ts"
    click CTL "https://github.com/samanhappy/mcphub/tree/main/src/controllers/"
    click BIZ "https://github.com/samanhappy/mcphub/tree/main/src/services/"
    click SVC_SSE "https://github.com/samanhappy/mcphub/blob/main/src/services/sseService.ts"
    click SVC_VEC "https://github.com/samanhappy/mcphub/blob/main/src/services/vectorSearchService.ts"
    click DBLAYER "https://github.com/samanhappy/mcphub/blob/main/src/db/connection.ts"
    click MW "https://github.com/samanhappy/mcphub/blob/main/src/middlewares/auth.ts"
    click CONFIG "https://github.com/samanhappy/mcphub/blob/main/mcp_settings.json"
    click CLI "https://github.com/samanhappy/mcphub/blob/main/bin/cli.js"
    click OPENAI "https://github.com/samanhappy/mcphub/blob/main/src/clients/openapi.ts"

    %% Click Events for Database
    click DB "https://github.com/samanhappy/mcphub/blob/main/src/db/entities/VectorEmbedding.ts"
    click DB "https://github.com/samanhappy/mcphub/blob/main/src/db/repositories/VectorEmbeddingRepository.ts"
    click DB "https://github.com/samanhappy/mcphub/blob/main/src/db/repositories/BaseRepository.ts"
    click DB "https://github.com/samanhappy/mcphub/blob/main/src/db/subscribers/VectorEmbeddingSubscriber.ts"
    click DB "https://github.com/samanhappy/mcphub/blob/main/src/db/types/postgresVectorType.ts"

    %% Click Events for Backend Models and Utils
    click CTL "https://github.com/samanhappy/mcphub/blob/main/src/models/User.ts"
    click BIZ "https://github.com/samanhappy/mcphub/blob/main/src/utils/smartRouting.ts"

    %% Click Events for Deployment
    click NGINX "https://github.com/samanhappy/mcphub/blob/main/nginx.conf.example"
    click CLI "https://github.com/samanhappy/mcphub/tree/main/Dockerfile"
    click CLI "https://github.com/samanhappy/mcphub/blob/main/entrypoint.sh"
    click NGINX "https://github.com/samanhappy/mcphub/blob/main/.env.example"
    click NGINX "https://github.com/samanhappy/mcphub/blob/main/.github/workflows/build.yml"
    click NGINX "https://github.com/samanhappy/mcphub/blob/main/.github/workflows/ci.yml"
    click NGINX "https://github.com/samanhappy/mcphub/blob/main/.github/workflows/npm-publish.yml"
    click NGINX "https://github.com/samanhappy/mcphub/blob/main/.github/workflows/release.yml"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085;
    classDef api fill:#d4edda,stroke:#155724,color:#155724;
    classDef db fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef infra fill:#f8d7da,stroke:#721c24,color:#721c24;
```
