# sungminna/mcp_poc architecture

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

- Interactive diagram: https://gitdiagram.com/sungminna/mcp_poc
- Repository: https://github.com/sungminna/mcp_poc

## Overview

##### Project Type & Purpose
- Full-stack, retrieval-augmented chatbot platform.
- Three main deliverables:
- Core AI library (“lucia”) for extraction, embedding, storage, pipelines.
- FastAPI backend service (“react_mcp”) exposing REST API, orchestrating chat, RAG, tool servers.
- SvelteKit frontend (“velt”) for chat UI.
- Ancillary Django-style app (“lucia_backend”) for admin/user management (legacy or separate deployment).

##### File-Structure Analysis
- Top-level:
- docker-compose.yml, nginx.conf → deployment config
- lucia/ → Python core library (LLM clients, extractors, stores, vectorstores, pipelines)
- react_mcp/ → FastAPI app (main.py, routers/, services/, crud/, models/)
- lucia_backend/ → Django-style project (manage.py, chat_manager/, user_manager/)
- velt/ → SvelteKit frontend (src/, build/, .svelte-kit/)
- Key patterns:
- “lucia” core is a plugin-style package used by backend.
- “react_mcp” uses layered structure: routers → services → persistence.
- External tool servers (weather_server.py, math_server.py) co-hosted.
- Datastores & config:
- PostgreSQL (asyncpg + SQLAlchemy)
- Neo4j graph (neo4j-driver)
- Milvus vector store (pymilvus)
- Redis cache (aioredis)
- JWT, rate limiting, logging, Langfuse tracing

##### README Insights
- Startup sequence: migrations + DB/graph/vectorstore initialization.
- User flow: signup/login → PostgreSQL + Neo4j.
- Chat flow: extract → Neo4j persist → embed (Redis cache → Milvus) → graph & vector search → REACT agent → return & save to PostgreSQL.
- Asynchronous, scalable, modular.

