# yzyazid8-web/ledger-agent architecture

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

- Interactive diagram: https://gitdiagram.com/yzyazid8-web/ledger-agent
- Repository: https://github.com/yzyazid8-web/ledger-agent
- Video tour (about a minute): https://gitdiagram.com/yzyazid8-web/ledger-agent/video

## Overview

ledger-agent is a traceable financial-report assistant for U.S. annual and quarterly filings. Users submit a question through the Next.js interface; the API streams agent steps and returns a sourced answer or abstention. The agent gathers filing passages and typed XBRL facts, may calculate from cited inputs, and verifies numerical claims before responding. Separate ingestion and evaluation branches support the product. The graph reflects README-described capabilities where implementation excerpts were unavailable; those links cite the README rather than implying unsampled code was inspected.

Main entry points: [`backend/src/ledger_agent/agent/react.py`](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/agent/react.py) (ReAct agent), [`backend/src/ledger_agent/agent/nodes.py`](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/agent/nodes.py) (Agent workflow nodes), [`backend/src/ledger_agent/retrieval`](https://github.com/yzyazid8-web/ledger-agent/tree/main/backend/src/ledger_agent/retrieval) (Hybrid filing search), [`backend/src/ledger_agent/agent/toolbox.py`](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/agent/toolbox.py) (Tool dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_ingestion["Filing and XBRL ingestion"]
end

subgraph group_retrieve["Evidence retrieval"]
  node_facts[("Typed fact store<br/>[financial_facts.py]")]
  node_retrieval["Hybrid filing search"]
  node_filters["Query filters<br/>[query_analysis.py]"]
  node_fallback["Filter relaxation<br/>[fallback.py]"]
end

subgraph group_reason["Agent reasoning"]
  node_searchtool["Filing search tool<br/>[search_filings.py]"]
  node_agent["ReAct agent<br/>[react.py]"]
  node_graphagent["Fixed-step agent<br/>[graph.py]"]
  node_nodes["Agent workflow nodes<br/>[nodes.py]"]
  node_toolbox["Tool dispatch<br/>[toolbox.py]"]
  node_calculator["Safe calculator<br/>[calculator.py]"]
  node_verify["Answer verification<br/>[verify.py]"]
  node_pipeline["Answer and trace format<br/>[pipeline.py]"]
end

subgraph group_serving["User interface"]
  node_web["Question interface<br/>[page.tsx]"]
  node_client["API client<br/>[api.ts]"]
  node_proxy["API proxy<br/>[route.ts]"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_service["Agent service<br/>[service.py]"]
  node_trace["Trace and evidence views<br/>[AgentTrace.tsx]"]
end

subgraph group_eval["Evaluation"]
  node_evaluation["Evaluation harness"]
  node_baseline["Naive RAG baseline<br/>[naive_rag.py]"]
end

node_user(("Analyst"))
node_edgar["SEC EDGAR"]
node_llm["LLM provider"]

node_user -->|"asks"| node_web
node_web -->|"submits question"| node_client
node_client -->|"sends request"| node_proxy
node_proxy -->|"forwards request"| node_api
node_api -->|"routes to"| node_service
node_service -->|"streams steps"| node_agent
node_agent -->|"formats answer"| node_pipeline
node_service -->|"builds retriever"| node_retrieval
node_service -->|"builds agent"| node_graphagent
node_ingestion -->|"fetches filings"| node_edgar
node_ingestion -->|"loads XBRL facts"| node_facts
node_ingestion -->|"indexes chunks"| node_retrieval
node_agent -->|"requests tool choices"| node_llm
node_agent -->|"dispatches tools"| node_toolbox
node_toolbox -->|"executes search"| node_searchtool
node_toolbox -->|"reads facts"| node_facts
node_toolbox -->|"evaluates calculation"| node_calculator
node_searchtool -->|"searches passages"| node_retrieval
node_retrieval -->|"extracts query entities"| node_filters
node_searchtool -->|"relaxes filters"| node_fallback
node_graphagent -->|"runs workflow"| node_nodes
node_nodes -->|"gathers passages"| node_searchtool
node_nodes -->|"looks up facts"| node_facts
node_nodes -->|"calculates values"| node_calculator
node_nodes -->|"checks answer"| node_verify
node_agent -->|"checks citations"| node_verify
node_api -->|"streams answer"| node_web
node_web -->|"renders steps"| node_trace
node_evaluation -->|"evaluates configurations"| node_agent
node_evaluation -->|"compares baseline"| node_baseline
node_baseline -->|"searches context"| node_retrieval
node_baseline -->|"generates answer"| node_llm

click node_web "https://github.com/yzyazid8-web/ledger-agent/blob/main/frontend/app/page.tsx"
click node_client "https://github.com/yzyazid8-web/ledger-agent/blob/main/frontend/lib/api.ts"
click node_proxy "https://github.com/yzyazid8-web/ledger-agent/blob/main/frontend/app/api/%5B...path%5D/route.ts"
click node_api "https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/api/main.py"
click node_service "https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/api/service.py"
click node_trace "https://github.com/yzyazid8-web/ledger-agent/blob/main/frontend/components/AgentTrace.tsx"
click node_ingestion "https://github.com/yzyazid8-web/ledger-agent/tree/main/backend/src/ledger_agent/ingestion"
click node_facts "https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/tools/financial_facts.py"
click node_retrieval "https://github.com/yzyazid8-web/ledger-agent/tree/main/backend/src/ledger_agent/retrieval"
click node_filters "https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/retrieval/query_analysis.py"
click node_fallback "https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/retrieval/fallback.py"
click node_searchtool "https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/tools/search_filings.py"
click node_agent "https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/agent/react.py"
click node_graphagent "https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/agent/graph.py"
click node_nodes "https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/agent/nodes.py"
click node_toolbox "https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/agent/toolbox.py"
click node_calculator "https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/tools/calculator.py"
click node_verify "https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/agent/verify.py"
click node_pipeline "https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/pipeline.py"
click node_evaluation "https://github.com/yzyazid8-web/ledger-agent/tree/main/backend/src/ledger_agent/evaluation"
click node_baseline "https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/baselines/naive_rag.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_ingestion toneBlue
class node_facts,node_retrieval,node_filters,node_fallback toneAmber
class node_searchtool,node_agent,node_graphagent,node_nodes,node_toolbox,node_calculator,node_verify,node_pipeline toneMint
class node_web,node_client,node_proxy,node_api,node_service,node_trace toneRose
class node_evaluation,node_baseline,node_user,node_edgar,node_llm toneIndigo
```

## Components

### Data ingestion

- [Filing and XBRL ingestion](https://github.com/yzyazid8-web/ledger-agent/tree/main/backend/src/ledger_agent/ingestion): `backend/src/ledger_agent/ingestion`

### Evidence retrieval

- [Typed fact store](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/tools/financial_facts.py): `backend/src/ledger_agent/tools/financial_facts.py`
- [Hybrid filing search](https://github.com/yzyazid8-web/ledger-agent/tree/main/backend/src/ledger_agent/retrieval): `backend/src/ledger_agent/retrieval`
- [Query filters](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/retrieval/query_analysis.py): `backend/src/ledger_agent/retrieval/query_analysis.py`
- [Filter relaxation](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/retrieval/fallback.py): `backend/src/ledger_agent/retrieval/fallback.py`

### Agent reasoning

- [Filing search tool](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/tools/search_filings.py): `backend/src/ledger_agent/tools/search_filings.py`
- [ReAct agent](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/agent/react.py): `backend/src/ledger_agent/agent/react.py`
- [Fixed-step agent](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/agent/graph.py): `backend/src/ledger_agent/agent/graph.py`
- [Agent workflow nodes](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/agent/nodes.py): `backend/src/ledger_agent/agent/nodes.py`
- [Tool dispatch](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/agent/toolbox.py): `backend/src/ledger_agent/agent/toolbox.py`
- [Safe calculator](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/tools/calculator.py): `backend/src/ledger_agent/tools/calculator.py`
- [Answer verification](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/agent/verify.py): `backend/src/ledger_agent/agent/verify.py`
- [Answer and trace format](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/pipeline.py): `backend/src/ledger_agent/pipeline.py`

### User interface

- [Question interface](https://github.com/yzyazid8-web/ledger-agent/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [API client](https://github.com/yzyazid8-web/ledger-agent/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [API proxy](https://github.com/yzyazid8-web/ledger-agent/blob/main/frontend/app/api/%5B...path%5D/route.ts): `frontend/app/api/[...path]/route.ts`
- [FastAPI routes](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/api/main.py): `backend/src/ledger_agent/api/main.py`
- [Agent service](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/api/service.py): `backend/src/ledger_agent/api/service.py`
- [Trace and evidence views](https://github.com/yzyazid8-web/ledger-agent/blob/main/frontend/components/AgentTrace.tsx): `frontend/components/AgentTrace.tsx`

### Evaluation

- [Evaluation harness](https://github.com/yzyazid8-web/ledger-agent/tree/main/backend/src/ledger_agent/evaluation): `backend/src/ledger_agent/evaluation`
- [Naive RAG baseline](https://github.com/yzyazid8-web/ledger-agent/blob/main/backend/src/ledger_agent/baselines/naive_rag.py): `backend/src/ledger_agent/baselines/naive_rag.py`

### Other components

- **Analyst**
- **SEC EDGAR**
- **LLM provider**

## Connections

- Analyst → Question interface: asks
- Question interface → API client: submits question (evidence: `frontend/app/page.tsx`)
- API client → API proxy: sends request (evidence: `frontend/lib/api.ts`)
- API proxy → FastAPI routes: forwards request
- FastAPI routes → Agent service: routes to (evidence: `backend/src/ledger_agent/api/main.py`)
- Agent service → ReAct agent: streams steps (evidence: `backend/src/ledger_agent/api/service.py`)
- ReAct agent → Answer and trace format: formats answer (evidence: `backend/src/ledger_agent/agent/react.py`)
- Agent service → Hybrid filing search: builds retriever (evidence: `backend/src/ledger_agent/api/service.py`)
- Agent service → Fixed-step agent: builds agent (evidence: `backend/src/ledger_agent/api/service.py`)
- Filing and XBRL ingestion → SEC EDGAR: fetches filings
- Filing and XBRL ingestion → Typed fact store: loads XBRL facts
- Filing and XBRL ingestion → Hybrid filing search: indexes chunks (evidence: `backend/src/ledger_agent/retrieval/query_analysis.py`)
- ReAct agent → LLM provider: requests tool choices
- ReAct agent → Tool dispatch: dispatches tools (evidence: `backend/src/ledger_agent/agent/react.py`)
- Tool dispatch → Filing search tool: executes search
- Tool dispatch → Typed fact store: reads facts
- Tool dispatch → Safe calculator: evaluates calculation
- Filing search tool → Hybrid filing search: searches passages (evidence: `backend/src/ledger_agent/tools/search_filings.py`)
- Hybrid filing search → Query filters: extracts query entities (evidence: `backend/src/ledger_agent/retrieval/query_analysis.py`)
- Filing search tool → Filter relaxation: relaxes filters (evidence: `backend/src/ledger_agent/tools/search_filings.py`)
- Fixed-step agent → Agent workflow nodes: runs workflow (evidence: `backend/src/ledger_agent/agent/graph.py`)
- Agent workflow nodes → Filing search tool: gathers passages (evidence: `backend/src/ledger_agent/agent/nodes.py`)
- Agent workflow nodes → Typed fact store: looks up facts (evidence: `backend/src/ledger_agent/agent/nodes.py`)
- Agent workflow nodes → Safe calculator: calculates values (evidence: `backend/src/ledger_agent/agent/nodes.py`)
- Agent workflow nodes → Answer verification: checks answer (evidence: `backend/src/ledger_agent/agent/nodes.py`)
- ReAct agent → Answer verification: checks citations (evidence: `backend/src/ledger_agent/agent/react.py`)
- FastAPI routes → Question interface: streams answer
- Question interface → Trace and evidence views: renders steps (evidence: `frontend/app/page.tsx`)
- Evaluation harness → ReAct agent: evaluates configurations (evidence: `backend/src/ledger_agent/evaluation/components.py`)
- Evaluation harness → Naive RAG baseline: compares baseline (evidence: `backend/src/ledger_agent/evaluation/components.py`)
- Naive RAG baseline → Hybrid filing search: searches context (evidence: `backend/src/ledger_agent/baselines/naive_rag.py`)
- Naive RAG baseline → LLM provider: generates answer (evidence: `backend/src/ledger_agent/baselines/naive_rag.py`)
