# sanskrutishah14/tao-fin-capstone architecture

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

- Interactive diagram: https://gitdiagram.com/sanskrutishah14/tao-fin-capstone
- Repository: https://github.com/sanskrutishah14/tao-fin-capstone

## Overview

TAO-Fin is a financial question-answering API. Users submit a question; the TAO orchestrator classifies it, retrieves filing evidence, may use deterministic financial calculations or an LLM, and verifies the answer before returning it. A separate company-sync workflow ingests SEC filings and market data for indexing and lookup. The graph preserves the README’s documented retrieval, parsing, market-data, and FinanceBench capabilities; relationships involving unsampled implementations are cited to the README rather than inferred from names.

Main entry points: [`backend/app/main.py`](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/services/tao_pipeline.py`](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/tao_pipeline.py) (TAO orchestrator), [`backend/app/services/company_service.py`](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/company_service.py) (Company sync), [`backend/app/services/hybrid_retriever.py`](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/hybrid_retriever.py) (Hybrid retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_api["FastAPI application<br/>[main.py]"]
  node_analyze["Analysis endpoint<br/>[analyze.py]"]
  node_tao["TAO orchestrator<br/>[tao_pipeline.py]"]
  node_controller["TAO controller<br/>[tao_controller.py]"]
  node_companyroute["Company routes<br/>[companies.py]"]
  node_marketroute["Market routes<br/>[market.py]"]
end

subgraph group_ingest["Filing and market data"]
  node_companyservice["Company sync<br/>[company_service.py]"]
  node_sec["SEC filing client<br/>[sec_client.py]"]
  node_secparser["Filing parser<br/>[sec_parser.py]"]
  node_chunker["Document chunker<br/>[chunker.py]"]
  node_tableparser["Table extractor<br/>[table_parser.py]"]
  node_marketdata["Market data<br/>[market_data.py]"]
  node_store[("Finance database<br/>[models.py]")]
end

subgraph group_retrieval["Evidence retrieval"]
  node_rag["RAG pipeline<br/>[rag_pipeline.py]"]
  node_hybrid["Hybrid retrieval"]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
  node_vector[("FAISS vector store<br/>[vector_store.py]")]
  node_bm25[("BM25 index<br/>[bm25_index.py]")]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
end

subgraph group_reasoning["Reasoning and verification"]
  node_query["Query analyzer<br/>[query_analyzer.py]"]
  node_metrics["Metrics resolver"]
  node_calculator["Calculator<br/>[calculator.py]"]
  node_llmclient["Ollama client<br/>[ollama_client.py]"]
  node_verifier["Answer verifier<br/>[verifier.py]"]
end

subgraph group_benchmark["Benchmark evaluation"]
  node_evaluator["FinanceBench evaluator"]
end

node_user(("Questioner"))
node_yahoo["Yahoo Finance"]
node_ollama["Ollama service"]
node_financebench["FinanceBench dataset"]

node_user -->|"submits question"| node_api
node_api -->|"routes request"| node_analyze
node_analyze -->|"runs analysis"| node_tao
node_tao -->|"classifies query"| node_query
node_tao -->|"requests evidence"| node_rag
node_rag -->|"retrieves evidence"| node_hybrid
node_hybrid -->|"embeds query"| node_embeddings
node_hybrid -->|"searches vectors"| node_vector
node_hybrid -->|"searches keywords"| node_bm25
node_hybrid -->|"reranks candidates"| node_reranker
node_tao -->|"resolves metrics"| node_metrics
node_metrics -->|"computes ratios"| node_calculator
node_tao -->|"generates answer"| node_llmclient
node_llmclient -->|"sends prompt"| node_ollama
node_tao -->|"checks answer"| node_verifier
node_tao -->|"chooses next action"| node_controller
node_controller -.->|"expands retrieval"| node_rag
node_controller -.->|"requests revision"| node_llmclient
node_companyroute -->|"syncs company"| node_companyservice
node_companyservice -->|"downloads filings"| node_sec
node_companyservice -->|"parses filings"| node_secparser
node_companyservice -->|"persists records"| node_store
node_companyservice -->|"fetches company data"| node_yahoo
node_marketroute -->|"requests market data"| node_marketdata
node_marketdata -->|"fetches quotes"| node_yahoo
node_api -->|"loads filing records"| node_store
node_api -->|"chunks filing text"| node_chunker
node_api -->|"builds embeddings"| node_embeddings
node_api -->|"builds vector index"| node_vector
node_api -->|"builds lexical index"| node_bm25
node_api -->|"extracts table chunks"| node_tableparser
node_financebench -->|"supplies benchmark"| node_evaluator
node_evaluator -->|"evaluates answers"| node_tao

click node_api "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/main.py"
click node_analyze "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/routes/analyze.py"
click node_tao "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/tao_pipeline.py"
click node_controller "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/tao_controller.py"
click node_companyroute "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/routes/companies.py"
click node_companyservice "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/company_service.py"
click node_sec "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/sec_client.py"
click node_secparser "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/sec_parser.py"
click node_chunker "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/chunker.py"
click node_tableparser "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/table_parser.py"
click node_marketroute "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/routes/market.py"
click node_marketdata "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/market_data.py"
click node_store "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/db/models.py"
click node_rag "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/rag_pipeline.py"
click node_hybrid "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/hybrid_retriever.py"
click node_embeddings "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/embeddings.py"
click node_vector "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/vector_store.py"
click node_bm25 "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/bm25_index.py"
click node_reranker "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/reranker.py"
click node_query "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/query_analyzer.py"
click node_metrics "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/metrics_resolver.py"
click node_calculator "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/calculator.py"
click node_llmclient "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/ollama_client.py"
click node_verifier "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/verifier.py"
click node_evaluator "https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/evaluation/financebench_evaluator.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_analyze,node_tao,node_controller,node_companyroute,node_marketroute toneBlue
class node_companyservice,node_sec,node_secparser,node_chunker,node_tableparser,node_marketdata,node_store toneAmber
class node_rag,node_hybrid,node_embeddings,node_vector,node_bm25,node_reranker toneMint
class node_query,node_metrics,node_calculator,node_llmclient,node_verifier toneRose
class node_evaluator,node_user,node_yahoo,node_ollama,node_financebench toneIndigo
```

## Components

### API and orchestration

- [FastAPI application](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/main.py): `backend/app/main.py`
- [Analysis endpoint](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/routes/analyze.py): `backend/app/routes/analyze.py`
- [TAO orchestrator](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/tao_pipeline.py): `backend/app/services/tao_pipeline.py`
- [TAO controller](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/tao_controller.py): `backend/app/services/tao_controller.py`
- [Company routes](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/routes/companies.py): `backend/app/routes/companies.py`
- [Market routes](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/routes/market.py): `backend/app/routes/market.py`

### Filing and market data

- [Company sync](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/company_service.py): `backend/app/services/company_service.py`
- [SEC filing client](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/sec_client.py): `backend/app/services/sec_client.py`
- [Filing parser](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/sec_parser.py): `backend/app/services/sec_parser.py`
- [Document chunker](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/chunker.py): `backend/app/services/chunker.py`
- [Table extractor](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/table_parser.py): `backend/app/services/table_parser.py`
- [Market data](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/market_data.py): `backend/app/services/market_data.py`
- [Finance database](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/db/models.py): `backend/app/db/models.py`

### Evidence retrieval

- [RAG pipeline](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/rag_pipeline.py): `backend/app/services/rag_pipeline.py`
- [Hybrid retrieval](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/hybrid_retriever.py): `backend/app/services/hybrid_retriever.py`
- [Embeddings](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/embeddings.py): `backend/app/services/embeddings.py`
- [FAISS vector store](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/vector_store.py): `backend/app/services/vector_store.py`
- [BM25 index](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/bm25_index.py): `backend/app/services/bm25_index.py`
- [Cross-encoder reranker](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/reranker.py): `backend/app/services/reranker.py`

### Reasoning and verification

- [Query analyzer](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/query_analyzer.py): `backend/app/services/query_analyzer.py`
- [Metrics resolver](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/metrics_resolver.py): `backend/app/services/metrics_resolver.py`
- [Calculator](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/calculator.py): `backend/app/services/calculator.py`
- [Ollama client](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/ollama_client.py): `backend/app/services/ollama_client.py`
- [Answer verifier](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/backend/app/services/verifier.py): `backend/app/services/verifier.py`

### Benchmark evaluation

- [FinanceBench evaluator](https://github.com/sanskrutishah14/tao-fin-capstone/blob/main/evaluation/financebench_evaluator.py): `evaluation/financebench_evaluator.py`

### Other components

- **Questioner**
- **Yahoo Finance**
- **Ollama service**
- **FinanceBench dataset**

## Connections

- Questioner → FastAPI application: submits question (evidence: `README.md`)
- FastAPI application → Analysis endpoint: routes request (evidence: `backend/app/main.py`)
- Analysis endpoint → TAO orchestrator: runs analysis (evidence: `README.md`)
- TAO orchestrator → Query analyzer: classifies query (evidence: `README.md`)
- TAO orchestrator → RAG pipeline: requests evidence (evidence: `backend/app/services/tao_pipeline.py`)
- RAG pipeline → Hybrid retrieval: retrieves evidence (evidence: `backend/app/services/rag_pipeline.py`)
- Hybrid retrieval → Embeddings: embeds query (evidence: `backend/app/services/hybrid_retriever.py`)
- Hybrid retrieval → FAISS vector store: searches vectors (evidence: `backend/app/services/hybrid_retriever.py`)
- Hybrid retrieval → BM25 index: searches keywords (evidence: `README.md`)
- Hybrid retrieval → Cross-encoder reranker: reranks candidates (evidence: `backend/app/services/hybrid_retriever.py`)
- TAO orchestrator → Metrics resolver: resolves metrics (evidence: `backend/app/services/tao_pipeline.py`)
- Metrics resolver → Calculator: computes ratios (evidence: `backend/app/services/metrics_resolver.py`)
- TAO orchestrator → Ollama client: generates answer (evidence: `README.md`)
- Ollama client → Ollama service: sends prompt (evidence: `backend/app/services/ollama_client.py`)
- TAO orchestrator → Answer verifier: checks answer (evidence: `README.md`)
- TAO orchestrator → TAO controller: chooses next action (evidence: `backend/app/services/tao_pipeline.py`)
- TAO controller → RAG pipeline: expands retrieval (evidence: `README.md`)
- TAO controller → Ollama client: requests revision (evidence: `README.md`)
- Company routes → Company sync: syncs company (evidence: `backend/app/routes/companies.py`)
- Company sync → SEC filing client: downloads filings (evidence: `README.md`)
- Company sync → Filing parser: parses filings (evidence: `README.md`)
- Company sync → Finance database: persists records (evidence: `backend/app/services/company_service.py`)
- Company sync → Yahoo Finance: fetches company data (evidence: `README.md`)
- Market routes → Market data: requests market data (evidence: `backend/app/routes/market.py`)
- Market data → Yahoo Finance: fetches quotes (evidence: `README.md`)
- FastAPI application → Finance database: loads filing records (evidence: `backend/app/main.py`)
- FastAPI application → Document chunker: chunks filing text (evidence: `backend/app/main.py`)
- FastAPI application → Embeddings: builds embeddings (evidence: `backend/app/main.py`)
- FastAPI application → FAISS vector store: builds vector index (evidence: `backend/app/main.py`)
- FastAPI application → BM25 index: builds lexical index (evidence: `backend/app/main.py`)
- FastAPI application → Table extractor: extracts table chunks (evidence: `backend/app/main.py`)
- FinanceBench dataset → FinanceBench evaluator: supplies benchmark (evidence: `README.md`)
- FinanceBench evaluator → TAO orchestrator: evaluates answers (evidence: `README.md`)
