# hrishikeshchandi/semantic-drift-rag architecture

> Architecture diagram of the GitHub repository hrishikeshchandi/semantic-drift-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hrishikeshchandi/semantic-drift-rag
- Repository: https://github.com/hrishikeshchandi/semantic-drift-rag

## Overview

Semantic Drift RAG is a document-grounded question-answering service. Users upload documents, which are loaded, chunked, embedded, indexed for hybrid retrieval, and used to derive corpus drift statistics. For a query, the API checks document scope before invoking a LangGraph retrieval, response, and evaluation loop; out-of-scope queries are refused and near-boundary queries request clarification. The README documents capabilities beyond the sampled implementation, including citations, multi-session use, and multiple ingestion formats; those links are shown where documented rather than inferred from unsampled code.

Main entry points: [`main.py`](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/main.py) (FastAPI server), [`vectorstore/vectorstore.py`](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/vectorstore/vectorstore.py) (Hybrid vector store), [`nodes/nodes.py`](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/nodes/nodes.py) (RAG operations), [`routers/files.py`](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/routers/files.py) (File management API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and interface"]
  node_webui["Web interface<br/>[script.js]"]
  node_api_server["FastAPI server<br/>[main.py]"]
  node_file_api["File management API<br/>[files.py]"]
end

subgraph group_ingest["Document ingestion"]
  node_processor["Document processor<br/>[processor.py]"]
  node_vectorstore[("Hybrid vector store<br/>[vectorstore.py]")]
  node_disk[("User index and sessions")]
end

subgraph group_scope["Scope and sessions"]
  node_drift["Drift detector<br/>[detector.py]"]
  node_session_state[("Session drift state<br/>[detector.py]")]
end

subgraph group_answer["Grounded answering"]
  node_graph["RAG graph<br/>[builder.py]"]
  node_state["Pipeline state<br/>[rag_state.py]"]
  node_nodes["RAG operations<br/>[nodes.py]"]
  node_models["LLM configuration<br/>[llm.py]"]
end

node_user(("User"))
node_model_provider{{"Model providers"}}

node_user -.->|"uses"| node_webui
node_webui -.->|"submits queries"| node_api_server
node_user -->|"uploads and queries"| node_api_server
node_api_server -->|"mounts routes"| node_file_api
node_file_api -->|"loads and chunks"| node_processor
node_file_api -->|"builds index"| node_vectorstore
node_processor -->|"provides chunks"| node_vectorstore
node_vectorstore -->|"persists index"| node_disk
node_api_server -->|"loads retriever"| node_vectorstore
node_api_server -->|"analyzes query"| node_drift
node_drift -->|"reads and updates"| node_session_state
node_drift -->|"reads corpus stats"| node_disk
node_api_server -->|"runs answering graph"| node_graph
node_graph -->|"dispatches steps"| node_nodes
node_graph -->|"invokes with state"| node_state
node_nodes -->|"updates"| node_state
node_nodes -->|"retrieves passages"| node_vectorstore
node_nodes -->|"calls models"| node_models
node_models -->|"configures"| node_model_provider
node_vectorstore -.->|"uses embeddings"| node_model_provider

click node_webui "https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/frontend/script.js"
click node_api_server "https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/main.py"
click node_file_api "https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/routers/files.py"
click node_processor "https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/document_ingestion/processor.py"
click node_vectorstore "https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/vectorstore/vectorstore.py"
click node_drift "https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/drift_detector/detector.py"
click node_session_state "https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/drift_detector/detector.py"
click node_graph "https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/graph_builder/builder.py"
click node_state "https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/state/rag_state.py"
click node_nodes "https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/nodes/nodes.py"
click node_models "https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/llm/llm.py"

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_webui,node_api_server,node_file_api,node_user toneBlue
class node_processor,node_vectorstore,node_disk toneAmber
class node_drift,node_session_state toneMint
class node_graph,node_state,node_nodes,node_models toneRose
class node_model_provider toneIndigo
```

## Components

### API and interface

- [Web interface](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/frontend/script.js): `frontend/script.js`
- [FastAPI server](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/main.py): `main.py`
- [File management API](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/routers/files.py): `routers/files.py`

### Document ingestion

- [Document processor](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/document_ingestion/processor.py): `document_ingestion/processor.py`
- [Hybrid vector store](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/vectorstore/vectorstore.py): `vectorstore/vectorstore.py`
- **User index and sessions**

### Scope and sessions

- [Drift detector](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/drift_detector/detector.py): `drift_detector/detector.py`
- [Session drift state](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/drift_detector/detector.py): `drift_detector/detector.py`

### Grounded answering

- [RAG graph](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/graph_builder/builder.py): `graph_builder/builder.py`
- [Pipeline state](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/state/rag_state.py): `state/rag_state.py`
- [RAG operations](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/nodes/nodes.py): `nodes/nodes.py`
- [LLM configuration](https://github.com/hrishikeshchandi/semantic-drift-rag/blob/main/llm/llm.py): `llm/llm.py`

### Other components

- **User**
- **Model providers**

## Connections

- User → Web interface: uses
- Web interface → FastAPI server: submits queries
- User → FastAPI server: uploads and queries (evidence: `README.md`)
- FastAPI server → File management API: mounts routes (evidence: `main.py`)
- File management API → Document processor: loads and chunks (evidence: `routers/files.py`)
- File management API → Hybrid vector store: builds index (evidence: `routers/files.py`)
- Document processor → Hybrid vector store: provides chunks (evidence: `README.md`)
- Hybrid vector store → User index and sessions: persists index (evidence: `README.md`)
- FastAPI server → Hybrid vector store: loads retriever (evidence: `main.py`)
- FastAPI server → Drift detector: analyzes query (evidence: `main.py`)
- Drift detector → Session drift state: reads and updates (evidence: `drift_detector/detector.py`)
- Drift detector → User index and sessions: reads corpus stats (evidence: `drift_detector/detector.py`)
- FastAPI server → RAG graph: runs answering graph (evidence: `main.py`)
- RAG graph → RAG operations: dispatches steps (evidence: `graph_builder/builder.py`)
- RAG graph → Pipeline state: invokes with state (evidence: `graph_builder/builder.py`)
- RAG operations → Pipeline state: updates (evidence: `nodes/nodes.py`)
- RAG operations → Hybrid vector store: retrieves passages (evidence: `README.md`)
- RAG operations → LLM configuration: calls models (evidence: `nodes/nodes.py`)
- LLM configuration → Model providers: configures (evidence: `llm/llm.py`)
- Hybrid vector store → Model providers: uses embeddings (evidence: `README.md`)