# debabratamishra/litemind-ui architecture

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

- Interactive diagram: https://gitdiagram.com/debabratamishra/litemind-ui
- Repository: https://github.com/debabratamishra/litemind-ui

## Overview

##### Project Type and Purpose
- LiteMindUI is a full-stack web application providing a hybrid LLM interface:
- Streamlit frontend (at localhost:8501) for interactive UI
- FastAPI backend (at localhost:8000) for REST + streaming API endpoints
- Modular Python services for RAG, embeddings, Ollama & Hugging Face (vLLM) integration
- Document ingestion pipeline (PDF/DOCX/TXT → extractor → vector store)

##### Main Components
a. Frontend Layer (Streamlit)
- Entrypoint: `streamlit_app.py`
- UI modules under `app/frontend`: pages, components (streaming handler, text renderer, voice input), services (chat_service, rag_service, backend_service)
b. API Layer (FastAPI)
- Entrypoint: `main.py`
- Routers under `app/backend/api`: chat.py, rag.py, health.py, models.py
- Core logic under `app/backend/core`: config, embeddings, CORS, health checks
- Pydantic models under `app/backend/models`
c. Service Layer
- app/services:
- host_service_manager.py (auto-failover between Ollama & vLLM)
- ollama.py (local LLM)
- vllm_service.py (Hugging Face)
- rag_service.py (vector search + retrieval)
- speech_service.py (optional voice I/O)
d. Ingestion Pipeline
- app/ingestion: file_ingest.py, enhanced_extractors.py, enhanced_document_processor.py
- Takes uploaded docs → extracts text → generates embeddings → stores in Chroma (uploads/chroma_db)
e. Persistence & External
- File storage: `/uploads` directory
- Vector DB: Chroma on disk
- External LLM endpoints: Ollama API (http://localhost:11434), Hugging Face (via vLLM)

##### Relationships & Data Flows
1. User interacts in browser → Streamlit frontend UI
2. Frontend invokes backend via HTTP (REST or streaming)
3. FastAPI routes request to appropriate API module
4. API handler calls Service Layer (chat, rag, embeddings)
5. Service Layer may:
– Hit local Ollama API or vLLM (external)
– Perform vector search on local Chroma DB
– Call ingestion pipeline for new uploads
6. Response (possibly streaming tokens) flows back through API to frontend
7. Frontend renders responses in real time

##### Architectural Patterns & Principles
- Layered separation: UI / API / Services / Persistence
- Modular “service” classes for extensibility
- Auto-failover manager for backend switching
- Async, non-blocking I/O in FastAPI for high throughput
- Containerized micro-services in Docker Compose (one container each for backend & frontend)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & Browser
    U["User"]:::external
    U -->|"interacts"| FE_ENTRY

    %% Frontend Layer
    subgraph "Streamlit Frontend" 
        direction TB
        FE_ENTRY["streamlit_app.py"]:::frontend
        FE_CONFIG["config.py"]:::frontend
        subgraph "Pages"
            direction TB
            FE_PAGE_CHAT["chat_page.py"]:::frontend
            FE_PAGE_RAG["rag_page.py"]:::frontend
        end
        subgraph "Components"
            direction TB
            FE_COMP_STREAM["streaming_handler.py"]:::frontend
            FE_COMP_TEXT["text_renderer.py"]:::frontend
            FE_COMP_VOICE["voice_input.py"]:::frontend
            FE_COMP_VLLM["vllm_config.py"]:::frontend
        end
        subgraph "Services (UI)"
            direction TB
            FE_SVC_BACKEND["backend_service.py"]:::frontend
            FE_SVC_CHAT["chat_service.py"]:::frontend
            FE_SVC_RAG["rag_service.py"]:::frontend
        end
        subgraph "Utilities"
            direction TB
            FE_UTIL_AUDIO["audio_recorder.py"]:::frontend
            FE_UTIL_TEXT["text_processing.py"]:::frontend
            FE_UTIL_CLEAN["text_processing_clean.py"]:::frontend
        end
    end

    %% Frontend to Backend
    FE_ENTRY -->|"POST /api/chat, /api/rag"| BE_ENTRY

    %% API Layer
    subgraph "FastAPI Backend"
        direction TB
        BE_ENTRY["main.py"]:::api
        subgraph "Routers"
            direction TB
            BE_ROUTER_CHAT["chat.py"]:::api
            BE_ROUTER_RAG["rag.py"]:::api
            BE_ROUTER_HEALTH["health.py"]:::api
            BE_ROUTER_MODELS["models.py"]:::api
        end
        subgraph "Core Modules"
            direction TB
            BE_CORE_CONFIG["config.py"]:::api
            BE_CORE_EMBED["embeddings.py"]:::api
            BE_CORE_CORS["CORS & Health"]:::api
        end
        BE_MODELS["api_models.py"]:::api
    end

    %% Backend to Services
    BE_ROUTER_CHAT -->|"calls chat_service"| SVC_HOST
    BE_ROUTER_RAG -->|"calls rag_service"| SVC_RAG
    BE_CORE_EMBED -->|"generates embeddings"| SVC_VLLM

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        SVC_HOST["host_service_manager.py"]:::service
        SVC_OLLAMA["ollama.py"]:::service
        SVC_VLLM["vllm_service.py"]:::service
        SVC_RAG["rag_service.py"]:::service
        SVC_SPEECH["speech_service.py"]:::service
    end

    %% Services to Persistence & External
    SVC_HOST -->|"HTTP|RPC"| EX_OLLAMA
    SVC_VLLM -->|"HTTP"| EX_VLLM
    SVC_RAG -->|"vector search"| DB_CHROMA
    SVC_SPEECH -->|"I/O"| FE_ENTRY

    %% Ingestion Pipeline
    subgraph "Ingestion Pipeline"
        direction TB
        INGEST_FILE["file_ingest.py"]:::pipeline
        INGEST_EXT["enhanced_extractors.py"]:::pipeline
        INGEST_PROC["enhanced_document_processor.py"]:::pipeline
    end
    INGEST_PROC -->|"stores embeddings"| DB_CHROMA
    INGEST_FILE --> INGEST_EXT --> INGEST_PROC

    %% Persistence & External
    subgraph "Persistence & External"
        direction TB
        UPLOADS["/uploads"]:::storage
        DB_CHROMA["Chroma DB"]:::storage
        EX_OLLAMA["Ollama API"]:::external
        EX_VLLM["Hugging Face (vLLM)"]:::external
    end

    %% Deployment & Config
    subgraph "Environment & Deployment"
        direction TB
        ENV_EX[".env.example"]:::config
        GLOBAL_CFG["config.py"]:::config
        STREAM_CFG[".streamlit/config.toml"]:::config
        DOCKER_FE["Dockerfile.streamlit"]:::config
        DOCKER_BE["Dockerfile"]:::config
        DOCKER_COMP["docker-compose*.yml"]:::config
    end

    %% Click Events
    click FE_ENTRY "https://github.com/debabratamishra/litemind-ui/blob/main/streamlit_app.py"
    click FE_CONFIG "https://github.com/debabratamishra/litemind-ui/blob/main/app/frontend/config.py"
    click FE_PAGE_CHAT "https://github.com/debabratamishra/litemind-ui/blob/main/app/frontend/pages/chat_page.py"
    click FE_PAGE_RAG "https://github.com/debabratamishra/litemind-ui/blob/main/app/frontend/pages/rag_page.py"
    click FE_COMP_STREAM "https://github.com/debabratamishra/litemind-ui/blob/main/app/frontend/components/streaming_handler.py"
    click FE_COMP_TEXT "https://github.com/debabratamishra/litemind-ui/blob/main/app/frontend/components/text_renderer.py"
    click FE_COMP_VOICE "https://github.com/debabratamishra/litemind-ui/blob/main/app/frontend/components/voice_input.py"
    click FE_COMP_VLLM "https://github.com/debabratamishra/litemind-ui/blob/main/app/frontend/components/vllm_config.py"
    click FE_SVC_BACKEND "https://github.com/debabratamishra/litemind-ui/blob/main/app/frontend/services/backend_service.py"
    click FE_SVC_CHAT "https://github.com/debabratamishra/litemind-ui/blob/main/app/frontend/services/chat_service.py"
    click FE_SVC_RAG "https://github.com/debabratamishra/litemind-ui/blob/main/app/frontend/services/rag_service.py"
    click FE_UTIL_AUDIO "https://github.com/debabratamishra/litemind-ui/blob/main/app/frontend/utils/audio_recorder.py"
    click FE_UTIL_TEXT "https://github.com/debabratamishra/litemind-ui/blob/main/app/frontend/utils/text_processing.py"
    click FE_UTIL_CLEAN "https://github.com/debabratamishra/litemind-ui/blob/main/app/frontend/utils/text_processing_clean.py"
    click BE_ENTRY "https://github.com/debabratamishra/litemind-ui/blob/main/main.py"
    click BE_ROUTER_CHAT "https://github.com/debabratamishra/litemind-ui/blob/main/app/backend/api/chat.py"
    click BE_ROUTER_RAG "https://github.com/debabratamishra/litemind-ui/blob/main/app/backend/api/rag.py"
    click BE_ROUTER_HEALTH "https://github.com/debabratamishra/litemind-ui/blob/main/app/backend/api/health.py"
    click BE_ROUTER_MODELS "https://github.com/debabratamishra/litemind-ui/blob/main/app/backend/api/models.py"
    click BE_CORE_CONFIG "https://github.com/debabratamishra/litemind-ui/blob/main/app/backend/core/config.py"
    click BE_CORE_EMBED "https://github.com/debabratamishra/litemind-ui/blob/main/app/backend/core/embeddings.py"
    click BE_MODELS "https://github.com/debabratamishra/litemind-ui/blob/main/app/backend/models/api_models.py"
    click SVC_HOST "https://github.com/debabratamishra/litemind-ui/blob/main/app/services/host_service_manager.py"
    click SVC_OLLAMA "https://github.com/debabratamishra/litemind-ui/blob/main/app/services/ollama.py"
    click SVC_VLLM "https://github.com/debabratamishra/litemind-ui/blob/main/app/services/vllm_service.py"
    click SVC_RAG "https://github.com/debabratamishra/litemind-ui/blob/main/app/services/rag_service.py"
    click SVC_SPEECH "https://github.com/debabratamishra/litemind-ui/blob/main/app/services/speech_service.py"
    click INGEST_FILE "https://github.com/debabratamishra/litemind-ui/blob/main/app/ingestion/file_ingest.py"
    click INGEST_EXT "https://github.com/debabratamishra/litemind-ui/blob/main/app/ingestion/enhanced_extractors.py"
    click INGEST_PROC "https://github.com/debabratamishra/litemind-ui/blob/main/app/ingestion/enhanced_document_processor.py"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#42A5F5,color:#0D47A1;
    classDef api fill:#E8F5E9,stroke:#66BB6A,color:#1B5E20;
    classDef service fill:#FFF9C4,stroke:#FFEE58,color:#F57F17;
    classDef storage fill:#ECEFF1,stroke:#90A4AE,color:#37474F;
    classDef external fill:#F3E5F5,stroke:#AB47BC,color:#4A148C;
    classDef pipeline fill:#FFF3E0,stroke:#FFA726,color:#E65100;
    classDef config fill:#E0F7FA,stroke:#26C6DA,color:#006064;
```
