# damieee/lightrag_experimental architecture

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

- Interactive diagram: https://gitdiagram.com/damieee/lightrag_experimental
- Repository: https://github.com/damieee/lightrag_experimental

## Overview

##### Project type and purpose
- This is a hybrid RAG (Retrieval-Augmented Generation) API service with a minimal Streamlit front-end for demo purposes.
- FastAPI provides REST endpoints for chat and document management; a local Pydantic-backed document store holds the chunks; external LLM calls (OpenAI-compatible) power the generation.

##### File structure
- Top-level:
- `api/` – FastAPI app, schemas, business services
- `main_app.py` / `streamlit_app.py` – entry points for CLI/demo and Streamlit UI
- helper scripts: `insert_pydantic_docs.py`, `super-basic-lightrag.py`
- Within `api/`:
- `app.py` defines routers (`/chat`, `/chat/stream`, `/docs/*`)
- `schemas/` holds Pydantic models for payload validation
- `services/` contains the core RAG logic and external-call adapters
- Config & deployment: `requirements.txt`, `api/requirements.txt`, `pyproject.toml`, `.env.example`, uvicorn lock file

##### README for additional insights
- The system combines naive RAG with graph-based relationship mapping – so there is a “hybrid” retrieval module.
- Endpoints do error handling via structured JSON.
- CORS is enabled (ready for a separate JS front‐end if desired).
- Streaming support for real-time chunked responses.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients"
        direction TB
        RESTClients["REST Clients\n(curl, Postman, JS UI)"]:::clients
        StreamlitUI["Streamlit Demo UI"]:::clients
        CLI_InsertDocs["CLI: Insert Docs"]:::clients
        CLI_RAGDemo["CLI: Super-basic RAG Demo"]:::clients
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIServer["FastAPI Server"]:::api
        HealthCheck["Health Check Endpoint"]:::api
        ChatRouter["Chat Router\nPOST /chat"]:::api
        StreamRouter["Chat Stream Router\nPOST /chat/stream"]:::api
        DocsRouter["Docs Router\nPOST /docs/*"]:::api
        SchemaChat["Pydantic Schemas\n(chat)"]:::schema
        SchemaDocs["Pydantic Schemas\n(docs)"]:::schema
    end

    %% Business Logic Layer
    subgraph "Business Logic" 
        direction TB
        RAGAgent["RAG Agent Orchestrator"]:::service
        LightRAG["LightRAG Core Service\n(chunk+graph)"]:::service
        PydanticService["Pydantic Doc Store Adapter"]:::service
        OpenAIAdapter["OpenAI-compatible LLM Adapter"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        LocalStore["Local Pydantic Document Store"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAIAPI["OpenAI API"]:::external
    end

    %% Deployment & Config
    subgraph "Deployment & Config"
        direction TB
        Env[".env.example"]:::config
        ReqRoot["requirements.txt\npyproject.toml"]:::config
        ReqAPI["api/requirements.txt\napi/pyproject.toml\napi/uv.lock"]:::config
    end

    %% Connections: Client to API
    RESTClients -->|"POST /chat"| ChatRouter
    RESTClients -->|"POST /chat/stream"| StreamRouter
    RESTClients -->|"POST /docs/*"| DocsRouter
    StreamlitUI -->|"HTTP /chat"| ChatRouter
    CLI_InsertDocs -->|"CLI call"| DocsRouter
    CLI_RAGDemo -->|"CLI call"| ChatRouter

    %% API internal flow
    ChatRouter -->|"Validate with chat schema"| SchemaChat
    StreamRouter -->|"Validate with chat schema"| SchemaChat
    DocsRouter -->|"Validate with docs schema"| SchemaDocs

    SchemaChat -->|"Dispatch to RAG Agent"| RAGAgent
    SchemaDocs -->|"Dispatch to Pydantic Service"| PydanticService

    %% Business logic flow
    RAGAgent -->|"Retrieve chunks"| LightRAG
    LightRAG -->|"Read/Write chunks"| LocalStore
    RAGAgent -->|"Call LLM"| OpenAIAdapter
    OpenAIAdapter -->|"HTTP request"| OpenAIAPI

    PydanticService -->|"Read/Write docs"| LocalStore

    %% Response flow
    RAGAgent -->|"Stream/Batch response"| ChatRouter
    PydanticService -->|"Response"| DocsRouter
    ChatRouter -->|"200/4xx/5xx JSON"| RESTClients
    DocsRouter -->|"200/4xx/5xx JSON"| RESTClients
    StreamRouter -->|"chunked stream"| RESTClients

    %% Click events
    click APIServer "https://github.com/damieee/lightrag_experimental/blob/main/api/app.py"
    click HealthCheck "https://github.com/damieee/lightrag_experimental/blob/main/api/hello.py"
    click ChatRouter "https://github.com/damieee/lightrag_experimental/blob/main/api/app.py"
    click DocsRouter "https://github.com/damieee/lightrag_experimental/blob/main/api/app.py"
    click SchemaChat "https://github.com/damieee/lightrag_experimental/blob/main/api/schemas/chat.py"
    click SchemaDocs "https://github.com/damieee/lightrag_experimental/blob/main/api/schemas/docs.py"
    click LightRAG "https://github.com/damieee/lightrag_experimental/blob/main/api/services/lightrag_service.py"
    click RAGAgent "https://github.com/damieee/lightrag_experimental/blob/main/api/services/rag_agent.py"
    click PydanticService "https://github.com/damieee/lightrag_experimental/blob/main/api/services/pydantic_ai_service.py"
    click OpenAIAdapter "https://github.com/damieee/lightrag_experimental/blob/main/api/services/my_openai_compatible_model.py"
    click CLI_InsertDocs "https://github.com/damieee/lightrag_experimental/blob/main/insert_pydantic_docs.py"
    click CLI_RAGDemo "https://github.com/damieee/lightrag_experimental/blob/main/super-basic-lightrag.py"
    click StreamlitUI "https://github.com/damieee/lightrag_experimental/blob/main/streamlit_app.py"
    click Env "https://github.com/damieee/lightrag_experimental/blob/main/.env.example"
    click ReqRoot "https://github.com/damieee/lightrag_experimental/blob/main/requirements.txt"
    click ReqRoot "https://github.com/damieee/lightrag_experimental/blob/main/pyproject.toml"
    click ReqAPI "https://github.com/damieee/lightrag_experimental/blob/main/api/requirements.txt"
    click ReqAPI "https://github.com/damieee/lightrag_experimental/blob/main/api/pyproject.toml"
    click ReqAPI "https://github.com/damieee/lightrag_experimental/blob/main/api/uv.lock"

    %% Styles
    classDef clients fill:#DDDDDD,stroke:#888,stroke-width:1px
    classDef api fill:#D0E8FF,stroke:#339,stroke-width:1px
    classDef schema fill:#E8F4FF,stroke:#339,stroke-width:1px
    classDef service fill:#DFF2BF,stroke:#4F8A10,stroke-width:1px
    classDef data fill:#FEEFB3,stroke:#9F6000,stroke-width:1px
    classDef external fill:#F4DFFF,stroke:#7D26CD,stroke-width:1px
    classDef config fill:#EFEFEF,stroke:#999,stroke-width:1px
```
