# ducbao210/finsight architecture

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

- Interactive diagram: https://gitdiagram.com/ducbao210/finsight
- Repository: https://github.com/ducbao210/finsight

## Overview

FinSight is a FinanceBench-focused, evidence-grounded financial QA system. Filings are parsed and chunked into indexes; a question enters the API and runs through corrective multi-hop retrieval, evidence grading, optional calculation, cited answer generation, and citation validation. A separate two-pass evaluation capability scores retrieval, citations, and generated answers. The README documents the major workflows; source excerpts confirm API initialization and dispatch plus key retrieval and graph components. Some unsampled implementation links are omitted where source evidence is unavailable.

Main entry points: [`src/evaluation/runner.py`](https://github.com/ducbao210/finsight/blob/main/src/evaluation/runner.py) (Evaluation Runner), [`src/retrieval/hybrid.py`](https://github.com/ducbao210/finsight/blob/main/src/retrieval/hybrid.py) (Hybrid Search), [`src/main.py`](https://github.com/ducbao210/finsight/blob/main/src/main.py) (FastAPI Service), [`src/graph/nodes.py`](https://github.com/ducbao210/finsight/blob/main/src/graph/nodes.py) (Reasoning Nodes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Filing Ingestion"]
  node_parser["Filing Parser<br/>[parser.py]"]
  node_metadata["Filing Metadata<br/>[metadata.py]"]
  node_chunker["Document Chunker<br/>[chunker.py]"]
end

subgraph group_retrieval["Evidence Retrieval"]
  node_chroma[("Vector Index<br/>[dense.py]")]
  node_bm25[("Lexical Index<br/>[bm25.py]")]
  node_dense["Dense Search<br/>[dense.py]"]
  node_hybrid["Hybrid Search<br/>[hybrid.py]"]
  node_reranker["Optional Reranker<br/>[reranker.py]"]
end

subgraph group_answer["Question Answering"]
  node_api["FastAPI Service<br/>[main.py]"]
  node_workflow["CRAG Orchestrator<br/>[workflow.py]"]
  node_state["Workflow State<br/>[state.py]"]
  node_reasoning["Reasoning Nodes<br/>[nodes.py]"]
  node_prompts["Reasoning Prompts<br/>[__init__.py]"]
  node_calculation["Financial Calculations"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_runner["Evaluation Runner<br/>[runner.py]"]
  node_eval_dataset["Benchmark Dataset<br/>[dataset.py]"]
  node_retrieval_metrics["Retrieval Metrics"]
  node_citation_metrics["Citation Metrics"]
  node_generation_metrics["Generation Metrics"]
  node_reporting["Evaluation Reports<br/>[reporting.py]"]
end

subgraph group_foundation["Shared Foundation"]
  node_schemas["Request and Result Schemas<br/>[__init__.py]"]
  node_config["Configuration<br/>[configs.py]"]
end

node_user(("Questioner"))
node_actor_eval(("Benchmark Operator"))

node_user -->|"submits question"| node_api
node_api -->|"runs pipeline"| node_workflow
node_workflow -->|"dispatches steps"| node_reasoning
node_workflow -->|"uses state"| node_state
node_reasoning -->|"uses prompts"| node_prompts
node_reasoning -->|"retrieves evidence"| node_hybrid
node_hybrid -->|"fuses search"| node_dense
node_hybrid -->|"fuses search"| node_bm25
node_hybrid -.->|"optionally reranks"| node_reranker
node_dense -->|"queries vectors"| node_chroma
node_reasoning -->|"computes metrics"| node_calculation
node_api -->|"validates responses"| node_schemas
node_parser -.->|"extracts filing details"| node_metadata
node_metadata -.->|"supplies metadata"| node_chunker
node_chunker -.->|"indexes chunks"| node_chroma
node_chunker -.->|"indexes chunks"| node_bm25
node_actor_eval -->|"runs evaluation"| node_eval_runner
node_eval_runner -->|"loads questions"| node_eval_dataset
node_eval_runner -->|"scores retrieval"| node_retrieval_metrics
node_eval_runner -->|"scores citations"| node_citation_metrics
node_eval_runner -->|"scores answers"| node_generation_metrics
node_eval_runner -->|"writes reports"| node_reporting
node_api -->|"loads settings"| node_config

click node_api "https://github.com/ducbao210/finsight/blob/main/src/main.py"
click node_workflow "https://github.com/ducbao210/finsight/blob/main/src/graph/workflow.py"
click node_state "https://github.com/ducbao210/finsight/blob/main/src/graph/state.py"
click node_reasoning "https://github.com/ducbao210/finsight/blob/main/src/graph/nodes.py"
click node_prompts "https://github.com/ducbao210/finsight/blob/main/src/core/prompts/__init__.py"
click node_calculation "https://github.com/ducbao210/finsight/blob/main/src/calculation/financial_metrics.py"
click node_schemas "https://github.com/ducbao210/finsight/blob/main/src/schemas/__init__.py"
click node_parser "https://github.com/ducbao210/finsight/blob/main/src/ingestion/parser.py"
click node_metadata "https://github.com/ducbao210/finsight/blob/main/src/ingestion/metadata.py"
click node_chunker "https://github.com/ducbao210/finsight/blob/main/src/ingestion/chunker.py"
click node_chroma "https://github.com/ducbao210/finsight/blob/main/src/retrieval/dense.py"
click node_bm25 "https://github.com/ducbao210/finsight/blob/main/src/retrieval/bm25.py"
click node_dense "https://github.com/ducbao210/finsight/blob/main/src/retrieval/dense.py"
click node_hybrid "https://github.com/ducbao210/finsight/blob/main/src/retrieval/hybrid.py"
click node_reranker "https://github.com/ducbao210/finsight/blob/main/src/retrieval/reranker.py"
click node_eval_runner "https://github.com/ducbao210/finsight/blob/main/src/evaluation/runner.py"
click node_eval_dataset "https://github.com/ducbao210/finsight/blob/main/src/evaluation/dataset.py"
click node_retrieval_metrics "https://github.com/ducbao210/finsight/blob/main/src/evaluation/retrieval_metrics.py"
click node_citation_metrics "https://github.com/ducbao210/finsight/blob/main/src/evaluation/citation_metrics.py"
click node_generation_metrics "https://github.com/ducbao210/finsight/blob/main/src/evaluation/generation_metrics.py"
click node_reporting "https://github.com/ducbao210/finsight/blob/main/src/evaluation/reporting.py"
click node_config "https://github.com/ducbao210/finsight/blob/main/src/core/configs.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_parser,node_metadata,node_chunker toneBlue
class node_chroma,node_bm25,node_dense,node_hybrid,node_reranker toneAmber
class node_api,node_workflow,node_state,node_reasoning,node_prompts,node_calculation toneMint
class node_eval_runner,node_eval_dataset,node_retrieval_metrics,node_citation_metrics,node_generation_metrics,node_reporting toneRose
class node_schemas,node_config,node_user,node_actor_eval toneIndigo
```

## Components

### Filing Ingestion

- [Filing Parser](https://github.com/ducbao210/finsight/blob/main/src/ingestion/parser.py): `src/ingestion/parser.py`
- [Filing Metadata](https://github.com/ducbao210/finsight/blob/main/src/ingestion/metadata.py): `src/ingestion/metadata.py`
- [Document Chunker](https://github.com/ducbao210/finsight/blob/main/src/ingestion/chunker.py): `src/ingestion/chunker.py`

### Evidence Retrieval

- [Vector Index](https://github.com/ducbao210/finsight/blob/main/src/retrieval/dense.py): `src/retrieval/dense.py`
- [Lexical Index](https://github.com/ducbao210/finsight/blob/main/src/retrieval/bm25.py): `src/retrieval/bm25.py`
- [Dense Search](https://github.com/ducbao210/finsight/blob/main/src/retrieval/dense.py): `src/retrieval/dense.py`
- [Hybrid Search](https://github.com/ducbao210/finsight/blob/main/src/retrieval/hybrid.py): `src/retrieval/hybrid.py`
- [Optional Reranker](https://github.com/ducbao210/finsight/blob/main/src/retrieval/reranker.py): `src/retrieval/reranker.py`

### Question Answering

- [FastAPI Service](https://github.com/ducbao210/finsight/blob/main/src/main.py): `src/main.py`
- [CRAG Orchestrator](https://github.com/ducbao210/finsight/blob/main/src/graph/workflow.py): `src/graph/workflow.py`
- [Workflow State](https://github.com/ducbao210/finsight/blob/main/src/graph/state.py): `src/graph/state.py`
- [Reasoning Nodes](https://github.com/ducbao210/finsight/blob/main/src/graph/nodes.py): `src/graph/nodes.py`
- [Reasoning Prompts](https://github.com/ducbao210/finsight/blob/main/src/core/prompts/__init__.py): `src/core/prompts/__init__.py`
- [Financial Calculations](https://github.com/ducbao210/finsight/blob/main/src/calculation/financial_metrics.py): `src/calculation/financial_metrics.py`

### Evaluation

- [Evaluation Runner](https://github.com/ducbao210/finsight/blob/main/src/evaluation/runner.py): `src/evaluation/runner.py`
- [Benchmark Dataset](https://github.com/ducbao210/finsight/blob/main/src/evaluation/dataset.py): `src/evaluation/dataset.py`
- [Retrieval Metrics](https://github.com/ducbao210/finsight/blob/main/src/evaluation/retrieval_metrics.py): `src/evaluation/retrieval_metrics.py`
- [Citation Metrics](https://github.com/ducbao210/finsight/blob/main/src/evaluation/citation_metrics.py): `src/evaluation/citation_metrics.py`
- [Generation Metrics](https://github.com/ducbao210/finsight/blob/main/src/evaluation/generation_metrics.py): `src/evaluation/generation_metrics.py`
- [Evaluation Reports](https://github.com/ducbao210/finsight/blob/main/src/evaluation/reporting.py): `src/evaluation/reporting.py`

### Shared Foundation

- [Request and Result Schemas](https://github.com/ducbao210/finsight/blob/main/src/schemas/__init__.py): `src/schemas/__init__.py`
- [Configuration](https://github.com/ducbao210/finsight/blob/main/src/core/configs.py): `src/core/configs.py`

### Other components

- **Questioner**
- **Benchmark Operator**

## Connections

- Questioner → FastAPI Service: submits question (evidence: `README.md`)
- FastAPI Service → CRAG Orchestrator: runs pipeline (evidence: `src/main.py`)
- CRAG Orchestrator → Reasoning Nodes: dispatches steps (evidence: `src/graph/workflow.py`)
- CRAG Orchestrator → Workflow State: uses state (evidence: `src/graph/workflow.py`)
- Reasoning Nodes → Reasoning Prompts: uses prompts (evidence: `src/graph/nodes.py`)
- Reasoning Nodes → Hybrid Search: retrieves evidence (evidence: `src/graph/nodes.py`)
- Hybrid Search → Dense Search: fuses search (evidence: `src/retrieval/hybrid.py`)
- Hybrid Search → Lexical Index: fuses search (evidence: `src/retrieval/hybrid.py`)
- Hybrid Search → Optional Reranker: optionally reranks (evidence: `src/retrieval/hybrid.py`)
- Dense Search → Vector Index: queries vectors (evidence: `src/retrieval/dense.py`)
- Reasoning Nodes → Financial Calculations: computes metrics (evidence: `src/graph/nodes.py`)
- FastAPI Service → Request and Result Schemas: validates responses (evidence: `src/main.py`)
- Filing Parser → Filing Metadata: extracts filing details
- Filing Metadata → Document Chunker: supplies metadata
- Document Chunker → Vector Index: indexes chunks (evidence: `README.md`)
- Document Chunker → Lexical Index: indexes chunks (evidence: `README.md`)
- Benchmark Operator → Evaluation Runner: runs evaluation (evidence: `README.md`)
- Evaluation Runner → Benchmark Dataset: loads questions (evidence: `src/evaluation/runner.py`)
- Evaluation Runner → Retrieval Metrics: scores retrieval (evidence: `src/evaluation/runner.py`)
- Evaluation Runner → Citation Metrics: scores citations (evidence: `src/evaluation/runner.py`)
- Evaluation Runner → Generation Metrics: scores answers (evidence: `src/evaluation/runner.py`)
- Evaluation Runner → Evaluation Reports: writes reports (evidence: `src/evaluation/__init__.py`)
- FastAPI Service → Configuration: loads settings (evidence: `src/main.py`)
