# 0gis0/chainlit-demo architecture

> Architecture diagram of the GitHub repository 0gis0/chainlit-demo, 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/0gis0/chainlit-demo
- Repository: https://github.com/0gis0/chainlit-demo

## Overview

##### Project Type and Purpose
- This is a container-based demo application combining a Python chat UI (Chainlit) with Azure OpenAI and external “Model Context Protocol” (MCP) servers.
- Purpose: let a developer spin up a local dev container, run a Chainlit chat app, wire in Azure OpenAI LLM calls, and dynamically attach MCP servers (e.g., a filesystem server) to enrich the model’s context.

##### Top-Level Components
- Dev Environment
- VSCode Dev Container (.devcontainer/devcontainer.json)
- Python runtime, Node.js runtime
- Chainlit Chat App
- app.py (entrypoint)
- .chainlit/ (CLI config & translation JSONs)
- requirements.txt
- Configuration
- .azure.env (sample in .azure.env-sample) – holds Azure OpenAI creds and endpoint
- External Services
- Azure OpenAI endpoint (cloud API)
- MCP Servers (Node.js microservices, e.g. @modelcontextprotocol/server-filesystem)
- File System Context
- Local workspace (/workspaces/chainlit-demo)
- poema.txt (example artifact)

##### Interactions & Data Flow
- Developer opens the repo in VSCode → launches Dev Container
- Inside container, runs `chainlit run app.py -w` → Chainlit server and web UI spin up
- User submits prompt in browser UI → Chainlit backend processes message
→ Chainlit calls Azure OpenAI REST API using credentials from `.azure.env`
- Responses from Azure and MCP servers merge back in Chainlit → rendered in UI
- E.g., writing a poem: Chainlit instructs filesystem MCP server to save output to poema.txt

##### Architectural Patterns & Principles
- Microservices for each MCP server (isolated Node.js processes)
- Containerized development environment (reproducible builds, no local installs)
- Plugin/extension model: Chainlit can dynamically load multiple MCP servers via simple CLI commands
- Clear separation of concerns: UI layer (Chainlit front), orchestrator layer (Chainlit backend), LLM service, context providers

##### Essentials to Capture
- Configuration files and environment variables

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer and Dev Container
    Developer["Developer"]:::devtools
    DevContainer["VSCode Dev Container"]:::devtools
    Developer -->|"opens repo"| DevContainer

    %% Inside Dev Container
    subgraph "Dev Container Environment"
        direction TB
        ChainlitUI["Chainlit UI (Browser)"]:::chainlit
        ChainlitBackend["Chainlit Backend"]:::chainlit
        ConfigEnv[".azure.env-sample"]:::devtools
        AppEntrypoint["app.py"]:::chainlit
        ChainlitConfig[".chainlit/config.toml"]:::chainlit
        Translations[".chainlit/translations/*.json"]:::chainlit
        Requirements["requirements.txt"]:::devtools
        Documentation["Docs: README.md, chainlit.md"]:::devtools

        ChainlitUI -->|"user input"| ChainlitBackend
        ChainlitBackend -->|"uses creds from .azure.env"| ConfigEnv
        ChainlitBackend -->|"runs"| AppEntrypoint
        ChainlitBackend -->|"loads config"| ChainlitConfig
        ChainlitBackend -->|"loads translations"| Translations
        AppEntrypoint -->|"installs deps"| Requirements
    end

    %% External Services
    AzureOpenAI["Azure OpenAI Service"]:::cloud
    MCPServer["MCP Server (Filesystem)"]:::microservice
    LocalFS["Local File System (poema.txt)"]:::storage

    ChainlitBackend -->|"REST API (HTTPS)"| AzureOpenAI
    ChainlitBackend -->|"HTTP (fetch context)"| MCPServer
    MCPServer -->|"reads/writes"| LocalFS

    %% Click Events
    click DevContainer "https://github.com/0gis0/chainlit-demo/blob/main/.devcontainer/devcontainer.json"
    click AppEntrypoint "https://github.com/0gis0/chainlit-demo/blob/main/app.py"
    click ChainlitConfig "https://github.com/0gis0/chainlit-demo/blob/main/.chainlit/config.toml"
    click Translations "https://github.com/0gis0/chainlit-demo/blob/main/.chainlit/translations/*.json"
    click Requirements "https://github.com/0gis0/chainlit-demo/blob/main/requirements.txt"
    click ConfigEnv "https://github.com/0gis0/chainlit-demo/blob/main/.azure.env-sample"
    click LocalFS "https://github.com/0gis0/chainlit-demo/blob/main/poema.txt"
    click Documentation "https://github.com/0gis0/chainlit-demo/blob/main/README.md"
    click Documentation "https://github.com/0gis0/chainlit-demo/blob/main/chainlit.md"

    %% Styling
    classDef devtools fill:#D0E8FF,stroke:#0366D6,stroke-width:1px;
    classDef chainlit fill:#FFF4C1,stroke:#D4A017,stroke-width:1px;
    classDef cloud fill:#DFFFE0,stroke:#228B22,stroke-width:1px;
    classDef microservice fill:#FFE4B5,stroke:#FF8C00,stroke-width:1px;
    classDef storage fill:#E0E0E0,stroke:#808080,stroke-width:1px;
```
