# 1amibrahim/doc-rag architecture

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

- Interactive diagram: https://gitdiagram.com/1amibrahim/doc-rag
- Repository: https://github.com/1amibrahim/doc-rag

## Overview

##### Project Type & Purpose
- This is a full-stack Python web application plus accompanying libraries for building Retrieval-Augmented Generation (RAG) pipelines.
- End-users interact with a Gradio-based UI to chat with their documents; developers import the `kotaemon` and `ktem` libraries to customize or embed RAG pipelines in their own projects.

##### High-Level File‐Structure Analysis
- Root files: `app.py`, `st_app.py`, `sso_app.py` → entrypoints for different deployment modes (Gradio, Streamlit, SSO demo).
- `libs/kotaemon`: core RAG SDK → agents, loaders, embeddings, indices, llm wrappers, pipelines, storage adapters, CLI and contribs.
- `libs/ktem`: application framework → database models, Streamlit pages, UI components, embeddings manager, indexing manager, migrations.
- `docs`, `templates`, `scripts` and CI/CD config → documentation site (MkDocs), project/ component templates, helper scripts, Dockerfile, GitHub Actions.

##### Key Architectural Insights from README
- Layered RAG pipeline:
- Document loading & parsing → vector + full-text indexing → hybrid retrieval → optional re-ranking → reasoning (agents, question decomposition) → final LLM generation with citations.
- Supports multiple providers: OpenAI/Azure, local LLMs (`ollama`, `llama-cpp-python`), multiple vector stores (Chroma, LanceDB, Milvus, Qdrant), full-text stores (Elasticsearch, SimpleFile).
- UI built on Gradio theming, with settings pages for collections, LLM/embeddings, pipelines, user management.

##### Main Components & Interactions
- Presentation Layer
– Browser UI (Gradio) served by `app.py` → chat tab, settings, resources, PDF viewer.
- Application Server
– Gradio app instance orchestrating requests.
– Auth & multi-user management via `ktem` database models (SQL via Alembic/migrations).
- RAG Pipeline Core (`kotaemon`)
– Loaders (PDF, HTML, Excel, OCR) → extract text + metadata.
– Indexers & Splitters → full-text indexing and chunking.
– Vectorization (embedding models).
– Document store adapters & Vector store adapters.
– Retriever (hybrid full-text + vector), Reranker, QA pipelines, Agent frameworks (ReAct, ReWOO).
- Model Providers
– External LLM/embedding APIs (OpenAI, Azure) or local servers (Ollama, llama-cpp).
- Data Storage
– Persistent relational DB (user accounts, model configs).
– Full-text store (Elasticsearch or file).
– Vector store (Chroma, LanceDB, etc.).
– Application data folder (`ktem_app_data` for user uploads, logs).
- Infrastructure & Ops
– Docker image variants (lite, full, ollama).
– CI/CD pipelines (GitHub Actions).
– Scripts for setup, migrations, local servers.

