# vedanshimesvaniya/antarkosh architecture

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

- Interactive diagram: https://gitdiagram.com/vedanshimesvaniya/antarkosh
- Repository: https://github.com/vedanshimesvaniya/antarkosh

## Overview

Antarkosh combines document RAG and live-database Text-to-SQL behind a unified query experience. Users upload documents for staged extraction, embedding, and indexing, or ask questions that are routed through document retrieval and/or SQL generation, validation, and execution before results are returned. The React UI communicates with FastAPI; shared provider routing, safety controls, budgets, and telemetry support the pipelines. The README documents the major product flows; sampled source and the SOURCE INDEX support the specific module links shown. Some unsampled implementation details are therefore represented at subsystem level.

Main entry points: [`src/pipeline/query.py`](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/pipeline/query.py) (Query orchestrator), [`src/pipeline/ingestion.py`](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/pipeline/ingestion.py) (Ingestion orchestrator), [`src/main.py`](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/main.py) (FastAPI application), [`src/stages/s12b_sql_retrieval.py`](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/stages/s12b_sql_retrieval.py) (SQL generation and retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User Interface"]
  node_ui["React application<br/>[App.jsx]"]
  node_ui_state["UI state and API<br/>[store.js]"]
end

subgraph group_api["Application API"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_query_api["Query endpoint<br/>[query.py]"]
  node_upload_api["Upload endpoint<br/>[upload.py]"]
end

subgraph group_pipelines["Knowledge Pipelines"]
  node_query_orchestrator["Query orchestrator<br/>[query.py]"]
  node_ingestion_orchestrator["Ingestion orchestrator<br/>[ingestion.py]"]
  node_document_processing["Document processing"]
  node_embedding["Dense and sparse embeddings<br/>[s10_embeddings.py]"]
  node_vector_store[("Hybrid vector index")]
  node_rag_retrieval["RAG retrieval"]
end

subgraph group_sql["Text-to-SQL"]
  node_sql_retrieval["SQL generation and retrieval"]
  node_live_db[("Live relational database")]
end

subgraph group_runtime["Runtime Services"]
  node_provider_router["Provider routing<br/>[provider_client.py]"]
  node_guards["Query safety guards"]
  node_budget["Query token budget<br/>[query_budget.py]"]
  node_telemetry["Tracing and telemetry<br/>[telemetry.py]"]
  node_ingestion_registry[("Ingestion registry")]
end

node_user(("User"))
node_llm_providers{{"LLM and vision providers"}}
node_qdrant[("Qdrant Cloud")]

node_user -->|"asks or uploads"| node_ui
node_ui -->|"uses state"| node_ui_state
node_ui_state -.->|"calls API"| node_fastapi
node_fastapi -->|"routes queries"| node_query_api
node_fastapi -->|"routes uploads"| node_upload_api
node_query_api -->|"calls"| node_query_orchestrator
node_upload_api -->|"starts ingestion"| node_ingestion_orchestrator
node_ingestion_orchestrator -->|"runs stages"| node_document_processing
node_ingestion_orchestrator -->|"embeds chunks"| node_embedding
node_ingestion_orchestrator -->|"indexes chunks"| node_vector_store
node_ingestion_orchestrator -->|"checks registry"| node_ingestion_registry
node_query_orchestrator -->|"embeds query"| node_embedding
node_query_orchestrator -->|"retrieves documents"| node_rag_retrieval
node_query_orchestrator -->|"dispatches SQL"| node_sql_retrieval
node_rag_retrieval -->|"searches index"| node_vector_store
node_sql_retrieval -->|"executes SQL"| node_live_db
node_ingestion_orchestrator -->|"routes vision tasks"| node_provider_router
node_query_orchestrator -->|"routes generation"| node_provider_router
node_provider_router -->|"calls providers"| node_llm_providers
node_embedding -->|"provides vectors"| node_qdrant
node_vector_store -->|"reads and writes"| node_qdrant
node_sql_retrieval -.->|"validates queries"| node_guards
node_query_orchestrator -.->|"limits query use"| node_budget
node_query_orchestrator -.->|"records execution"| node_telemetry

click node_ui "https://github.com/vedanshimesvaniya/antarkosh/blob/main/Antarkosh_UI/src/App.jsx"
click node_ui_state "https://github.com/vedanshimesvaniya/antarkosh/blob/main/Antarkosh_UI/src/store/store.js"
click node_fastapi "https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/main.py"
click node_query_api "https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/api/query.py"
click node_upload_api "https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/api/upload.py"
click node_query_orchestrator "https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/pipeline/query.py"
click node_ingestion_orchestrator "https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/pipeline/ingestion.py"
click node_document_processing "https://github.com/vedanshimesvaniya/antarkosh/tree/main/src/stages"
click node_embedding "https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/stages/s10_embeddings.py"
click node_vector_store "https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/stages/s11_vector_store.py"
click node_rag_retrieval "https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/stages/s12_s13_s14_retrieval.py"
click node_sql_retrieval "https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/stages/s12b_sql_retrieval.py"
click node_provider_router "https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/core/provider_client.py"
click node_guards "https://github.com/vedanshimesvaniya/antarkosh/tree/main/src/guards"
click node_budget "https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/utils/query_budget.py"
click node_telemetry "https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/utils/telemetry.py"
click node_ingestion_registry "https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/core/ingestion_registry.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_ui,node_ui_state,node_user toneBlue
class node_fastapi,node_query_api,node_upload_api,node_qdrant toneAmber
class node_query_orchestrator,node_ingestion_orchestrator,node_document_processing,node_embedding,node_vector_store,node_rag_retrieval toneMint
class node_sql_retrieval,node_live_db toneRose
class node_provider_router,node_guards,node_budget,node_telemetry,node_ingestion_registry,node_llm_providers toneIndigo
```

## Components

### User Interface

- [React application](https://github.com/vedanshimesvaniya/antarkosh/blob/main/Antarkosh_UI/src/App.jsx): `Antarkosh_UI/src/App.jsx`
- [UI state and API](https://github.com/vedanshimesvaniya/antarkosh/blob/main/Antarkosh_UI/src/store/store.js): `Antarkosh_UI/src/store/store.js`

### Application API

- [FastAPI application](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/main.py): `src/main.py`
- [Query endpoint](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/api/query.py): `src/api/query.py`
- [Upload endpoint](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/api/upload.py): `src/api/upload.py`

### Knowledge Pipelines

- [Query orchestrator](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/pipeline/query.py): `src/pipeline/query.py`
- [Ingestion orchestrator](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/pipeline/ingestion.py): `src/pipeline/ingestion.py`
- [Document processing](https://github.com/vedanshimesvaniya/antarkosh/tree/main/src/stages): `src/stages`
- [Dense and sparse embeddings](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/stages/s10_embeddings.py): `src/stages/s10_embeddings.py`
- [Hybrid vector index](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/stages/s11_vector_store.py): `src/stages/s11_vector_store.py`
- [RAG retrieval](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/stages/s12_s13_s14_retrieval.py): `src/stages/s12_s13_s14_retrieval.py`

### Text-to-SQL

- [SQL generation and retrieval](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/stages/s12b_sql_retrieval.py): `src/stages/s12b_sql_retrieval.py`
- **Live relational database**

### Runtime Services

- [Provider routing](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/core/provider_client.py): `src/core/provider_client.py`
- [Query safety guards](https://github.com/vedanshimesvaniya/antarkosh/tree/main/src/guards): `src/guards`
- [Query token budget](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/utils/query_budget.py): `src/utils/query_budget.py`
- [Tracing and telemetry](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/utils/telemetry.py): `src/utils/telemetry.py`
- [Ingestion registry](https://github.com/vedanshimesvaniya/antarkosh/blob/main/src/core/ingestion_registry.py): `src/core/ingestion_registry.py`

### Other components

- **User**
- **LLM and vision providers**
- **Qdrant Cloud**

## Connections

- User → React application: asks or uploads (evidence: `README.md`)
- React application → UI state and API: uses state (evidence: `Antarkosh_UI/src/App.jsx`)
- UI state and API → FastAPI application: calls API
- FastAPI application → Query endpoint: routes queries (evidence: `src/main.py`)
- FastAPI application → Upload endpoint: routes uploads (evidence: `src/main.py`)
- Query endpoint → Query orchestrator: calls (evidence: `src/api/query.py`)
- Upload endpoint → Ingestion orchestrator: starts ingestion (evidence: `README.md`)
- Ingestion orchestrator → Document processing: runs stages (evidence: `src/pipeline/ingestion.py`)
- Ingestion orchestrator → Dense and sparse embeddings: embeds chunks (evidence: `src/pipeline/ingestion.py`)
- Ingestion orchestrator → Hybrid vector index: indexes chunks (evidence: `src/pipeline/ingestion.py`)
- Ingestion orchestrator → Ingestion registry: checks registry (evidence: `src/pipeline/ingestion.py`)
- Query orchestrator → Dense and sparse embeddings: embeds query (evidence: `src/pipeline/query.py`)
- Query orchestrator → RAG retrieval: retrieves documents (evidence: `src/pipeline/query.py`)
- Query orchestrator → SQL generation and retrieval: dispatches SQL (evidence: `src/pipeline/query.py`)
- RAG retrieval → Hybrid vector index: searches index (evidence: `src/stages/s12_s13_s14_retrieval.py`)
- SQL generation and retrieval → Live relational database: executes SQL (evidence: `README.md`)
- Ingestion orchestrator → Provider routing: routes vision tasks (evidence: `src/pipeline/ingestion.py`)
- Query orchestrator → Provider routing: routes generation (evidence: `src/pipeline/query.py`)
- Provider routing → LLM and vision providers: calls providers (evidence: `src/core/provider_client.py`)
- Dense and sparse embeddings → Qdrant Cloud: provides vectors (evidence: `README.md`)
- Hybrid vector index → Qdrant Cloud: reads and writes (evidence: `README.md`)
- SQL generation and retrieval → Query safety guards: validates queries (evidence: `src/stages/s12b_sql_retrieval.py`)
- Query orchestrator → Query token budget: limits query use (evidence: `src/pipeline/query.py`)
- Query orchestrator → Tracing and telemetry: records execution (evidence: `src/pipeline/query.py`)
