# mayankpuvvala/financial_rag architecture

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

- Interactive diagram: https://gitdiagram.com/mayankpuvvala/financial_rag
- Repository: https://github.com/mayankpuvvala/financial_rag

## Overview

Financial RAG answers questions about SEC 10-K filings with grounded, numbered citations. A question enters through the API or Python/CLI interface, is classified and resolved (including on-demand filing ingestion), then follows direct retrieval or multi-document/temporal decomposition, retrieval, and answer generation or synthesis. Filing ingestion downloads, parses, chunks, embeds, and indexes documents. The README documents these major capabilities; several implementation details are unsampled, so uncertain connections are omitted.

Main entry points: [`retrieval/retriever.py`](https://github.com/mayankpuvvala/financial_rag/blob/main/retrieval/retriever.py) (Hybrid retriever), [`ingestion/auto_ingest.py`](https://github.com/mayankpuvvala/financial_rag/blob/main/ingestion/auto_ingest.py) (On-demand indexing), [`generation/synthesizer.py`](https://github.com/mayankpuvvala/financial_rag/blob/main/generation/synthesizer.py) (Multi-query synthesizer), [`query.py`](https://github.com/mayankpuvvala/financial_rag/blob/main/query.py) (Query pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces"]
  node_api["HTTP API<br/>[app.py]"]
  node_query["Query pipeline<br/>[query.py]"]
end

subgraph group_routing["Query routing"]
  node_resolver["Company resolver<br/>[resolver.py]"]
  node_classifier["Query classifier<br/>[classifier.py]"]
  node_decomposer["Query decomposer<br/>[decomposer.py]"]
end

subgraph group_ingestion["Filing ingestion"]
  node_registry["SEC ticker registry<br/>[registry.py]"]
  node_autoingest["On-demand indexing<br/>[auto_ingest.py]"]
  node_downloader["Filing downloader<br/>[downloader.py]"]
  node_parser["Filing parser<br/>[parser.py]"]
  node_chunker["Parent-child chunker<br/>[chunker.py]"]
end

subgraph group_retrieval["Retrieval and indexing"]
  node_embedder["Embedding indexer<br/>[embedder.py]"]
  node_retriever["Hybrid retriever<br/>[retriever.py]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
  node_parentstore["Parent section store<br/>[parent_store.py]"]
  node_vectorstore[("Qdrant collections<br/>[vector_store.py]")]
end

subgraph group_answers["Answer generation"]
  node_generator["Cited answer generator<br/>[generator.py]"]
  node_synthesizer["Multi-query synthesizer<br/>[synthesizer.py]"]
end

node_user(("Questioner"))
node_config["Settings<br/>[config.py]"]
node_models["Domain models<br/>[models.py]"]
node_sec["SEC EDGAR"]
node_groq["Groq LLM"]
node_answer["Cited answer"]

node_user -->|"asks via HTTP"| node_api
node_user -->|"asks via CLI"| node_query
node_api -->|"invokes"| node_query
node_query -->|"classifies and resolves"| node_resolver
node_resolver -->|"classifies"| node_classifier
node_resolver -->|"resolves ticker"| node_registry
node_resolver -->|"ensures indexed"| node_autoingest
node_registry -->|"looks up tickers"| node_sec
node_downloader -->|"downloads filings"| node_sec
node_autoingest -->|"fetches filing"| node_downloader
node_autoingest -->|"parses filing"| node_parser
node_autoingest -->|"chunks sections"| node_chunker
node_autoingest -->|"indexes chunks"| node_embedder
node_downloader -->|"feeds filing records"| node_parser
node_parser -->|"produces sections"| node_chunker
node_chunker -->|"produces chunks"| node_embedder
node_embedder -->|"upserts vectors"| node_vectorstore
node_query -->|"retrieves directly"| node_retriever
node_query -->|"handles multi-year queries"| node_synthesizer
node_synthesizer -->|"decomposes queries"| node_decomposer
node_synthesizer -->|"retrieves per question"| node_retriever
node_synthesizer -->|"generates sub-answers"| node_generator
node_retriever -->|"encodes queries"| node_embedder
node_retriever -->|"hybrid searches"| node_vectorstore
node_retriever -->|"reranks matches"| node_reranker
node_retriever -->|"loads parent text"| node_parentstore
node_retriever -->|"supplies context"| node_generator
node_generator -->|"requests completion"| node_groq
node_classifier -->|"classifies question"| node_groq
node_decomposer -->|"decomposes question"| node_groq
node_generator -->|"returns citations"| node_answer
node_synthesizer -->|"returns synthesis"| node_answer

click node_api "https://github.com/mayankpuvvala/financial_rag/blob/main/api/app.py"
click node_query "https://github.com/mayankpuvvala/financial_rag/blob/main/query.py"
click node_config "https://github.com/mayankpuvvala/financial_rag/blob/main/config.py"
click node_models "https://github.com/mayankpuvvala/financial_rag/blob/main/models.py"
click node_resolver "https://github.com/mayankpuvvala/financial_rag/blob/main/routing/resolver.py"
click node_classifier "https://github.com/mayankpuvvala/financial_rag/blob/main/routing/classifier.py"
click node_decomposer "https://github.com/mayankpuvvala/financial_rag/blob/main/routing/decomposer.py"
click node_registry "https://github.com/mayankpuvvala/financial_rag/blob/main/ingestion/registry.py"
click node_autoingest "https://github.com/mayankpuvvala/financial_rag/blob/main/ingestion/auto_ingest.py"
click node_downloader "https://github.com/mayankpuvvala/financial_rag/blob/main/ingestion/downloader.py"
click node_parser "https://github.com/mayankpuvvala/financial_rag/blob/main/ingestion/parser.py"
click node_chunker "https://github.com/mayankpuvvala/financial_rag/blob/main/ingestion/chunker.py"
click node_embedder "https://github.com/mayankpuvvala/financial_rag/blob/main/ingestion/embedder.py"
click node_retriever "https://github.com/mayankpuvvala/financial_rag/blob/main/retrieval/retriever.py"
click node_reranker "https://github.com/mayankpuvvala/financial_rag/blob/main/retrieval/reranker.py"
click node_parentstore "https://github.com/mayankpuvvala/financial_rag/blob/main/retrieval/parent_store.py"
click node_vectorstore "https://github.com/mayankpuvvala/financial_rag/blob/main/retrieval/vector_store.py"
click node_generator "https://github.com/mayankpuvvala/financial_rag/blob/main/generation/generator.py"
click node_synthesizer "https://github.com/mayankpuvvala/financial_rag/blob/main/generation/synthesizer.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_api,node_query toneBlue
class node_resolver,node_classifier,node_decomposer toneAmber
class node_registry,node_autoingest,node_downloader,node_parser,node_chunker toneMint
class node_embedder,node_retriever,node_reranker,node_parentstore,node_vectorstore toneRose
class node_generator,node_synthesizer,node_user,node_models,node_sec,node_groq,node_answer toneIndigo
class node_config toneTeal
```

## Components

### Interfaces

- [HTTP API](https://github.com/mayankpuvvala/financial_rag/blob/main/api/app.py): `api/app.py`
- [Query pipeline](https://github.com/mayankpuvvala/financial_rag/blob/main/query.py): `query.py`

### Query routing

- [Company resolver](https://github.com/mayankpuvvala/financial_rag/blob/main/routing/resolver.py): `routing/resolver.py`
- [Query classifier](https://github.com/mayankpuvvala/financial_rag/blob/main/routing/classifier.py): `routing/classifier.py`
- [Query decomposer](https://github.com/mayankpuvvala/financial_rag/blob/main/routing/decomposer.py): `routing/decomposer.py`

### Filing ingestion

- [SEC ticker registry](https://github.com/mayankpuvvala/financial_rag/blob/main/ingestion/registry.py): `ingestion/registry.py`
- [On-demand indexing](https://github.com/mayankpuvvala/financial_rag/blob/main/ingestion/auto_ingest.py): `ingestion/auto_ingest.py`
- [Filing downloader](https://github.com/mayankpuvvala/financial_rag/blob/main/ingestion/downloader.py): `ingestion/downloader.py`
- [Filing parser](https://github.com/mayankpuvvala/financial_rag/blob/main/ingestion/parser.py): `ingestion/parser.py`
- [Parent-child chunker](https://github.com/mayankpuvvala/financial_rag/blob/main/ingestion/chunker.py): `ingestion/chunker.py`

### Retrieval and indexing

- [Embedding indexer](https://github.com/mayankpuvvala/financial_rag/blob/main/ingestion/embedder.py): `ingestion/embedder.py`
- [Hybrid retriever](https://github.com/mayankpuvvala/financial_rag/blob/main/retrieval/retriever.py): `retrieval/retriever.py`
- [Cross-encoder reranker](https://github.com/mayankpuvvala/financial_rag/blob/main/retrieval/reranker.py): `retrieval/reranker.py`
- [Parent section store](https://github.com/mayankpuvvala/financial_rag/blob/main/retrieval/parent_store.py): `retrieval/parent_store.py`
- [Qdrant collections](https://github.com/mayankpuvvala/financial_rag/blob/main/retrieval/vector_store.py): `retrieval/vector_store.py`

### Answer generation

- [Cited answer generator](https://github.com/mayankpuvvala/financial_rag/blob/main/generation/generator.py): `generation/generator.py`
- [Multi-query synthesizer](https://github.com/mayankpuvvala/financial_rag/blob/main/generation/synthesizer.py): `generation/synthesizer.py`

### Other components

- **Questioner**
- [Settings](https://github.com/mayankpuvvala/financial_rag/blob/main/config.py): `config.py`
- [Domain models](https://github.com/mayankpuvvala/financial_rag/blob/main/models.py): `models.py`
- **SEC EDGAR**
- **Groq LLM**
- **Cited answer**

## Connections

- Questioner → HTTP API: asks via HTTP (evidence: `README.md`)
- Questioner → Query pipeline: asks via CLI (evidence: `README.md`)
- HTTP API → Query pipeline: invokes (evidence: `api/app.py`)
- Query pipeline → Company resolver: classifies and resolves (evidence: `query.py`)
- Company resolver → Query classifier: classifies (evidence: `routing/resolver.py`)
- Company resolver → SEC ticker registry: resolves ticker (evidence: `routing/resolver.py`)
- Company resolver → On-demand indexing: ensures indexed (evidence: `routing/resolver.py`)
- SEC ticker registry → SEC EDGAR: looks up tickers (evidence: `README.md`)
- Filing downloader → SEC EDGAR: downloads filings (evidence: `README.md`)
- On-demand indexing → Filing downloader: fetches filing (evidence: `ingestion/auto_ingest.py`)
- On-demand indexing → Filing parser: parses filing (evidence: `ingestion/auto_ingest.py`)
- On-demand indexing → Parent-child chunker: chunks sections (evidence: `ingestion/auto_ingest.py`)
- On-demand indexing → Embedding indexer: indexes chunks (evidence: `ingestion/auto_ingest.py`)
- Filing downloader → Filing parser: feeds filing records (evidence: `README.md`)
- Filing parser → Parent-child chunker: produces sections (evidence: `README.md`)
- Parent-child chunker → Embedding indexer: produces chunks (evidence: `README.md`)
- Embedding indexer → Qdrant collections: upserts vectors (evidence: `ingestion/embedder.py`)
- Query pipeline → Hybrid retriever: retrieves directly (evidence: `query.py`)
- Query pipeline → Multi-query synthesizer: handles multi-year queries (evidence: `query.py`)
- Multi-query synthesizer → Query decomposer: decomposes queries (evidence: `generation/synthesizer.py`)
- Multi-query synthesizer → Hybrid retriever: retrieves per question (evidence: `generation/synthesizer.py`)
- Multi-query synthesizer → Cited answer generator: generates sub-answers (evidence: `generation/synthesizer.py`)
- Hybrid retriever → Embedding indexer: encodes queries (evidence: `retrieval/retriever.py`)
- Hybrid retriever → Qdrant collections: hybrid searches (evidence: `retrieval/retriever.py`)
- Hybrid retriever → Cross-encoder reranker: reranks matches (evidence: `retrieval/retriever.py`)
- Hybrid retriever → Parent section store: loads parent text (evidence: `retrieval/retriever.py`)
- Hybrid retriever → Cited answer generator: supplies context (evidence: `README.md`)
- Cited answer generator → Groq LLM: requests completion (evidence: `generation/generator.py`)
- Query classifier → Groq LLM: classifies question (evidence: `README.md`)
- Query decomposer → Groq LLM: decomposes question (evidence: `README.md`)
- Cited answer generator → Cited answer: returns citations (evidence: `README.md`)
- Multi-query synthesizer → Cited answer: returns synthesis (evidence: `generation/synthesizer.py`)
