# sridharmalladi/raglens architecture

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

- Interactive diagram: https://gitdiagram.com/sridharmalladi/raglens
- Repository: https://github.com/sridharmalladi/raglens

## Overview

1. **What this repo is**
   - RAGLens is a **live retrieval-augmented generation benchmarking app**.
   - Its main purpose is to run the same query across **four retrieval configurations** and compare answers and LLM-as-judge scores side by side:
     - No RAG
     - Dense RAG
     - Hybrid RAG
     - Hybrid + reranking

2. **Top-level runtime shape**
   - The app is served from **`main.py`**, with the README showing it is launched with **Uvicorn** on port **7860**.
   - The repo is packaged for **Docker / HF Spaces**, so the deployed unit is a single container exposing both backend logic and the web UI.

3. **Frontend boundary**
   - `static/index.html`, `static/app.js`, and `static/styles.css` are the client-side presentation layer.
   - This front end is likely thin: it renders the comparison dashboard and calls backend endpoints for generation, retrieval, and monitoring data.
   - The architecture boundary is clear: **static UI in `static/`**, Python orchestration and ML logic in `src/`.

4. **Backend orchestration layer**
   - `src/` contains the core application subsystems:
     - `inference.py` for LLM calls and answer generation
     - `retrieval.py` for the retrieval strategies
     - `evaluation.py` for scoring/benchmarking
     - `monitoring.py` for time-based stats and dashboard data
     - `scheduler.py` for periodic jobs
     - `storage.py` for persistence
     - `corpus.py` for corpus loading/chunk handling
     - `models.py` for shared data structures/config objects
   - This looks like a **service-oriented Python backend**, where the request path composes retrieval, generation, evaluation, and storage.

5. **Retrieval subsystem**
   - The README defines the retrieval stack as:
     - **Dense retrieval** using **BGE embeddings** and **FAISS**
     - **Sparse retrieval** using **BM25**
     - **Hybrid retrieval** combining both
     - **Reranking** using a **BGE cross-encoder**
   - The main architectural distinction is that the retrieval layer is not a single index; it is a **strategy switchboard** that can execute multiple pipelines for comparison.

6. **Generation + judge evaluation**
   - Answer generation uses **Groq llama-3.1-8b-instant**.
   - Evaluation is separate from generation and uses **LLM-as-judge** scoring for:
     - faithfulness
     - relevancy
     - precision
   - This means the system has two LLM-facing flows:
     - one for producing candidate answers
     - one for scoring those answers against the retrieved context and/or query

7. **Corpus and indexing pipeline**
   - The corpus is stored under `corpus/raw` and `corpus/processed`, with `corpus/processed/chunks.json` as a persisted processed artifact.
   - `build_corpus.ipynb` suggests offline preprocessing/index-building happens separately from live query serving.
   - `src/corpus.py` likely loads and normalizes these chunks for retrieval, keeping the serving path independent of raw document ingestion.

8. **Persistence and state**
   - `src/storage.py` and the README indicate **SQLite** is used for persistence.
   - That storage likely holds benchmark runs, scores, monitoring history, or cached results.
   - The repo also includes `adapters/`, which is probably intended as an integration boundary for external data sources or future ingestion connectors, though it is currently empty.

9. **Scheduling and monitoring**
   - `src/scheduler.py` and the README’s mention of **APScheduler hourly cron** indicate background jobs are part of the system.
   - `src/monitoring.py` plus the “7-day monitoring dashboard” suggest the app collects and aggregates run history over time, separate from live query execution.
   - This creates a second major data flow: **periodic benchmark collection → SQLite → monitoring dashboard**, independent of direct user queries.

10. **Configuration and secrets**
    - `config.py` and `.env.example` show the app is environment-driven.
    - The key external dependency is **`GROQ_API_KEY`**, which gates both generation and judge evaluation.
    - This keeps cloud API access out of the code path and makes deployment portable across local dev and container hosting.

11. **Testing and quality boundary**
    - `tests/test_retrieval.py`, `tests/test_generation.py`, and `tests/test_evaluation.py` map directly to the three core ML subsystems.
    - This is useful for architecture diagrams because the repo’s test coverage mirrors the runtime decomposition: retrieval, generation, and evaluation are treated as separate units.

12. **End-to-end data flow**
    - A user query enters the backend through the web UI.
    - The backend runs the query through one or more retrieval strategies.
    - Retrieved chunks are fed to Groq for answer generation.
    - The generated output is scored by the judge model.
    - Results are persisted in SQLite and surfaced in the comparison/monitoring UI.
    - Scheduled jobs keep the monitoring data fresh without requiring user interaction.

13. **Key architectural takeaway**
    - This is not just a demo app; it is a **benchmarking system** with a clean separation between:
      - offline corpus preparation
      - online retrieval/generation
      - evaluation
      - persistence/monitoring
      - static presentation
    - The most important diagram boundary is between the **query-time RAG pipeline** and the **scheduled benchmarking/analytics pipeline**, both sharing the same storage and corpus artifacts.

