# surajsuru/banking-rag-copilot architecture

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

- Interactive diagram: https://gitdiagram.com/surajsuru/banking-rag-copilot
- Repository: https://github.com/surajsuru/banking-rag-copilot

## Overview

Banking RAG Copilot lets employees ask banking-operations questions and receive answers grounded in retrieved knowledge-base chunks, with sources and grounding signals. The principal flow is Streamlit chat → FastAPI → RAG orchestration → access-filtered hybrid retrieval → prompt and LLM → citation/grounding results. Documents also pass through parsing, cleaning, chunking, embedding, and vector storage; evaluation is a separate product capability. The README documents API/UI, reranking, RBAC, and evaluation; unsampled wiring is shown only where documented, and uncertain links are omitted.

Main entry points: [`src/retrieval/hybrid_search.py`](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/retrieval/hybrid_search.py) (Hybrid search), [`src/ingestion/pipeline.py`](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/ingestion/pipeline.py) (Ingestion pipeline), [`src/rag/pipeline.py`](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/rag/pipeline.py) (RAG orchestrator), [`app/api.py`](https://github.com/surajsuru/banking-rag-copilot/blob/main/app/api.py) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Knowledge Ingestion"]
  node_ingestion["Ingestion pipeline<br/>[pipeline.py]"]
  node_loader["File discovery<br/>[loader.py]"]
  node_parser["Format parsers<br/>[parser.py]"]
  node_cleaner["Text cleaning<br/>[cleaner.py]"]
  node_chunker["Document chunking<br/>[chunker.py]"]
end

subgraph group_search["Retrieval and Storage"]
  node_embedder["Embedding model<br/>[embedder.py]"]
  node_hybrid["Hybrid search<br/>[hybrid_search.py]"]
  node_vector["Vector search<br/>[vector_search.py]"]
  node_bm25["BM25 search<br/>[bm25_search.py]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
  node_store[("Chunk vector store<br/>[vector_store.py]")]
end

subgraph group_answer["Answer Generation"]
  node_rag["RAG orchestrator<br/>[pipeline.py]"]
  node_prompt["Prompt construction<br/>[prompt.py]"]
  node_llm["LLM client<br/>[llm.py]"]
  node_citations["Citations and grounding<br/>[citations.py]"]
end

subgraph group_interfaces["Employee Interfaces"]
  node_ui["Chat UI<br/>[ui.py]"]
  node_api["REST API<br/>[api.py]"]
end

subgraph group_quality["Security and Evaluation"]
  node_access["Role access rules<br/>[access_control.py]"]
  node_evaluation["RAG evaluation"]
end

node_employee(("Bank employee"))
node_postgres[("PostgreSQL pgvector")]
node_groq["Groq inference"]

node_employee -->|"asks question"| node_ui
node_ui -->|"POSTs question"| node_api
node_api -->|"invokes"| node_rag
node_rag -->|"retrieves chunks"| node_hybrid
node_hybrid -->|"runs semantic search"| node_vector
node_hybrid -->|"runs keyword search"| node_bm25
node_hybrid -->|"reranks results"| node_reranker
node_hybrid -->|"gets role permissions"| node_access
node_vector -->|"embeds query"| node_embedder
node_vector -->|"searches vectors"| node_store
node_store -->|"queries"| node_postgres
node_hybrid -->|"loads BM25 chunks"| node_postgres
node_ingestion -->|"discovers files"| node_loader
node_ingestion -->|"parses files"| node_parser
node_ingestion -->|"cleans text"| node_cleaner
node_ingestion -->|"creates chunks"| node_chunker
node_ingestion -.->|"embeds chunks"| node_embedder
node_ingestion -.->|"stores chunks"| node_store
node_rag -->|"builds prompt"| node_prompt
node_rag -->|"generates answer"| node_llm
node_llm -->|"requests completion"| node_groq
node_rag -->|"checks answer"| node_citations
node_rag -->|"returns answer and sources"| node_api
node_api -->|"returns response"| node_ui
node_evaluation -.->|"benchmarks retrieval"| node_hybrid

click node_ui "https://github.com/surajsuru/banking-rag-copilot/blob/main/app/ui.py"
click node_api "https://github.com/surajsuru/banking-rag-copilot/blob/main/app/api.py"
click node_rag "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/rag/pipeline.py"
click node_ingestion "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/ingestion/pipeline.py"
click node_loader "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/ingestion/loader.py"
click node_parser "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/ingestion/parser.py"
click node_cleaner "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/ingestion/cleaner.py"
click node_chunker "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/ingestion/chunker.py"
click node_embedder "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/embeddings/embedder.py"
click node_hybrid "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/retrieval/hybrid_search.py"
click node_vector "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/retrieval/vector_search.py"
click node_bm25 "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/retrieval/bm25_search.py"
click node_reranker "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/retrieval/reranker.py"
click node_access "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/security/access_control.py"
click node_store "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/database/vector_store.py"
click node_prompt "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/generation/prompt.py"
click node_llm "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/generation/llm.py"
click node_citations "https://github.com/surajsuru/banking-rag-copilot/blob/main/src/rag/citations.py"
click node_evaluation "https://github.com/surajsuru/banking-rag-copilot/tree/main/src/evaluation"

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_ingestion,node_loader,node_parser,node_cleaner,node_chunker toneBlue
class node_embedder,node_hybrid,node_vector,node_bm25,node_reranker,node_store,node_postgres toneAmber
class node_rag,node_prompt,node_llm,node_citations toneMint
class node_ui,node_api toneRose
class node_access,node_evaluation,node_employee,node_groq toneIndigo
```

## Components

### Knowledge Ingestion

- [Ingestion pipeline](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/ingestion/pipeline.py): `src/ingestion/pipeline.py`
- [File discovery](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/ingestion/loader.py): `src/ingestion/loader.py`
- [Format parsers](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/ingestion/parser.py): `src/ingestion/parser.py`
- [Text cleaning](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/ingestion/cleaner.py): `src/ingestion/cleaner.py`
- [Document chunking](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/ingestion/chunker.py): `src/ingestion/chunker.py`

### Retrieval and Storage

- [Embedding model](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/embeddings/embedder.py): `src/embeddings/embedder.py`
- [Hybrid search](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/retrieval/hybrid_search.py): `src/retrieval/hybrid_search.py`
- [Vector search](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/retrieval/vector_search.py): `src/retrieval/vector_search.py`
- [BM25 search](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/retrieval/bm25_search.py): `src/retrieval/bm25_search.py`
- [Cross-encoder reranker](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/retrieval/reranker.py): `src/retrieval/reranker.py`
- [Chunk vector store](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/database/vector_store.py): `src/database/vector_store.py`

### Answer Generation

- [RAG orchestrator](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/rag/pipeline.py): `src/rag/pipeline.py`
- [Prompt construction](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/generation/prompt.py): `src/generation/prompt.py`
- [LLM client](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/generation/llm.py): `src/generation/llm.py`
- [Citations and grounding](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/rag/citations.py): `src/rag/citations.py`

### Employee Interfaces

- [Chat UI](https://github.com/surajsuru/banking-rag-copilot/blob/main/app/ui.py): `app/ui.py`
- [REST API](https://github.com/surajsuru/banking-rag-copilot/blob/main/app/api.py): `app/api.py`

### Security and Evaluation

- [Role access rules](https://github.com/surajsuru/banking-rag-copilot/blob/main/src/security/access_control.py): `src/security/access_control.py`
- [RAG evaluation](https://github.com/surajsuru/banking-rag-copilot/tree/main/src/evaluation): `src/evaluation`

### Other components

- **Bank employee**
- **PostgreSQL pgvector**
- **Groq inference**

## Connections

- Bank employee → Chat UI: asks question
- Chat UI → REST API: POSTs question
- REST API → RAG orchestrator: invokes
- RAG orchestrator → Hybrid search: retrieves chunks
- Hybrid search → Vector search: runs semantic search
- Hybrid search → BM25 search: runs keyword search
- Hybrid search → Cross-encoder reranker: reranks results
- Hybrid search → Role access rules: gets role permissions
- Vector search → Embedding model: embeds query
- Vector search → Chunk vector store: searches vectors
- Chunk vector store → PostgreSQL pgvector: queries
- Hybrid search → PostgreSQL pgvector: loads BM25 chunks
- Ingestion pipeline → File discovery: discovers files
- Ingestion pipeline → Format parsers: parses files
- Ingestion pipeline → Text cleaning: cleans text
- Ingestion pipeline → Document chunking: creates chunks
- Ingestion pipeline → Embedding model: embeds chunks
- Ingestion pipeline → Chunk vector store: stores chunks
- RAG orchestrator → Prompt construction: builds prompt
- RAG orchestrator → LLM client: generates answer
- LLM client → Groq inference: requests completion
- RAG orchestrator → Citations and grounding: checks answer
- RAG orchestrator → REST API: returns answer and sources
- REST API → Chat UI: returns response
- RAG evaluation → Hybrid search: benchmarks retrieval