# dipanshu1146/waterrag architecture

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

- Interactive diagram: https://gitdiagram.com/dipanshu1146/waterrag
- Repository: https://github.com/dipanshu1146/waterrag

## Overview

This is a wastewater-document RAG application: users upload documents, which the backend extracts, chunks, and indexes for later question answering; the UI also supports document listing and deletion. The graph distinguishes upload orchestration, ingestion/extraction, retrieval, and storage. The README is empty, so capabilities and relationships are based on the supplied source excerpts and SOURCE INDEX; unsampled route behavior and integrations are not expanded beyond documented references.

Main entry points: [`src/vectorstore/search_index.py`](https://github.com/dipanshu1146/waterrag/blob/main/src/vectorstore/search_index.py) (Index operations), [`src/api/routes/upload.py`](https://github.com/dipanshu1146/waterrag/blob/main/src/api/routes/upload.py) (Upload management), [`src/api/routes/ask.py`](https://github.com/dipanshu1146/waterrag/blob/main/src/api/routes/ask.py) (Question answering), [`src/ingestion/pipeline.py`](https://github.com/dipanshu1146/waterrag/blob/main/src/ingestion/pipeline.py) (Ingestion pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_frontend["Web application<br/>[App.jsx]"]
end

subgraph group_api["API workflows"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_uploads["Upload management<br/>[upload.py]"]
  node_ask["Question answering<br/>[ask.py]"]
end

subgraph group_ingestion["Ingestion and extraction"]
  node_pipeline["Ingestion pipeline<br/>[pipeline.py]"]
  node_loader["Document loading<br/>[load_documents.py]"]
  node_pdf_tables["PDF table extraction"]
  node_table_text["Table row formatting<br/>[table_to_text.py]"]
  node_document_extract["Document extraction"]
end

subgraph group_retrieval["Question retrieval"]
  node_general_search["Hybrid retrieval<br/>[general_search.py]"]
  node_filter_index["Filtered retrieval<br/>[filter_index.py]"]
end

subgraph group_storage["Index and storage"]
  node_search_index["Index operations<br/>[search_index.py]"]
  node_cloud_adapter["Cloud storage adapter<br/>[cloud_store.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_vector_db[("Document vector index")]
end

node_user(("Document user"))
node_cloud_db[("Cloud database")]
node_object_storage[("Cloud file storage")]

node_user -->|"uses"| node_frontend
node_frontend -->|"uploads files"| node_uploads
node_frontend -->|"manages documents"| node_uploads
node_api_app -->|"registers route"| node_uploads
node_api_app -->|"registers route"| node_ask
node_uploads -->|"indexes upload"| node_pipeline
node_uploads -->|"indexes and deletes"| node_search_index
node_pipeline -->|"loads documents"| node_loader
node_pipeline -->|"extracts PDF tables"| node_pdf_tables
node_pipeline -->|"formats table rows"| node_table_text
node_loader -->|"extracts tables"| node_pdf_tables
node_ask -->|"retrieves broadly"| node_general_search
node_ask -->|"filters retrieval"| node_filter_index
node_ask -->|"queries index"| node_search_index
node_general_search -->|"semantic search"| node_search_index
node_filter_index -->|"queries index"| node_search_index
node_search_index -->|"loads Excel records"| node_loader
node_search_index -.->|"uses cloud backend"| node_cloud_adapter
node_general_search -.->|"uses cloud backend"| node_cloud_adapter
node_general_search -->|"reads settings"| node_config
node_filter_index -->|"reads settings"| node_config
node_search_index -->|"reads settings"| node_config
node_search_index -->|"reads and writes"| node_vector_db
node_cloud_adapter -->|"stores vectors"| node_cloud_db
node_cloud_adapter -->|"stores files"| node_object_storage

click node_frontend "https://github.com/dipanshu1146/waterrag/blob/main/frontend/src/App.jsx"
click node_api_app "https://github.com/dipanshu1146/waterrag/blob/main/src/api/main.py"
click node_uploads "https://github.com/dipanshu1146/waterrag/blob/main/src/api/routes/upload.py"
click node_ask "https://github.com/dipanshu1146/waterrag/blob/main/src/api/routes/ask.py"
click node_pipeline "https://github.com/dipanshu1146/waterrag/blob/main/src/ingestion/pipeline.py"
click node_loader "https://github.com/dipanshu1146/waterrag/blob/main/src/ingestion/load_documents.py"
click node_pdf_tables "https://github.com/dipanshu1146/waterrag/blob/main/src/extraction/pdf_table_extractor.py"
click node_table_text "https://github.com/dipanshu1146/waterrag/blob/main/src/extraction/table_to_text.py"
click node_document_extract "https://github.com/dipanshu1146/waterrag/blob/main/src/extraction/document_extractor.py"
click node_general_search "https://github.com/dipanshu1146/waterrag/blob/main/src/vectorstore/general_search.py"
click node_filter_index "https://github.com/dipanshu1146/waterrag/blob/main/src/vectorstore/filter_index.py"
click node_search_index "https://github.com/dipanshu1146/waterrag/blob/main/src/vectorstore/search_index.py"
click node_cloud_adapter "https://github.com/dipanshu1146/waterrag/blob/main/src/vectorstore/cloud_store.py"
click node_config "https://github.com/dipanshu1146/waterrag/blob/main/src/config.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_frontend,node_user toneBlue
class node_api_app,node_uploads,node_ask,node_cloud_db,node_object_storage toneAmber
class node_pipeline,node_loader,node_pdf_tables,node_table_text,node_document_extract toneMint
class node_general_search,node_filter_index toneRose
class node_search_index,node_cloud_adapter,node_config,node_vector_db toneIndigo
```

## Components

### User interface

- [Web application](https://github.com/dipanshu1146/waterrag/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### API workflows

- [FastAPI application](https://github.com/dipanshu1146/waterrag/blob/main/src/api/main.py): `src/api/main.py`
- [Upload management](https://github.com/dipanshu1146/waterrag/blob/main/src/api/routes/upload.py): `src/api/routes/upload.py`
- [Question answering](https://github.com/dipanshu1146/waterrag/blob/main/src/api/routes/ask.py): `src/api/routes/ask.py`

### Ingestion and extraction

- [Ingestion pipeline](https://github.com/dipanshu1146/waterrag/blob/main/src/ingestion/pipeline.py): `src/ingestion/pipeline.py`
- [Document loading](https://github.com/dipanshu1146/waterrag/blob/main/src/ingestion/load_documents.py): `src/ingestion/load_documents.py`
- [PDF table extraction](https://github.com/dipanshu1146/waterrag/blob/main/src/extraction/pdf_table_extractor.py): `src/extraction/pdf_table_extractor.py`
- [Table row formatting](https://github.com/dipanshu1146/waterrag/blob/main/src/extraction/table_to_text.py): `src/extraction/table_to_text.py`
- [Document extraction](https://github.com/dipanshu1146/waterrag/blob/main/src/extraction/document_extractor.py): `src/extraction/document_extractor.py`

### Question retrieval

- [Hybrid retrieval](https://github.com/dipanshu1146/waterrag/blob/main/src/vectorstore/general_search.py): `src/vectorstore/general_search.py`
- [Filtered retrieval](https://github.com/dipanshu1146/waterrag/blob/main/src/vectorstore/filter_index.py): `src/vectorstore/filter_index.py`

### Index and storage

- [Index operations](https://github.com/dipanshu1146/waterrag/blob/main/src/vectorstore/search_index.py): `src/vectorstore/search_index.py`
- [Cloud storage adapter](https://github.com/dipanshu1146/waterrag/blob/main/src/vectorstore/cloud_store.py): `src/vectorstore/cloud_store.py`
- [Runtime configuration](https://github.com/dipanshu1146/waterrag/blob/main/src/config.py): `src/config.py`
- **Document vector index**

### Other components

- **Document user**
- **Cloud database**
- **Cloud file storage**

## Connections

- Document user → Web application: uses
- Web application → Upload management: uploads files (evidence: `frontend/src/App.jsx`)
- Web application → Upload management: manages documents (evidence: `frontend/src/App.jsx`)
- FastAPI application → Upload management: registers route (evidence: `src/api/main.py`)
- FastAPI application → Question answering: registers route (evidence: `src/api/main.py`)
- Upload management → Ingestion pipeline: indexes upload (evidence: `src/api/routes/upload.py`)
- Upload management → Index operations: indexes and deletes (evidence: `src/api/routes/upload.py`)
- Ingestion pipeline → Document loading: loads documents (evidence: `src/ingestion/pipeline.py`)
- Ingestion pipeline → PDF table extraction: extracts PDF tables (evidence: `src/ingestion/pipeline.py`)
- Ingestion pipeline → Table row formatting: formats table rows (evidence: `src/ingestion/pipeline.py`)
- Document loading → PDF table extraction: extracts tables (evidence: `src/ingestion/load_documents.py`)
- Question answering → Hybrid retrieval: retrieves broadly (evidence: `src/api/routes/ask.py`)
- Question answering → Filtered retrieval: filters retrieval (evidence: `src/api/routes/ask.py`)
- Question answering → Index operations: queries index (evidence: `src/api/routes/ask.py`)
- Hybrid retrieval → Index operations: semantic search (evidence: `src/vectorstore/general_search.py`)
- Filtered retrieval → Index operations: queries index (evidence: `src/vectorstore/filter_index.py`)
- Index operations → Document loading: loads Excel records (evidence: `src/vectorstore/search_index.py`)
- Index operations → Cloud storage adapter: uses cloud backend (evidence: `src/vectorstore/search_index.py`)
- Hybrid retrieval → Cloud storage adapter: uses cloud backend (evidence: `src/vectorstore/general_search.py`)
- Hybrid retrieval → Runtime configuration: reads settings (evidence: `src/vectorstore/general_search.py`)
- Filtered retrieval → Runtime configuration: reads settings (evidence: `src/vectorstore/filter_index.py`)
- Index operations → Runtime configuration: reads settings (evidence: `src/vectorstore/search_index.py`)
- Index operations → Document vector index: reads and writes (evidence: `src/vectorstore/search_index.py`)
- Cloud storage adapter → Cloud database: stores vectors (evidence: `src/vectorstore/cloud_store.py`)
- Cloud storage adapter → Cloud file storage: stores files (evidence: `src/vectorstore/cloud_store.py`)
