# rojasantino/financial-document-rag architecture

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

- Interactive diagram: https://gitdiagram.com/rojasantino/financial-document-rag
- Repository: https://github.com/rojasantino/financial-document-rag

## Overview

This is a financial-document RAG application: users upload PDFs, which are parsed page by page, chunked, embedded, and indexed; questions are embedded, retrieved, reranked, and answered from a grounded prompt with page citations. The graph keeps upload and question handling as separate domain flows and includes configuration and persisted storage. Backend calls are evidenced by the sampled source; the README documents the frontend/backend relationship and major retrieval stages. The frontend implementation was read but its API wiring was not shown, so that connection is documented rather than source-verified.

Main entry points: [`app/services/rag_pipeline.py`](https://github.com/rojasantino/financial-document-rag/blob/main/app/services/rag_pipeline.py) (RAG answer pipeline), [`app/config.py`](https://github.com/rojasantino/financial-document-rag/blob/main/app/config.py) (Application settings), [`app/services/ingest.py`](https://github.com/rojasantino/financial-document-rag/blob/main/app/services/ingest.py) (Ingestion pipeline), [`app/api/upload.py`](https://github.com/rojasantino/financial-document-rag/blob/main/app/api/upload.py) (Upload endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_frontend["Streamlit UI<br/>[app.py]"]
end

subgraph group_api["API workflows"]
  node_backend["FastAPI app<br/>[main.py]"]
  node_upload["Upload endpoint<br/>[upload.py]"]
  node_ask["Question endpoint<br/>[chat.py]"]
end

subgraph group_ingestion["Document ingestion"]
  node_ingest["Ingestion pipeline<br/>[ingest.py]"]
  node_pdf["PDF extraction<br/>[pdf_loader.py]"]
  node_chunker["Text chunking<br/>[chunker.py]"]
end

subgraph group_retrieval["Retrieval and answering"]
  node_embedding["Text embeddings<br/>[embeddings.py]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
  node_rag["RAG answer pipeline<br/>[rag_pipeline.py]"]
  node_llm["LLM provider adapter<br/>[llm.py]"]
end

subgraph group_support["Configuration and storage"]
  node_vector[("FAISS vector store<br/>[vector_store.py]")]
  node_settings["Application settings<br/>[config.py]"]
  node_documents["Uploaded PDFs"]
  node_indexfiles[("Persisted index")]
end

node_user(("User"))
node_anthropic["Anthropic API"]
node_openai["OpenAI API"]

node_user -->|"uses"| node_frontend
node_frontend -->|"uses API"| node_backend
node_backend -->|"registers route"| node_upload
node_backend -->|"registers route"| node_ask
node_upload -->|"indexes PDF"| node_ingest
node_upload -->|"writes PDF"| node_documents
node_ingest -->|"extracts pages"| node_pdf
node_ingest -->|"creates chunks"| node_chunker
node_ingest -->|"embeds chunks"| node_embedding
node_ingest -->|"adds and saves"| node_vector
node_vector -->|"persists index"| node_indexfiles
node_ask -->|"answers question"| node_rag
node_rag -->|"embeds query"| node_embedding
node_rag -->|"searches candidates"| node_vector
node_rag -->|"reranks candidates"| node_reranker
node_rag -->|"generates answer"| node_llm
node_llm -.->|"calls provider"| node_anthropic
node_llm -.->|"calls provider"| node_openai
node_upload -->|"reads settings"| node_settings
node_chunker -->|"reads settings"| node_settings
node_embedding -->|"reads settings"| node_settings
node_reranker -->|"reads settings"| node_settings
node_llm -->|"reads settings"| node_settings
node_vector -->|"reads settings"| node_settings
node_rag -->|"reads settings"| node_settings

click node_frontend "https://github.com/rojasantino/financial-document-rag/blob/main/frontend/app.py"
click node_backend "https://github.com/rojasantino/financial-document-rag/blob/main/app/main.py"
click node_upload "https://github.com/rojasantino/financial-document-rag/blob/main/app/api/upload.py"
click node_ask "https://github.com/rojasantino/financial-document-rag/blob/main/app/api/chat.py"
click node_ingest "https://github.com/rojasantino/financial-document-rag/blob/main/app/services/ingest.py"
click node_pdf "https://github.com/rojasantino/financial-document-rag/blob/main/app/services/pdf_loader.py"
click node_chunker "https://github.com/rojasantino/financial-document-rag/blob/main/app/services/chunker.py"
click node_embedding "https://github.com/rojasantino/financial-document-rag/blob/main/app/services/embeddings.py"
click node_vector "https://github.com/rojasantino/financial-document-rag/blob/main/app/services/vector_store.py"
click node_reranker "https://github.com/rojasantino/financial-document-rag/blob/main/app/services/reranker.py"
click node_rag "https://github.com/rojasantino/financial-document-rag/blob/main/app/services/rag_pipeline.py"
click node_llm "https://github.com/rojasantino/financial-document-rag/blob/main/app/services/llm.py"
click node_settings "https://github.com/rojasantino/financial-document-rag/blob/main/app/config.py"
click node_documents "https://github.com/rojasantino/financial-document-rag/tree/main/data/documents"
click node_indexfiles "https://github.com/rojasantino/financial-document-rag/tree/main/data/vectorstore"

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_backend,node_upload,node_ask toneAmber
class node_ingest,node_pdf,node_chunker,node_anthropic,node_openai toneMint
class node_embedding,node_reranker,node_rag,node_llm toneRose
class node_vector,node_settings,node_documents,node_indexfiles toneIndigo
```

## Components

### User interface

- [Streamlit UI](https://github.com/rojasantino/financial-document-rag/blob/main/frontend/app.py): `frontend/app.py`

### API workflows

- [FastAPI app](https://github.com/rojasantino/financial-document-rag/blob/main/app/main.py): `app/main.py`
- [Upload endpoint](https://github.com/rojasantino/financial-document-rag/blob/main/app/api/upload.py): `app/api/upload.py`
- [Question endpoint](https://github.com/rojasantino/financial-document-rag/blob/main/app/api/chat.py): `app/api/chat.py`

### Document ingestion

- [Ingestion pipeline](https://github.com/rojasantino/financial-document-rag/blob/main/app/services/ingest.py): `app/services/ingest.py`
- [PDF extraction](https://github.com/rojasantino/financial-document-rag/blob/main/app/services/pdf_loader.py): `app/services/pdf_loader.py`
- [Text chunking](https://github.com/rojasantino/financial-document-rag/blob/main/app/services/chunker.py): `app/services/chunker.py`

### Retrieval and answering

- [Text embeddings](https://github.com/rojasantino/financial-document-rag/blob/main/app/services/embeddings.py): `app/services/embeddings.py`
- [Cross-encoder reranker](https://github.com/rojasantino/financial-document-rag/blob/main/app/services/reranker.py): `app/services/reranker.py`
- [RAG answer pipeline](https://github.com/rojasantino/financial-document-rag/blob/main/app/services/rag_pipeline.py): `app/services/rag_pipeline.py`
- [LLM provider adapter](https://github.com/rojasantino/financial-document-rag/blob/main/app/services/llm.py): `app/services/llm.py`

### Configuration and storage

- [FAISS vector store](https://github.com/rojasantino/financial-document-rag/blob/main/app/services/vector_store.py): `app/services/vector_store.py`
- [Application settings](https://github.com/rojasantino/financial-document-rag/blob/main/app/config.py): `app/config.py`
- [Uploaded PDFs](https://github.com/rojasantino/financial-document-rag/tree/main/data/documents): `data/documents`
- [Persisted index](https://github.com/rojasantino/financial-document-rag/tree/main/data/vectorstore): `data/vectorstore`

### Other components

- **User**
- **Anthropic API**
- **OpenAI API**

## Connections

- User → Streamlit UI: uses (evidence: `README.md`)
- Streamlit UI → FastAPI app: uses API (evidence: `README.md`)
- FastAPI app → Upload endpoint: registers route (evidence: `app/main.py`)
- FastAPI app → Question endpoint: registers route (evidence: `app/main.py`)
- Upload endpoint → Ingestion pipeline: indexes PDF (evidence: `app/api/upload.py`)
- Upload endpoint → Uploaded PDFs: writes PDF (evidence: `app/api/upload.py`)
- Ingestion pipeline → PDF extraction: extracts pages (evidence: `app/services/ingest.py`)
- Ingestion pipeline → Text chunking: creates chunks (evidence: `app/services/ingest.py`)
- Ingestion pipeline → Text embeddings: embeds chunks (evidence: `app/services/ingest.py`)
- Ingestion pipeline → FAISS vector store: adds and saves (evidence: `app/services/ingest.py`)
- FAISS vector store → Persisted index: persists index (evidence: `app/services/vector_store.py`)
- Question endpoint → RAG answer pipeline: answers question (evidence: `app/api/chat.py`)
- RAG answer pipeline → Text embeddings: embeds query (evidence: `app/services/rag_pipeline.py`)
- RAG answer pipeline → FAISS vector store: searches candidates (evidence: `app/services/rag_pipeline.py`)
- RAG answer pipeline → Cross-encoder reranker: reranks candidates (evidence: `app/services/rag_pipeline.py`)
- RAG answer pipeline → LLM provider adapter: generates answer (evidence: `app/services/rag_pipeline.py`)
- LLM provider adapter → Anthropic API: calls provider (evidence: `app/services/llm.py`)
- LLM provider adapter → OpenAI API: calls provider (evidence: `app/services/llm.py`)
- Upload endpoint → Application settings: reads settings (evidence: `app/api/upload.py`)
- Text chunking → Application settings: reads settings (evidence: `app/services/chunker.py`)
- Text embeddings → Application settings: reads settings (evidence: `app/services/embeddings.py`)
- Cross-encoder reranker → Application settings: reads settings (evidence: `app/services/reranker.py`)
- LLM provider adapter → Application settings: reads settings (evidence: `app/services/llm.py`)
- FAISS vector store → Application settings: reads settings (evidence: `app/services/vector_store.py`)
- RAG answer pipeline → Application settings: reads settings (evidence: `app/services/rag_pipeline.py`)