- Frontend (velt SvelteKit)
- API Gateway / Nginx
- Backend microservices:
– FastAPI “react_mcp”
– Django “lucia_backend” (admin/user)
- Core library “lucia” (depicted as a shared module)
- External tool servers (Weather, Math)
- External APIs (OpenAI, LangGraph/LangChain)
- Datastores: PostgreSQL, Neo4j, Milvus, Redis
- Message broker / optional queue (if used)
- User ↔ Frontend
- Frontend → API (JWT, CORS) via Nginx
- API → Authentication & Rate-Limit
- FastAPI:
– CRUD → PostgreSQL
– Graph operations → Neo4j
– Embeddings → OpenAI → Redis cache → Milvus
– Vector search → Milvus
– Prompt orchestration → LangChain/REACT → returns content
– Tool calls → Weather/math servers
- Django backend → PostgreSQL + Neo4j for admin
c. Architectural Patterns:
- Layered (routers → services → persistence)
- Plugin/Factory (lucia’s pluggable extractors, clients, stores)
- RAG pipeline (LLM + vector + graph)
- Microservices (distinct FastAPI & Django roles)
d. Key Technologies:
- FastAPI, Uvicorn, async SQLAlchemy, aioredis
- Neo4j-driver, pymilvus, OpenAI SDK
- SvelteKit, Vite
- JWT (python-jose), bcrypt, slowapi
- Docker, Docker-Compose, Nginx

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlanes
    subgraph "User Layer"
        direction TB
        User["User"]:::user
    end

    subgraph "API Gateway / Frontend"
        direction TB
        Frontend["SvelteKit Frontend (velt)"]:::frontend
        API_Gateway["Nginx / API Gateway"]:::gateway
    end

    subgraph "Backend Services"
        direction TB
        subgraph "FastAPI Service" 
            direction TB
            ReactMCP["react_mcp (FastAPI)"]:::backend
            Routers["Routers"]:::backend
            Services["Services"]:::backend
            Persistence["Persistence / CRUD"]:::backend
            CoreSec["Core & Security"]:::backend
            DBCache["Database & Cache Integration"]:::backend
            ToolServers["Tool Servers (Weather, Math)"]:::backend
        end
        subgraph "Django Service"
            direction TB
            LuciaBackend["lucia_backend (Django)"]:::backend
            AdminViews["Chat/User Views"]:::backend
        end
    end

    subgraph "Core Library"
        direction TB
        LuciaCore["lucia Core"]:::core
        subgraph "Clients"
            direction TB
            LLMClient["LLM Clients"]:::core
            EmbeddingClient["Embedding Clients"]:::core
        end
        subgraph "Extractors"
            direction TB
            OpenAIExt["OpenAI Extractors"]:::core
            NoOpExt["NoOp Extractor"]:::core
        end
        subgraph "Pipelines"
            direction TB
            Factory["Pipeline Factory"]:::core
            KnowledgePipe["Knowledge Pipeline"]:::core
            SearchPipe["Search Pipeline"]:::core
        end
        subgraph "Stores"
            direction TB
            Neo4jStore["Neo4j InfoStore"]:::core
            ClickHouseStore["ClickHouse InfoStore"]:::core
        end
        VectorStore["Milvus VectorStore"]:::core
        Agent["REACT Agent"]:::core
    end

    subgraph "Datastores"
        direction TB
        Postgres["PostgreSQL"]:::storage
        Neo4jDB["Neo4j"]:::storage
        Milvus["Milvus"]:::storage
        Redis["Redis Cache"]:::storage
    end

    subgraph "External APIs"
        direction TB
        OpenAI["OpenAI API"]:::external
        LangChain["LangChain / LangGraph"]:::external
    end

    %% Connections
    User -->|"HTTP/WS"| Frontend
    Frontend -->|"REST (JWT, CORS)"| API_Gateway
    API_Gateway -->|"Proxy"| ReactMCP

    %% FastAPI internals
    ReactMCP --> Routers
    Routers --> Services
    Services --> Persistence
    Services --> DBCache
    Services --> ToolServers

    ReactMCP --> CoreSec
    ReactMCP --> LucaCoreCall["Core Library Calls"]:::link
    CoreSec --> Persistence

    %% Lucia core interactions
    LucaCoreCall --> LuciaCore
    LuciaCore --> LLMClient
    LLMClient --> OpenAI
    LuciaCore --> EmbeddingClient
    EmbeddingClient --> OpenAI
    LuciaCore --> OpenAIExt
    LuciaCore --> NoOpExt
    LuciaCore --> Factory
    Factory --> KnowledgePipe
    Factory --> SearchPipe
    LuciaCore --> Neo4jStore
    LuciaCore --> ClickHouseStore
    LuciaCore --> VectorStore
    LuciaCore --> Agent

    %% Datastore flows
    Persistence -->|"SQLAlchemy"| Postgres
    Persistence -->|"Bolt"| Neo4jDB
    DBCache -->|"Redis"| Redis
    DBCache -->|"Milvus Client"| Milvus
    SearchPipe --> Milvus
    KnowledgePipe --> Neo4jDB
    Agent -->|"LLM Orchestration"| LangChain

    %% Tool servers
    ToolServers -->|"HTTP"| WeatherServer["Weather Server"]:::external
    ToolServers -->|"HTTP"| MathServer["Math Server"]:::external

    %% Django service
    API_Gateway -->|"Admin API"| LuciaBackend
    LuciaBackend --> AdminViews
    AdminViews --> Postgres
    AdminViews --> Neo4jDB

    %% User flow return
    ReactMCP -->|"Response"| Frontend
    Frontend --> User

    %% Click events
    click LuciaCore "https://github.com/sungminna/mcp_poc/tree/main/lucia/src/delos_lucia"
    click Agent "https://github.com/sungminna/mcp_poc/blob/main/lucia/src/delos_lucia/agents/chitchat.py"
    click LLMClient "https://github.com/sungminna/mcp_poc/blob/main/lucia/src/delos_lucia/clients/llm_client.py"
    click EmbeddingClient "https://github.com/sungminna/mcp_poc/blob/main/lucia/src/delos_lucia/embeddings/openai_embedding_client.py"
    click OpenAIExt "https://github.com/sungminna/mcp_poc/blob/main/lucia/src/delos_lucia/extractors/openai_extractors.py"
    click NoOpExt "https://github.com/sungminna/mcp_poc/blob/main/lucia/src/delos_lucia/extractors/noop_extractor.py"
    click Factory "https://github.com/sungminna/mcp_poc/blob/main/lucia/src/delos_lucia/pipeline_factory.py"
    click KnowledgePipe "https://github.com/sungminna/mcp_poc/blob/main/lucia/src/delos_lucia/pipelines/knowledge_pipeline.py"
    click SearchPipe "https://github.com/sungminna/mcp_poc/blob/main/lucia/src/delos_lucia/pipelines/search_pipeline.py"
    click Neo4jStore "https://github.com/sungminna/mcp_poc/blob/main/lucia/src/delos_lucia/stores/info_store_neo4j.py"
    click ClickHouseStore "https://github.com/sungminna/mcp_poc/blob/main/lucia/src/delos_lucia/stores/info_store_clickhouse.py"
    click VectorStore "https://github.com/sungminna/mcp_poc/blob/main/lucia/src/delos_lucia/vectorstores/milvus_vector_store.py"
    click ReactMCP "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/main.py"
    click Routers "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/routers/ask.py"
    click Routers "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/routers/auth.py"
    click Routers "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/routers/prompts.py"
    click Routers "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/routers/users.py"
    click Routers "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/routers/general.py"
    click Services "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/services/chat_service.py"
    click Services "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/services/llm_service.py"
    click Services "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/services/neo4j_service.py"
    click Services "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/services/milvus_service.py"
    click Persistence "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/crud/chat.py"
    click Persistence "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/crud/user.py"
    click CoreSec "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/core/config.py"
    click CoreSec "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/core/security.py"
    click CoreSec "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/core/depends.py"
    click DBCache "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/database.py"
    click ToolServers "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/weather_server.py"
    click ToolServers "https://github.com/sungminna/mcp_poc/blob/main/react_mcp/math_server.py"
    click LuciaBackend "https://github.com/sungminna/mcp_poc/blob/main/lucia_backend/config/config/settings.py"
    click AdminViews "https://github.com/sungminna/mcp_poc/blob/main/lucia_backend/chat_manager/views.py"
    click AdminViews "https://github.com/sungminna/mcp_poc/blob/main/lucia_backend/user_manager/views.py"
    click Frontend "https://github.com/sungminna/mcp_poc/blob/main/velt/src/routes/+page.svelte"
    click Frontend "https://github.com/sungminna/mcp_poc/blob/main/velt/src/routes/login/+page.svelte"
    click Frontend "https://github.com/sungminna/mcp_poc/blob/main/velt/src/routes/signup/+page.svelte"
    click Frontend "https://github.com/sungminna/mcp_poc/blob/main/velt/src/lib/components/ChatMessage.svelte"
    click Frontend "https://github.com/sungminna/mcp_poc/blob/main/velt/src/lib/components/IconSend.svelte"
    click dockerCompose "https://github.com/sungminna/mcp_poc/blob/main/docker-compose.yml"
    click nginxConfig "https://github.com/sungminna/mcp_poc/blob/main/nginx.conf"

    %% Styles
    classDef user fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef frontend fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef gateway fill:#B3D7FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef core fill:#E5D0FF,stroke:#333,stroke-width:1px
    classDef storage fill:#FFE5B3,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef link stroke-dasharray: 2 2,stroke:#999,fill:none
```
