# abdessamadr/bank-rag-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/abdessamadr/bank-rag-mcp
- Repository: https://github.com/abdessamadr/bank-rag-mcp

## Overview

Bank RAG MCP extracts bank annual reports, indexes page-aware chunks, retrieves relevant passages, and generates French answers with source citations. The main workflow is PDF extraction → chunking → embedding and storage → hybrid retrieval → answer generation. Evaluation and vector-store auditing are additional capabilities. The README documents an MCP server, but no corresponding source directory appears in the supplied tree, so that integration is shown as unverified; the excerpts do not establish a runtime connection to it.

Main entry points: [`src/retrieval/retriever.py`](https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/retrieval/retriever.py) (Hybrid retriever), [`src/generation/answer_generator.py`](https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/generation/answer_generator.py) (Answer generator), [`data`](https://github.com/abdessamadr/bank-rag-mcp/tree/main/data) (Chroma vector store), [`src/ingestion/embedder.py`](https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/ingestion/embedder.py) (Embedding indexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Document ingestion"]
  node_extract["PDF extraction<br/>[extract_pdfs.py]"]
  node_pages["Extracted pages"]
  node_chunker["Page chunking<br/>[chunker.py]"]
  node_chunks["Page-aware chunks"]
end

subgraph group_retrieval["Search and storage"]
  node_embedder["Embedding indexer<br/>[embedder.py]"]
  node_e5["E5 embeddings"]
  node_chroma[("Chroma vector store")]
  node_retriever["Hybrid retriever<br/>[retriever.py]"]
end

subgraph group_answers["Answer generation"]
  node_answer["Answer generator"]
  node_response["Cited answer"]
  node_mcp["MCP search server"]
end

subgraph group_quality["Evaluation and audit"]
  node_retrieval_eval["Retriever evaluation"]
  node_benchmark["Embedding benchmark"]
  node_model_config["Model configurations<br/>[model_config.py]"]
  node_audit["Vector-store audit"]
end

node_user(("Questioner"))
node_pdfs["Bank report PDFs"]
node_ollama["Ollama LLM"]

node_user -->|"asks question"| node_answer
node_pdfs -->|"provides PDFs"| node_extract
node_extract -->|"writes pages"| node_pages
node_pages -->|"reads pages"| node_chunker
node_chunker -->|"writes chunks"| node_chunks
node_chunks -->|"loads chunks"| node_embedder
node_embedder -->|"encodes passages"| node_e5
node_embedder -->|"indexes chunks"| node_chroma
node_retriever -->|"encodes queries"| node_e5
node_retriever -->|"queries and reads"| node_chroma
node_answer -->|"searches passages"| node_retriever
node_answer -->|"sends context"| node_ollama
node_answer -->|"returns citations"| node_response
node_retrieval_eval -->|"evaluates vectors"| node_retriever
node_benchmark -->|"loads settings"| node_model_config
node_benchmark -->|"builds and queries"| node_chroma
node_audit -->|"checks collection"| node_chroma
node_mcp -.->|"may expose search"| node_retriever

click node_extract "https://github.com/abdessamadr/bank-rag-mcp/blob/main/extract_pdfs.py"
click node_chunker "https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/chunking/chunker.py"
click node_embedder "https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/ingestion/embedder.py"
click node_chroma "https://github.com/abdessamadr/bank-rag-mcp/tree/main/data"
click node_retriever "https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/retrieval/retriever.py"
click node_answer "https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/generation/answer_generator.py"
click node_response "https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/generation/answer_generator.py"
click node_retrieval_eval "https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/retrieval/evaluate_retriever.py"
click node_benchmark "https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/evaluation/benchmark_embeddings.py"
click node_model_config "https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/evaluation/model_config.py"
click node_audit "https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/audit/audit_vectorstore.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_extract,node_pages,node_chunker,node_chunks toneBlue
class node_embedder,node_e5,node_chroma,node_retriever toneAmber
class node_answer,node_response,node_mcp toneMint
class node_retrieval_eval,node_benchmark,node_model_config,node_audit toneRose
class node_user,node_pdfs,node_ollama toneIndigo
```

## Components

### Document ingestion

- [PDF extraction](https://github.com/abdessamadr/bank-rag-mcp/blob/main/extract_pdfs.py): `extract_pdfs.py`
- **Extracted pages**
- [Page chunking](https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/chunking/chunker.py): `src/chunking/chunker.py`
- **Page-aware chunks**

### Search and storage

- [Embedding indexer](https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/ingestion/embedder.py): `src/ingestion/embedder.py`
- **E5 embeddings**
- [Chroma vector store](https://github.com/abdessamadr/bank-rag-mcp/tree/main/data): `data`
- [Hybrid retriever](https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/retrieval/retriever.py): `src/retrieval/retriever.py`

### Answer generation

- [Answer generator](https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/generation/answer_generator.py): `src/generation/answer_generator.py`
- [Cited answer](https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/generation/answer_generator.py): `src/generation/answer_generator.py`
- **MCP search server**

### Evaluation and audit

- [Retriever evaluation](https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/retrieval/evaluate_retriever.py): `src/retrieval/evaluate_retriever.py`
- [Embedding benchmark](https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/evaluation/benchmark_embeddings.py): `src/evaluation/benchmark_embeddings.py`
- [Model configurations](https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/evaluation/model_config.py): `src/evaluation/model_config.py`
- [Vector-store audit](https://github.com/abdessamadr/bank-rag-mcp/blob/main/src/audit/audit_vectorstore.py): `src/audit/audit_vectorstore.py`

### Other components

- **Questioner**
- **Bank report PDFs**
- **Ollama LLM**

## Connections

- Questioner → Answer generator: asks question (evidence: `src/generation/answer_generator.py`)
- Bank report PDFs → PDF extraction: provides PDFs (evidence: `extract_pdfs.py`)
- PDF extraction → Extracted pages: writes pages (evidence: `extract_pdfs.py`)
- Extracted pages → Page chunking: reads pages (evidence: `src/chunking/chunker.py`)
- Page chunking → Page-aware chunks: writes chunks (evidence: `src/chunking/chunker.py`)
- Page-aware chunks → Embedding indexer: loads chunks (evidence: `src/ingestion/embedder.py`)
- Embedding indexer → E5 embeddings: encodes passages (evidence: `src/ingestion/embedder.py`)
- Embedding indexer → Chroma vector store: indexes chunks (evidence: `src/ingestion/embedder.py`)
- Hybrid retriever → E5 embeddings: encodes queries (evidence: `src/retrieval/retriever.py`)
- Hybrid retriever → Chroma vector store: queries and reads (evidence: `src/retrieval/retriever.py`)
- Answer generator → Hybrid retriever: searches passages (evidence: `src/generation/answer_generator.py`)
- Answer generator → Ollama LLM: sends context (evidence: `src/generation/answer_generator.py`)
- Answer generator → Cited answer: returns citations (evidence: `src/generation/answer_generator.py`)
- Retriever evaluation → Hybrid retriever: evaluates vectors (evidence: `src/retrieval/evaluate_retriever.py`)
- Embedding benchmark → Model configurations: loads settings (evidence: `src/evaluation/benchmark_embeddings.py`)
- Embedding benchmark → Chroma vector store: builds and queries (evidence: `src/evaluation/benchmark_embeddings.py`)
- Vector-store audit → Chroma vector store: checks collection (evidence: `src/audit/audit_vectorstore.py`)
- MCP search server → Hybrid retriever: may expose search