##### Architectural Patterns & Principles
- Layered architecture (UI → orchestration → pipeline → model → storage).
- Plugin-style extensibility: components (loaders, indexers, llms, agents) follow base interfaces+ registration.
- Dependency injection via `flowsettings.py` and `.env`.
- Separation of concerns: `kotaemon` core for pipelines, `ktem` for app/UI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["Browser UI (Gradio)"]:::presentation
        StreamlitUI["Streamlit UI"]:::presentation
        SSOUI["SSO Demo UI"]:::presentation
    end

    %% Application Framework (ktem)
    subgraph "Application & Framework (ktem)"
        direction TB
        CoreApp["Core App Server & Entrypoints"]:::orchestration
        StreamlitApp["Streamlit App Server"]:::orchestration
        DBModels["Database Engine & Models"]:::orchestration
        EmbManager["Embeddings Manager & UI"]:::orchestration
        IndexManager["Index Manager & UI"]:::orchestration
        ChatPanel["Streamlit Pages & Chat Panel"]:::orchestration
        SettingsPages["Settings & User Management Pages"]:::orchestration
        ReasoningUI["Reasoning Engines (ReAct/ReWOO)"]:::orchestration
        RerankUI["Reranking UI & Manager"]:::orchestration
    end

    %% RAG Pipeline Core (kotaemon)
    subgraph "Pipeline Core (kotaemon SDK)"
        direction TB
        Agents["Agents Framework"]:::core
        Loaders["Document Loaders & Parsers"]:::core
        Indexers["Indexers & Splitters"]:::core
        Embeddings["Embedding Models & Vectorization"]:::core
        LLMWrappers["LLM Wrappers & Chats"]:::core
        RerankCore["Reranking Modules"]:::core
        VectorStores["Storage Adapters – Vector Stores"]:::core
        DocStores["Storage Adapters – Document Stores"]:::core
    end

    %% Storage Layer
    subgraph "Storage Layer"
        direction TB
        AuthDB["Auth & Config DB"]:::storage
        DocStore["Document Store (Elasticsearch/File)"]:::storage
        VecStore["Vector Store (Chroma/LanceDB/Milvus/Qdrant)"]:::storage
        AppData["App Data Folder"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMProviders["LLM/Embedding Providers"]:::external
        PDFViewer["PDF Viewer Assets"]:::external
    end

    %% Infrastructure & Ops
    subgraph "Infrastructure & Ops"
        direction TB
        DockerCI["Docker & CI/CD Configurations"]:::infra
        Docs["Documentation (MkDocs)"]:::infra
        Templates["Project Templates"]:::infra
        Scripts["Helper Scripts & Local Servers"]:::infra
        Migrations["Persistent Storage Migrations"]:::infra
    end

    %% Relationships
    Browser -->|"HTTP" | CoreApp
    StreamlitUI --> CoreApp
    SSOUI --> CoreApp
    CoreApp -->|reads/writes| AuthDB
    CoreApp --> ChatPanel
    CoreApp --> SettingsPages
    CoreApp --> EmbManager
    CoreApp --> IndexManager
    CoreApp --> ReasoningUI
    CoreApp --> RerankUI

    CoreApp --> PipelineOrch
    subgraph invisible
        PipelineOrch["Pipeline Orchestrator"]:::orchestration
    end
    PipelineOrch --> Loaders
    Loaders --> DocStores
    Loaders --> VectorStores
    DocStores --> DocStore
    VectorStores --> VecStore

    PipelineOrch --> Indexers
    Indexers --> DocStores
    Indexers --> VectorStores

    PipelineOrch --> Embeddings
    Embeddings --> LLMProviders

    PipelineOrch --> RerankCore
    RerankCore --> Indexers

    PipelineOrch --> Agents
    Agents --> LLMWrappers
    LLMWrappers --> LLMProviders

    Agents -->|"cited assets"| PDFViewer
    PDFViewer --> Browser

    %% Click Events
    click Browser "https://github.com/1amibrahim/doc-rag/blob/master/app.py"
    click StreamlitUI "https://github.com/1amibrahim/doc-rag/blob/master/st_app.py"
    click SSOUI "https://github.com/1amibrahim/doc-rag/blob/master/sso_app.py"
    click Agents "https://github.com/1amibrahim/doc-rag/tree/master/libs/kotaemon/kotaemon/agents"
    click Loaders "https://github.com/1amibrahim/doc-rag/tree/master/libs/kotaemon/kotaemon/loaders"
    click Indexers "https://github.com/1amibrahim/doc-rag/tree/master/libs/kotaemon/kotaemon/indices"
    click Embeddings "https://github.com/1amibrahim/doc-rag/tree/master/libs/kotaemon/kotaemon/embeddings"
    click LLMWrappers "https://github.com/1amibrahim/doc-rag/tree/master/libs/kotaemon/kotaemon/llms"
    click RerankCore "https://github.com/1amibrahim/doc-rag/tree/master/libs/kotaemon/kotaemon/rerankings"
    click VectorStores "https://github.com/1amibrahim/doc-rag/tree/master/libs/kotaemon/kotaemon/storages/vectorstores"
    click DocStores "https://github.com/1amibrahim/doc-rag/tree/master/libs/kotaemon/kotaemon/storages/docstores"
    click CoreApp "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/app.py"
    click CoreApp "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/main.py"
    click StreamlitApp "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/streamlit_app.py"
    click StreamlitApp "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/streamlit_main.py"
    click DBModels "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/db/engine.py"
    click DBModels "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/db/models.py"
    click EmbManager "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/embeddings/manager.py"
    click EmbManager "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/embeddings/ui.py"
    click IndexManager "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/index/manager.py"
    click IndexManager "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/index/ui.py"
    click ChatPanel "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/pages/chat/chat_panel.py"
    click SettingsPages "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/pages/settings.py"
    click SettingsPages "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/pages/login.py"
    click ReasoningUI "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/reasoning/react.py"
    click ReasoningUI "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/reasoning/rewoo.py"
    click RerankUI "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/rerankings/manager.py"
    click RerankUI "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/rerankings/ui.py"
    click Migrations "https://github.com/1amibrahim/doc-rag/tree/master/libs/ktem/migrations"
    click PDFViewer "https://github.com/1amibrahim/doc-rag/blob/master/libs/ktem/ktem/assets/js/pdf_viewer.js"
    click Docs "https://github.com/1amibrahim/doc-rag/tree/master/docs/"
    click Templates "https://github.com/1amibrahim/doc-rag/tree/master/templates/"
    click DockerCI "https://github.com/1amibrahim/doc-rag/tree/master/Dockerfile"
    click DockerCI "https://github.com/1amibrahim/doc-rag/tree/master/.github/workflows/"
    click Scripts "https://github.com/1amibrahim/doc-rag/tree/master/scripts/"

    %% Styles
    classDef presentation fill:#D0E6FF,stroke:#00529B,stroke-width:2px
    classDef orchestration fill:#DFFFD0,stroke:#356D35,stroke-width:2px
    classDef core fill:#FFE6B3,stroke:#AA5500,stroke-width:2px
    classDef storage fill:#FFF7C0,stroke:#A67C00,stroke-width:2px
    classDef external fill:#FFD0D0,stroke:#8B0000,stroke-width:2px
    classDef infra fill:#E0E0E0,stroke:#4F4F4F,stroke-width:2px
```
