# kltsai/legal-rag-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/kltsai/legal-rag-chatbot
- Repository: https://github.com/kltsai/legal-rag-chatbot

## Overview

##### Project type and purpose
- This is a Python-based Retrieval-Augmented Generation (RAG) chatbot specialized for legal queries.
- It ingests raw legal conversation data, computes embeddings, stores them in a vector database, and at runtime retrieves relevant context to feed into an LLM (Gemini) to generate answers.

##### File structure
- Top-level entry points:
- main.py – orchestrates batch pipelines or interactive sessions
- app.py / legal-rag-chatbot.py – likely CLI or API wrappers
- Core package: src/legal_rag_chatbot/
- components/
– data_ingestion.py
– data_embedding.py
– vector_storage.py
– gemini_client.py
– rag_sys.py
- config/configuration.py
- constants/
- entity/
- logging/
- utils/common.py
- Artifacts folder holds sample datasets and precomputed embeddings.

##### README.md
- Project title only, but name implies “Legal-RAG-Chatbot.”

##### Main components & interactions
a. Entry point (main.py)
- Calls Configuration loader
- Instantiates service modules
- Triggers ingestion/embedding pipeline or starts interactive chat
b. DataIngestion
- Reads raw JSON (train.json, test.json, val.json)
- Produces Document entities
c. DataEmbedding
- Takes Document entities → computes vector embeddings
d. VectorStorage
- Upserts embeddings into vector DB (local or cloud)
- Executes similarity searches at query time
e. GeminiClient
- Wraps external LLM API calls (prompt + context → completion)
f. RagSys
- At runtime:
1. Accepts user query
2. Calls VectorStorage.query() to retrieve top-k docs
3. Builds prompt (using utils/common, constants, templates)
4. Calls GeminiClient.generate()
5. Returns answer

##### Architectural patterns & design principles
- Modular “service” pattern: each concern isolated in its own component
- Pipeline for offline data prep (Ingestion → Embedding → Storage)
- RAG design at runtime: Retrieval (VectorStorage) + Generation (GeminiClient)
- Dependency inversion: RagSys depends on abstract interfaces of storage & LLM

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestrator
    main["main.py"]:::service
    click main "https://github.com/kltsai/legal-rag-chatbot/blob/master/main.py"

    subgraph "Configuration"
        configLoader["Configuration Loader"]:::config
        click configLoader "https://github.com/kltsai/legal-rag-chatbot/blob/master/src/legal_rag_chatbot/config/configuration.py"
        configFile["config/config.yaml"]:::config
        click configFile "https://github.com/kltsai/legal-rag-chatbot/blob/master/config/config.yaml"
    end

    main -->|"load_config()"| configLoader
    configLoader --> main

    %% Ingestion Pipeline
    subgraph "Ingestion Pipeline"
        dataIngestion["DataIngestion"]:::service
        click dataIngestion "https://github.com/kltsai/legal-rag-chatbot/blob/master/src/legal_rag_chatbot/components/data_ingestion.py"
        dataEmbedding["DataEmbedding"]:::service
        click dataEmbedding "https://github.com/kltsai/legal-rag-chatbot/blob/master/src/legal_rag_chatbot/components/data_embedding.py"
        vectorStorageComp["VectorStorage"]:::service
        click vectorStorageComp "https://github.com/kltsai/legal-rag-chatbot/blob/master/src/legal_rag_chatbot/components/vector_storage.py"
        rawData["Raw Data"]:::datastore
        click rawData "https://github.com/kltsai/legal-rag-chatbot/tree/master/artifacts/data_ingestion/"
        embeddingArt["Embedding Data"]:::datastore
        click embeddingArt "https://github.com/kltsai/legal-rag-chatbot/tree/master/artifacts/data_embedding/"
    end

    main -->|"ingest_data()"| dataIngestion
    dataIngestion -->|"produce Documents"| rawData
    main -->|"compute_embeddings()"| dataEmbedding
    rawData --> dataEmbedding
    dataEmbedding -->|"upsert_embeddings()"| vectorStorageComp
    dataEmbedding --> embeddingArt

    %% Runtime Chat Pipeline
    subgraph "Runtime Chat Pipeline"
        app["CLI/API Wrapper"]:::service
        click app "https://github.com/kltsai/legal-rag-chatbot/blob/master/app.py"
        alt["Alternate CLI"]:::service
        click alt "https://github.com/kltsai/legal-rag-chatbot/blob/master/legal-rag-chatbot.py"
        ragSys["RAG System"]:::service
        click ragSys "https://github.com/kltsai/legal-rag-chatbot/blob/master/src/legal_rag_chatbot/components/rag_sys.py"
        geminiClient["GeminiClient"]:::service
        click geminiClient "https://github.com/kltsai/legal-rag-chatbot/blob/master/src/legal_rag_chatbot/components/gemini_client.py"
        vectorStorageComp
        externalGemini["Gemini API"]:::external
    end

    app -->|"handle_query()"| ragSys
    alt -->|"handle_query()"| ragSys
    ragSys -->|"query()"| vectorStorageComp
    vectorStorageComp -->|"return top-k docs"| ragSys
    ragSys -->|"generate()"| geminiClient
    geminiClient -->|"return answer"| ragSys
    geminiClient --> externalGemini

    %% Shared Modules
    constants["Constants"]:::config
    click constants "https://github.com/kltsai/legal-rag-chatbot/tree/master/src/legal_rag_chatbot/constants/"
    utils["Common Utils"]:::config
    click utils "https://github.com/kltsai/legal-rag-chatbot/blob/master/src/legal_rag_chatbot/utils/common.py"
    entity["Entities"]:::config
    click entity "https://github.com/kltsai/legal-rag-chatbot/tree/master/src/legal_rag_chatbot/entity/"
    loggingMod["Logging Setup"]:::config
    click loggingMod "https://github.com/kltsai/legal-rag-chatbot/tree/master/src/legal_rag_chatbot/logging/"

    %% Dependencies
    dataIngestion --> constants
    dataEmbedding --> constants
    ragSys --> constants
    ragSys --> utils
    dataIngestion --> loggingMod
    dataEmbedding --> loggingMod
    vectorStorageComp --> loggingMod
    ragSys --> loggingMod
    dataIngestion --> entity

    %% Data Store
    vectorStorageComp -->|"store/retrieve"| rawData

    %% Legend
    subgraph Legend
        direction LR
        S["Service Module"]:::service
        C["Config/Constants/Utils"]:::config
        D["Data Store"]:::datastore
        E["External API"]:::external
    end

    classDef service fill:#cde5f7,stroke:#333,stroke-width:1px
    classDef config fill:#d4f7c3,stroke:#333,stroke-width:1px
    classDef datastore fill:#f7e7c3,stroke:#333,stroke-width:1px
    classDef external fill:#f7d4c3,stroke:#333,stroke-width:1px
```