Main entry points: [`main.py`](https://github.com/sridharmalladi/raglens/blob/main/main.py) (Main app), [`src/retrieval.py`](https://github.com/sridharmalladi/raglens/blob/main/src/retrieval.py) (Retrieval), [`src/inference.py`](https://github.com/sridharmalladi/raglens/blob/main/src/inference.py) (Generation), [`src/evaluation.py`](https://github.com/sridharmalladi/raglens/blob/main/src/evaluation.py) (Judge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["UI"]
  node_ui_html["Dashboard<br/>static UI<br/>[index.html]"]
  node_ui_js["Client logic<br/>browser script<br/>[app.js]"]
  node_ui_css["Styles<br/>[styles.css]"]
end

subgraph group_backend["Backend"]
  node_main["Main app<br/>ASGI entrypoint<br/>[main.py]"]
  node_config["Config<br/>[config.py]"]
  node_models["Models<br/>shared schemas<br/>[models.py]"]
  node_retrieval["Retrieval<br/>RAG strategies<br/>[retrieval.py]"]
  node_corpus["Corpus<br/>chunk loading<br/>[corpus.py]"]
  node_inference["Generation<br/>LLM calls<br/>[inference.py]"]
  node_evaluation["Judge<br/>LLM scoring<br/>[evaluation.py]"]
  node_monitoring["Monitoring<br/>metrics view<br/>[monitoring.py]"]
end

subgraph group_data["Data"]
  node_storage[("SQLite<br/>persistence<br/>[storage.py]")]
  node_chunks["Chunks<br/>processed corpus<br/>[chunks.json]"]
  node_raw_corpus["Raw corpus<br/>source documents"]
end

subgraph group_ops["Ops"]
  node_scheduler["Scheduler<br/>background jobs<br/>[scheduler.py]"]
  node_build_pipeline["Corpus build<br/>offline notebook<br/>[build_corpus.ipynb]"]
  node_adapters["Adapters<br/>integration boundary"]
  node_docker["Container<br/>deployment"]
end

node_main -->|"serves"| node_ui_html
node_main -->|"loads"| node_ui_js
node_main -->|"query path"| node_retrieval
node_main -->|"generates"| node_inference
node_main -->|"scores"| node_evaluation
node_main -->|"shows"| node_monitoring
node_ui_js -->|"API calls"| node_main
node_retrieval -->|"uses"| node_corpus
node_retrieval -->|"reads"| node_chunks
node_retrieval -->|"shared types"| node_models
node_retrieval -->|"stores results"| node_storage
node_inference -->|"uses keys"| node_config
node_inference -->|"shared types"| node_models
node_evaluation -->|"evaluates output"| node_inference
node_evaluation -->|"records scores"| node_storage
node_monitoring -->|"aggregates"| node_storage
node_scheduler -->|"periodic runs"| node_retrieval
node_scheduler -->|"refreshes"| node_monitoring
node_build_pipeline -->|"processes"| node_raw_corpus
node_build_pipeline -->|"produces"| node_chunks
node_docker -->|"packages"| node_main
node_adapters -.->|"ingests"| node_raw_corpus

click node_main "https://github.com/sridharmalladi/raglens/blob/main/main.py"
click node_ui_html "https://github.com/sridharmalladi/raglens/blob/main/static/index.html"
click node_ui_js "https://github.com/sridharmalladi/raglens/blob/main/static/app.js"
click node_ui_css "https://github.com/sridharmalladi/raglens/blob/main/static/styles.css"
click node_config "https://github.com/sridharmalladi/raglens/blob/main/config.py"
click node_models "https://github.com/sridharmalladi/raglens/blob/main/src/models.py"
click node_retrieval "https://github.com/sridharmalladi/raglens/blob/main/src/retrieval.py"
click node_corpus "https://github.com/sridharmalladi/raglens/blob/main/src/corpus.py"
click node_inference "https://github.com/sridharmalladi/raglens/blob/main/src/inference.py"
click node_evaluation "https://github.com/sridharmalladi/raglens/blob/main/src/evaluation.py"
click node_monitoring "https://github.com/sridharmalladi/raglens/blob/main/src/monitoring.py"
click node_scheduler "https://github.com/sridharmalladi/raglens/blob/main/src/scheduler.py"
click node_storage "https://github.com/sridharmalladi/raglens/blob/main/src/storage.py"
click node_chunks "https://github.com/sridharmalladi/raglens/blob/main/corpus/processed/chunks.json"
click node_raw_corpus "https://github.com/sridharmalladi/raglens/tree/main/corpus/raw"
click node_build_pipeline "https://github.com/sridharmalladi/raglens/blob/main/build_corpus.ipynb"
click node_adapters "https://github.com/sridharmalladi/raglens/tree/main/adapters"
click node_docker "https://github.com/sridharmalladi/raglens/tree/main/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui_html,node_ui_js,node_ui_css toneBlue
class node_main,node_config,node_models,node_retrieval,node_corpus,node_inference,node_evaluation,node_monitoring toneAmber
class node_storage,node_chunks,node_raw_corpus toneMint
class node_scheduler,node_build_pipeline,node_adapters,node_docker toneRose
```

## Components

### UI

Static presentation layer for the comparison dashboard.

- [Dashboard](https://github.com/sridharmalladi/raglens/blob/main/static/index.html): static UI · Primary web page for comparing RAG configurations. · `static/index.html`
- [Client logic](https://github.com/sridharmalladi/raglens/blob/main/static/app.js): browser script · Front-end behavior and API calls for the dashboard. · `static/app.js`
- [Styles](https://github.com/sridharmalladi/raglens/blob/main/static/styles.css): styles · Visual presentation for the dashboard. · `static/styles.css`

### Backend

Python app, orchestration, retrieval, evaluation, and persistence.

- [Main app](https://github.com/sridharmalladi/raglens/blob/main/main.py): ASGI entrypoint · Serves the app and routes requests into backend orchestration. · `main.py`
- [Config](https://github.com/sridharmalladi/raglens/blob/main/config.py): env config · Environment-driven settings and secrets. · `config.py`
- [Models](https://github.com/sridharmalladi/raglens/blob/main/src/models.py): shared schemas · Common data structures and configuration objects. · `src/models.py`
- [Retrieval](https://github.com/sridharmalladi/raglens/blob/main/src/retrieval.py): RAG strategies · Coordinates dense, sparse, hybrid, and reranked retrieval. · `src/retrieval.py`
- [Corpus](https://github.com/sridharmalladi/raglens/blob/main/src/corpus.py): chunk loading · Loads and normalizes processed corpus chunks for serving. · `src/corpus.py`
- [Generation](https://github.com/sridharmalladi/raglens/blob/main/src/inference.py): LLM calls · Builds prompts and produces candidate answers from retrieved context. · `src/inference.py`
- [Judge](https://github.com/sridharmalladi/raglens/blob/main/src/evaluation.py): LLM scoring · Scores answers with faithfulness, relevancy, and precision metrics. · `src/evaluation.py`
- [Monitoring](https://github.com/sridharmalladi/raglens/blob/main/src/monitoring.py): metrics view · Aggregates run history and dashboard stats over time. · `src/monitoring.py`

### Data

Corpus artifacts and persisted state used by the app.

- [SQLite](https://github.com/sridharmalladi/raglens/blob/main/src/storage.py): persistence · Stores runs, scores, cached results, and monitoring history. · `src/storage.py`
- [Chunks](https://github.com/sridharmalladi/raglens/blob/main/corpus/processed/chunks.json): processed corpus · Persisted processed corpus artifact used by retrieval. · `corpus/processed/chunks.json`
- [Raw corpus](https://github.com/sridharmalladi/raglens/tree/main/corpus/raw): source documents · Original corpus inputs for offline preprocessing. · `corpus/raw`

### Ops

Containerization and scheduled/background execution.

- [Scheduler](https://github.com/sridharmalladi/raglens/blob/main/src/scheduler.py): background jobs · Runs periodic benchmark and monitoring jobs. · `src/scheduler.py`
- [Corpus build](https://github.com/sridharmalladi/raglens/blob/main/build_corpus.ipynb): offline notebook · Offline preprocessing and index-building workflow. · `build_corpus.ipynb`
- [Adapters](https://github.com/sridharmalladi/raglens/tree/main/adapters): integration boundary · Placeholder boundary for external ingestion or integration connectors. · `adapters`
- [Container](https://github.com/sridharmalladi/raglens/tree/main/Dockerfile): deployment · Containerized deployment for local and hosted execution. · `Dockerfile`

## Connections

- Main app → Dashboard: serves · Main app exposes the dashboard UI.
- Main app → Client logic: loads · Browser client behavior is delivered with the app.
- Main app → Retrieval: query path · Requests flow into retrieval strategy execution.
- Main app → Generation: generates · Backend calls the LLM answer generation flow.
- Main app → Judge: scores · Backend runs judge scoring for benchmark outputs.
- Main app → Monitoring: shows · Dashboard surfaces monitoring and history data.
- Client logic → Main app: API calls · Front end invokes backend endpoints.
- Retrieval → Corpus: uses · Retrieval operates over processed chunks.
- Retrieval → Chunks: reads · Chunk artifact is the persisted retrieval input.
- Retrieval → Models: shared types · Uses common request and result schemas.
- Retrieval → SQLite: stores results · Persists benchmark outcomes and cached run data.
- Generation → Config: uses keys · LLM access is driven by environment config.
- Generation → Models: shared types · Consumes and returns structured payloads.
- Judge → Generation: evaluates output · Judge scores generated answers.
- Judge → SQLite: records scores · Persists evaluation outcomes.
- Monitoring → SQLite: aggregates · Monitoring dashboard reads persisted history.
- Scheduler → Retrieval: periodic runs · Background jobs trigger benchmark executions.
- Scheduler → Monitoring: refreshes · Scheduled jobs keep metrics current.
- Corpus build → Raw corpus: processes · Offline notebook transforms source documents.
- Corpus build → Chunks: produces · Offline preprocessing emits processed chunks.
- Container → Main app: packages · Container image bundles the runtime entrypoint.
- Adapters → Raw corpus: ingests · Integration boundary for future data sources.