# vansharora156/nexus-rag architecture

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

- Interactive diagram: https://gitdiagram.com/vansharora156/nexus-rag
- Repository: https://github.com/vansharora156/nexus-rag

## Overview

NexusRAG is an enterprise RAG application: users submit questions through a web UI, the API runs permission-aware hybrid retrieval, and Gemini generates cited answers. Administrators can also ingest supported documents through the API; parsing, chunking, deduplication, and dual indexing prepare them for search. The README documents Confluence/Markdown, scanned PDFs, Slack, Excel/CSV, and evaluation capabilities. Source excerpts are partial, so the graph follows documented ingestion stages where implementation details were not sampled and omits uncertain internal wiring.

Main entry points: [`src/pipeline/ingest.py`](https://github.com/vansharora156/nexus-rag/blob/main/src/pipeline/ingest.py) (Ingestion pipeline), [`src/retrieval/hybrid_retriever.py`](https://github.com/vansharora156/nexus-rag/blob/main/src/retrieval/hybrid_retriever.py) (Hybrid retrieval and RRF), [`api/routes.py`](https://github.com/vansharora156/nexus-rag/blob/main/api/routes.py) (API routes), [`src/pipeline/query.py`](https://github.com/vansharora156/nexus-rag/blob/main/src/pipeline/query.py) (Query pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interface and access"]
  node_web["Web interface<br/>[app.js]"]
  node_api["FastAPI application<br/>[app.py]"]
  node_routes["API routes<br/>[routes.py]"]
  node_users[("User accounts<br/>[user_db.py]")]
end

subgraph group_ingest["Document ingestion"]
  node_ingest_pipeline["Ingestion pipeline<br/>[ingest.py]"]
  node_parsers["Parser registry<br/>[registry.py]"]
  node_pdf_parser["PDF and OCR parser<br/>[pdf_parser.py]"]
  node_chunker["Hybrid chunker<br/>[hybrid_chunker.py]"]
  node_dedup["MinHash deduplication<br/>[minhash_dedup.py]"]
end

subgraph group_search["Retrieval and indexing"]
  node_embedder["Text embedder<br/>[embedder.py]"]
  node_vector_store[("Vector store<br/>[vector_store.py]")]
  node_bm25[("BM25 index<br/>[bm25_index.py]")]
  node_query_pipeline["Query pipeline<br/>[query.py]"]
  node_rewriter["Query rewriting<br/>[query_rewriter.py]"]
  node_retriever["Hybrid retrieval and RRF"]
  node_permissions["ACL permissions<br/>[permissions.py]"]
  node_permission_filter["Permission filter"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
end

subgraph group_answer["Answer generation"]
  node_generator["Answer generator<br/>[generator.py]"]
  node_citations["Citation formatter"]
end

node_user(("Enterprise user"))
node_admin(("Ingestion administrator"))
node_documents["Enterprise documents"]
node_qdrant[("Qdrant")]
node_gemini["Google Gemini"]

node_user -->|"asks question"| node_web
node_admin -->|"starts ingestion"| node_web
node_web -->|"calls API"| node_api
node_api -->|"dispatches"| node_routes
node_routes -->|"registers or authenticates"| node_users
node_routes -->|"runs query"| node_query_pipeline
node_routes -->|"starts ingestion"| node_ingest_pipeline
node_documents -->|"provides files"| node_ingest_pipeline
node_ingest_pipeline -->|"parses files"| node_parsers
node_parsers -->|"dispatches PDFs"| node_pdf_parser
node_ingest_pipeline -->|"chunks documents"| node_chunker
node_ingest_pipeline -->|"deduplicates chunks"| node_dedup
node_ingest_pipeline -->|"embeds chunks"| node_embedder
node_ingest_pipeline -->|"indexes vectors"| node_vector_store
node_ingest_pipeline -->|"builds lexical index"| node_bm25
node_query_pipeline -->|"retrieves context"| node_retriever
node_query_pipeline -->|"generates answer"| node_generator
node_retriever -->|"expands query"| node_rewriter
node_retriever -->|"resolves roles"| node_permissions
node_retriever -->|"searches dense index"| node_vector_store
node_retriever -->|"searches lexical index"| node_bm25
node_retriever -->|"filters results"| node_permission_filter
node_retriever -->|"reranks candidates"| node_reranker
node_generator -->|"requests generation"| node_gemini
node_vector_store -->|"reads and writes vectors"| node_qdrant
node_query_pipeline -->|"returns answer and citations"| node_web
node_generator -->|"formats citations"| node_citations

click node_web "https://github.com/vansharora156/nexus-rag/blob/main/frontend/app.js"
click node_api "https://github.com/vansharora156/nexus-rag/blob/main/api/app.py"
click node_routes "https://github.com/vansharora156/nexus-rag/blob/main/api/routes.py"
click node_users "https://github.com/vansharora156/nexus-rag/blob/main/src/auth/user_db.py"
click node_ingest_pipeline "https://github.com/vansharora156/nexus-rag/blob/main/src/pipeline/ingest.py"
click node_parsers "https://github.com/vansharora156/nexus-rag/blob/main/src/parsers/registry.py"
click node_pdf_parser "https://github.com/vansharora156/nexus-rag/blob/main/src/parsers/pdf_parser.py"
click node_chunker "https://github.com/vansharora156/nexus-rag/blob/main/src/chunking/hybrid_chunker.py"
click node_dedup "https://github.com/vansharora156/nexus-rag/blob/main/src/dedup/minhash_dedup.py"
click node_embedder "https://github.com/vansharora156/nexus-rag/blob/main/src/indexing/embedder.py"
click node_vector_store "https://github.com/vansharora156/nexus-rag/blob/main/src/indexing/vector_store.py"
click node_bm25 "https://github.com/vansharora156/nexus-rag/blob/main/src/indexing/bm25_index.py"
click node_query_pipeline "https://github.com/vansharora156/nexus-rag/blob/main/src/pipeline/query.py"
click node_rewriter "https://github.com/vansharora156/nexus-rag/blob/main/src/retrieval/query_rewriter.py"
click node_retriever "https://github.com/vansharora156/nexus-rag/blob/main/src/retrieval/hybrid_retriever.py"
click node_permissions "https://github.com/vansharora156/nexus-rag/blob/main/src/acl/permissions.py"
click node_permission_filter "https://github.com/vansharora156/nexus-rag/blob/main/src/retrieval/permission_filter.py"
click node_reranker "https://github.com/vansharora156/nexus-rag/blob/main/src/retrieval/reranker.py"
click node_generator "https://github.com/vansharora156/nexus-rag/blob/main/src/generation/generator.py"
click node_citations "https://github.com/vansharora156/nexus-rag/blob/main/src/generation/citation_formatter.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_web,node_api,node_routes,node_users,node_user toneBlue
class node_ingest_pipeline,node_parsers,node_pdf_parser,node_chunker,node_dedup,node_qdrant toneAmber
class node_embedder,node_vector_store,node_bm25,node_query_pipeline,node_rewriter,node_retriever,node_permissions,node_permission_filter,node_reranker toneMint
class node_generator,node_citations toneRose
class node_admin,node_documents,node_gemini toneIndigo
```

## Components

### Interface and access

- [Web interface](https://github.com/vansharora156/nexus-rag/blob/main/frontend/app.js): `frontend/app.js`
- [FastAPI application](https://github.com/vansharora156/nexus-rag/blob/main/api/app.py): `api/app.py`
- [API routes](https://github.com/vansharora156/nexus-rag/blob/main/api/routes.py): `api/routes.py`
- [User accounts](https://github.com/vansharora156/nexus-rag/blob/main/src/auth/user_db.py): `src/auth/user_db.py`

### Document ingestion

- [Ingestion pipeline](https://github.com/vansharora156/nexus-rag/blob/main/src/pipeline/ingest.py): `src/pipeline/ingest.py`
- [Parser registry](https://github.com/vansharora156/nexus-rag/blob/main/src/parsers/registry.py): `src/parsers/registry.py`
- [PDF and OCR parser](https://github.com/vansharora156/nexus-rag/blob/main/src/parsers/pdf_parser.py): `src/parsers/pdf_parser.py`
- [Hybrid chunker](https://github.com/vansharora156/nexus-rag/blob/main/src/chunking/hybrid_chunker.py): `src/chunking/hybrid_chunker.py`
- [MinHash deduplication](https://github.com/vansharora156/nexus-rag/blob/main/src/dedup/minhash_dedup.py): `src/dedup/minhash_dedup.py`

### Retrieval and indexing

- [Text embedder](https://github.com/vansharora156/nexus-rag/blob/main/src/indexing/embedder.py): `src/indexing/embedder.py`
- [Vector store](https://github.com/vansharora156/nexus-rag/blob/main/src/indexing/vector_store.py): `src/indexing/vector_store.py`
- [BM25 index](https://github.com/vansharora156/nexus-rag/blob/main/src/indexing/bm25_index.py): `src/indexing/bm25_index.py`
- [Query pipeline](https://github.com/vansharora156/nexus-rag/blob/main/src/pipeline/query.py): `src/pipeline/query.py`
- [Query rewriting](https://github.com/vansharora156/nexus-rag/blob/main/src/retrieval/query_rewriter.py): `src/retrieval/query_rewriter.py`
- [Hybrid retrieval and RRF](https://github.com/vansharora156/nexus-rag/blob/main/src/retrieval/hybrid_retriever.py): `src/retrieval/hybrid_retriever.py`
- [ACL permissions](https://github.com/vansharora156/nexus-rag/blob/main/src/acl/permissions.py): `src/acl/permissions.py`
- [Permission filter](https://github.com/vansharora156/nexus-rag/blob/main/src/retrieval/permission_filter.py): `src/retrieval/permission_filter.py`
- [Cross-encoder reranker](https://github.com/vansharora156/nexus-rag/blob/main/src/retrieval/reranker.py): `src/retrieval/reranker.py`

### Answer generation

- [Answer generator](https://github.com/vansharora156/nexus-rag/blob/main/src/generation/generator.py): `src/generation/generator.py`
- [Citation formatter](https://github.com/vansharora156/nexus-rag/blob/main/src/generation/citation_formatter.py): `src/generation/citation_formatter.py`

### Other components

- **Enterprise user**
- **Ingestion administrator**
- **Enterprise documents**
- **Qdrant**
- **Google Gemini**

## Connections

- Enterprise user → Web interface: asks question
- Ingestion administrator → Web interface: starts ingestion
- Web interface → FastAPI application: calls API
- FastAPI application → API routes: dispatches
- API routes → User accounts: registers or authenticates
- API routes → Query pipeline: runs query
- API routes → Ingestion pipeline: starts ingestion
- Enterprise documents → Ingestion pipeline: provides files
- Ingestion pipeline → Parser registry: parses files
- Parser registry → PDF and OCR parser: dispatches PDFs
- Ingestion pipeline → Hybrid chunker: chunks documents
- Ingestion pipeline → MinHash deduplication: deduplicates chunks
- Ingestion pipeline → Text embedder: embeds chunks
- Ingestion pipeline → Vector store: indexes vectors
- Ingestion pipeline → BM25 index: builds lexical index
- Query pipeline → Hybrid retrieval and RRF: retrieves context
- Query pipeline → Answer generator: generates answer
- Hybrid retrieval and RRF → Query rewriting: expands query
- Hybrid retrieval and RRF → ACL permissions: resolves roles
- Hybrid retrieval and RRF → Vector store: searches dense index
- Hybrid retrieval and RRF → BM25 index: searches lexical index
- Hybrid retrieval and RRF → Permission filter: filters results
- Hybrid retrieval and RRF → Cross-encoder reranker: reranks candidates
- Answer generator → Google Gemini: requests generation
- Vector store → Qdrant: reads and writes vectors
- Query pipeline → Web interface: returns answer and citations
- Answer generator → Citation formatter: formats citations