# nickr145/crag-finqa architecture

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

- Interactive diagram: https://gitdiagram.com/nickr145/crag-finqa
- Repository: https://github.com/nickr145/crag-finqa

## Overview

Financial CRAG answers FinQA financial questions through a hybrid retrieval and corrective-generation workflow. The main entry points are the FastAPI query endpoint and the CLI benchmark; both initialize the corpus, retriever, and LangGraph workflow. The graph retrieves documents, scores relevance, then refines internal context or searches SEC EDGAR before Claude generates an answer. The Streamlit demo and numeric-tolerance benchmark are additional capabilities. Edges reflect the sampled source and README; unsampled UI wiring is not inferred.

Main entry points: [`src/workflow/graph.py`](https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py) (CRAG Graph), [`app.py`](https://github.com/nickr145/crag-finqa/blob/main/app.py) (Query API), [`main.py`](https://github.com/nickr145/crag-finqa/blob/main/main.py) (CLI Benchmark), [`src/data/loader.py`](https://github.com/nickr145/crag-finqa/blob/main/src/data/loader.py) (Corpus Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_api["Query API<br/>[app.py]"]
  node_demo["Streamlit Demo<br/>[frontend.py]"]
  node_cli["CLI Benchmark<br/>[main.py]"]
end

subgraph group_corpus_retrieval["Corpus and Retrieval"]
  node_corpus["Corpus Loader<br/>[loader.py]"]
  node_parser["Financial Parser<br/>[parser.py]"]
  node_retriever["Hybrid Retriever<br/>[hybrid.py]"]
  node_edgar["EDGAR Search<br/>[sec_edgar.py]"]
end

subgraph group_crag["CRAG Workflow"]
  node_graph["CRAG Graph<br/>[graph.py]"]
  node_state["Workflow State<br/>[state.py]"]
  node_retrieve["Retrieve<br/>[graph.py]"]
  node_evaluate["Evaluate Relevance<br/>[graph.py]"]
  node_scorer["Document Scorer<br/>[scorer.py]"]
  node_route["Route Action<br/>[graph.py]"]
  node_fallback["SEC Fallback<br/>[graph.py]"]
  node_refine["Context Refinement<br/>[graph.py]"]
  node_generate["Answer Generation<br/>[graph.py]"]
end

subgraph group_evaluation["Evaluation and Settings"]
  node_metric["Numeric Tolerance<br/>[metrics.py]"]
  node_settings["Runtime Settings<br/>[settings.py]"]
end

node_user(("Questioner"))
node_finqa[("FinQA Dataset")]
node_claude["Claude API"]
node_sec["SEC EDGAR"]

node_user -->|"submits query"| node_api
node_api -->|"loads corpus"| node_corpus
node_api -->|"initializes"| node_retriever
node_api -->|"builds and invokes"| node_graph
node_demo -.->|"uses service"| node_api
node_cli -->|"loads corpus"| node_corpus
node_cli -->|"initializes"| node_retriever
node_cli -->|"builds and invokes"| node_graph
node_cli -->|"scores answer"| node_metric
node_corpus -->|"fetches records"| node_finqa
node_corpus -->|"formats records"| node_parser
node_graph -->|"uses schema"| node_state
node_graph -->|"registers node"| node_retrieve
node_graph -->|"registers node"| node_evaluate
node_graph -->|"registers routing"| node_route
node_graph -->|"registers node"| node_fallback
node_graph -->|"registers node"| node_refine
node_graph -->|"registers node"| node_generate
node_retrieve -->|"searches documents"| node_retriever
node_retrieve -->|"passes documents"| node_evaluate
node_evaluate -->|"scores documents"| node_scorer
node_evaluate -->|"sets action"| node_route
node_route -->|"routes incorrect"| node_fallback
node_route -->|"routes otherwise"| node_refine
node_fallback -->|"searches filings"| node_edgar
node_edgar -->|"queries and fetches"| node_sec
node_fallback -->|"passes context"| node_generate
node_refine -->|"passes context"| node_generate
node_generate -->|"requests answer"| node_claude
node_settings -->|"configures workflow"| node_graph
node_settings -->|"configures model"| node_scorer
node_settings -->|"configures embedding"| node_retriever

click node_api "https://github.com/nickr145/crag-finqa/blob/main/app.py"
click node_demo "https://github.com/nickr145/crag-finqa/blob/main/frontend.py"
click node_cli "https://github.com/nickr145/crag-finqa/blob/main/main.py"
click node_corpus "https://github.com/nickr145/crag-finqa/blob/main/src/data/loader.py"
click node_parser "https://github.com/nickr145/crag-finqa/blob/main/src/data/parser.py"
click node_retriever "https://github.com/nickr145/crag-finqa/blob/main/src/retrieval/hybrid.py"
click node_graph "https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py"
click node_state "https://github.com/nickr145/crag-finqa/blob/main/src/workflow/state.py"
click node_retrieve "https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py"
click node_evaluate "https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py"
click node_scorer "https://github.com/nickr145/crag-finqa/blob/main/src/evaluation/scorer.py"
click node_route "https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py"
click node_fallback "https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py"
click node_edgar "https://github.com/nickr145/crag-finqa/blob/main/src/retrieval/sec_edgar.py"
click node_refine "https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py"
click node_generate "https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py"
click node_metric "https://github.com/nickr145/crag-finqa/blob/main/src/evaluation/metrics.py"
click node_settings "https://github.com/nickr145/crag-finqa/blob/main/config/settings.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_demo,node_cli toneBlue
class node_corpus,node_parser,node_retriever,node_edgar,node_finqa toneAmber
class node_graph,node_state,node_retrieve,node_evaluate,node_scorer,node_route,node_fallback,node_refine,node_generate,node_claude toneMint
class node_metric,node_settings toneRose
class node_user,node_sec toneIndigo
```

## Components

### User Interfaces

- [Query API](https://github.com/nickr145/crag-finqa/blob/main/app.py): `app.py`
- [Streamlit Demo](https://github.com/nickr145/crag-finqa/blob/main/frontend.py): `frontend.py`
- [CLI Benchmark](https://github.com/nickr145/crag-finqa/blob/main/main.py): `main.py`

### Corpus and Retrieval

- [Corpus Loader](https://github.com/nickr145/crag-finqa/blob/main/src/data/loader.py): `src/data/loader.py`
- [Financial Parser](https://github.com/nickr145/crag-finqa/blob/main/src/data/parser.py): `src/data/parser.py`
- [Hybrid Retriever](https://github.com/nickr145/crag-finqa/blob/main/src/retrieval/hybrid.py): `src/retrieval/hybrid.py`
- [EDGAR Search](https://github.com/nickr145/crag-finqa/blob/main/src/retrieval/sec_edgar.py): `src/retrieval/sec_edgar.py`

### CRAG Workflow

- [CRAG Graph](https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py): `src/workflow/graph.py`
- [Workflow State](https://github.com/nickr145/crag-finqa/blob/main/src/workflow/state.py): `src/workflow/state.py`
- [Retrieve](https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py): `src/workflow/graph.py`
- [Evaluate Relevance](https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py): `src/workflow/graph.py`
- [Document Scorer](https://github.com/nickr145/crag-finqa/blob/main/src/evaluation/scorer.py): `src/evaluation/scorer.py`
- [Route Action](https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py): `src/workflow/graph.py`
- [SEC Fallback](https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py): `src/workflow/graph.py`
- [Context Refinement](https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py): `src/workflow/graph.py`
- [Answer Generation](https://github.com/nickr145/crag-finqa/blob/main/src/workflow/graph.py): `src/workflow/graph.py`

### Evaluation and Settings

- [Numeric Tolerance](https://github.com/nickr145/crag-finqa/blob/main/src/evaluation/metrics.py): `src/evaluation/metrics.py`
- [Runtime Settings](https://github.com/nickr145/crag-finqa/blob/main/config/settings.py): `config/settings.py`

### Other components

- **Questioner**
- **FinQA Dataset**
- **Claude API**
- **SEC EDGAR**

## Connections

- Questioner → Query API: submits query (evidence: `README.md`)
- Query API → Corpus Loader: loads corpus (evidence: `app.py`)
- Query API → Hybrid Retriever: initializes (evidence: `app.py`)
- Query API → CRAG Graph: builds and invokes (evidence: `app.py`)
- Streamlit Demo → Query API: uses service (evidence: `README.md`)
- CLI Benchmark → Corpus Loader: loads corpus (evidence: `main.py`)
- CLI Benchmark → Hybrid Retriever: initializes (evidence: `main.py`)
- CLI Benchmark → CRAG Graph: builds and invokes (evidence: `main.py`)
- CLI Benchmark → Numeric Tolerance: scores answer (evidence: `main.py`)
- Corpus Loader → FinQA Dataset: fetches records (evidence: `README.md`)
- Corpus Loader → Financial Parser: formats records (evidence: `src/data/loader.py`)
- CRAG Graph → Workflow State: uses schema (evidence: `src/workflow/graph.py`)
- CRAG Graph → Retrieve: registers node (evidence: `src/workflow/graph.py`)
- CRAG Graph → Evaluate Relevance: registers node (evidence: `src/workflow/graph.py`)
- CRAG Graph → Route Action: registers routing (evidence: `src/workflow/graph.py`)
- CRAG Graph → SEC Fallback: registers node (evidence: `src/workflow/graph.py`)
- CRAG Graph → Context Refinement: registers node (evidence: `src/workflow/graph.py`)
- CRAG Graph → Answer Generation: registers node (evidence: `src/workflow/graph.py`)
- Retrieve → Hybrid Retriever: searches documents (evidence: `src/workflow/graph.py`)
- Retrieve → Evaluate Relevance: passes documents (evidence: `src/workflow/graph.py`)
- Evaluate Relevance → Document Scorer: scores documents (evidence: `src/workflow/graph.py`)
- Evaluate Relevance → Route Action: sets action (evidence: `src/workflow/graph.py`)
- Route Action → SEC Fallback: routes incorrect (evidence: `src/workflow/graph.py`)
- Route Action → Context Refinement: routes otherwise (evidence: `src/workflow/graph.py`)
- SEC Fallback → EDGAR Search: searches filings (evidence: `src/workflow/graph.py`)
- EDGAR Search → SEC EDGAR: queries and fetches (evidence: `src/retrieval/sec_edgar.py`)
- SEC Fallback → Answer Generation: passes context (evidence: `src/workflow/graph.py`)
- Context Refinement → Answer Generation: passes context (evidence: `src/workflow/graph.py`)
- Answer Generation → Claude API: requests answer (evidence: `src/workflow/graph.py`)
- Runtime Settings → CRAG Graph: configures workflow (evidence: `src/workflow/graph.py`)
- Runtime Settings → Document Scorer: configures model (evidence: `src/evaluation/scorer.py`)
- Runtime Settings → Hybrid Retriever: configures embedding (evidence: `src/retrieval/hybrid.py`)
