# rahulpaul-07/three-way-financial-reconciliation-engine architecture

> Architecture diagram of the GitHub repository rahulpaul-07/three-way-financial-reconciliation-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rahulpaul-07/three-way-financial-reconciliation-engine
- Repository: https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine

## Overview

This repository is a three-way payment reconciliation product: it compares merchant orders, gateway transactions and settlements, and bank statement lines; classifies matches and exceptions; and presents the run in an interactive dashboard or report. The optional investigation agent and Q&A add model-assisted analysis backed by deterministic tools. The README documents the main workflow and dashboard capabilities; some backend and frontend connections are inferred only from the documented behavior, so those are marked unverified.

Main entry points: [`src/app.py`](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/app.py) (Web API), [`web/src/App.tsx`](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/App.tsx) (Dashboard composition), [`src/matcher.py`](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/matcher.py) (Tiered reconciliation), [`src/agent.py`](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/agent.py) (Resolution agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Reconciliation engine"]
  node_money_rules["Money and date rules<br/>[core.py]"]
  node_matcher["Tiered reconciliation<br/>[matcher.py]"]
  node_assignment["Ambiguous assignment<br/>[assignment.py]"]
end

subgraph group_analysis["Investigation and analysis"]
  node_investigator["Investigation runner<br/>[investigate.py]"]
  node_agent["Resolution agent<br/>[agent.py]"]
  node_tools["Deterministic tools<br/>[tools.py]"]
  node_llm["LLM providers<br/>[llm.py]"]
  node_qa["Question answering<br/>[ask.py]"]
  node_taxonomy["Exception taxonomy<br/>[taxonomy.py]"]
end

subgraph group_service["API and reporting"]
  node_analysis_json["Run analysis JSON<br/>[analysis.py]"]
  node_api["Web API<br/>[app.py]"]
  node_html_report["HTML report<br/>[report.py]"]
end

subgraph group_dashboard["Interactive dashboard"]
  node_web_app["Dashboard composition<br/>[App.tsx]"]
  node_web_api["Dashboard API client<br/>[api.ts]"]
  node_workbench["Run workbench<br/>[workbench.tsx]"]
  node_lineage["Record lineage explorer<br/>[lineage.tsx]"]
  node_evidence["Evidence charts<br/>[evidence.tsx]"]
  node_agent_panel["Agent panel<br/>[agent.tsx]"]
  node_engine_hooks["Engine and data hooks<br/>[use-engine.ts]"]
  node_run_types["Run data types<br/>[types.ts]"]
end

subgraph group_evaluation["Data and evaluation"]
  node_generator["Batch generator<br/>[generate_data.py]"]
  node_evaluator["Evaluation harness<br/>[evaluate.py]"]
  node_adversarial["Adversarial batches"]
end

node_merchant(("Merchant analyst"))
node_source_files["Four source CSVs"]

node_merchant -->|"supplies"| node_source_files
node_source_files -.->|"uploads"| node_api
node_source_files -->|"reconciles"| node_matcher
node_matcher -->|"uses rules"| node_money_rules
node_matcher -->|"delegates to"| node_assignment
node_api -->|"runs engine"| node_matcher
node_api -->|"returns run data"| node_analysis_json
node_api -->|"serves report"| node_html_report
node_matcher -->|"unresolved cases"| node_investigator
node_investigator -->|"starts investigation"| node_agent
node_agent -->|"calls tools"| node_tools
node_agent -->|"requests completions"| node_llm
node_investigator -->|"configures provider"| node_llm
node_api -->|"offers investigations"| node_investigator
node_api -->|"offers Q&amp;A"| node_qa
node_qa -->|"asks model"| node_llm
node_tools -->|"uses primitives"| node_money_rules
node_agent -->|"uses classes"| node_taxonomy
node_merchant -->|"views dashboard"| node_web_app
node_web_app -->|"loads snapshots"| node_web_api
node_web_app -->|"renders"| node_workbench
node_web_app -->|"renders"| node_evidence
node_web_app -->|"renders"| node_agent_panel
node_web_app -->|"reads status"| node_engine_hooks
node_workbench -.->|"requests runs"| node_web_api
node_workbench -->|"shows record paths"| node_lineage
node_web_api -->|"uses types"| node_run_types
node_generator -->|"writes batches"| node_source_files
node_adversarial -->|"extends batches"| node_generator
node_evaluator -->|"grades resolutions"| node_matcher
node_evaluator -->|"runs scale batches"| node_generator

click node_generator "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/generate_data.py"
click node_money_rules "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/core.py"
click node_matcher "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/matcher.py"
click node_assignment "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/assignment.py"
click node_analysis_json "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/analysis.py"
click node_api "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/app.py"
click node_html_report "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/report.py"
click node_investigator "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/investigate.py"
click node_agent "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/agent.py"
click node_tools "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/tools.py"
click node_llm "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/llm.py"
click node_qa "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/ask.py"
click node_taxonomy "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/taxonomy.py"
click node_evaluator "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/evaluate.py"
click node_adversarial "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/adversarial_data.py"
click node_web_app "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/App.tsx"
click node_web_api "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/lib/api.ts"
click node_workbench "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/sections/workbench.tsx"
click node_lineage "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/sections/run/lineage.tsx"
click node_evidence "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/sections/evidence.tsx"
click node_agent_panel "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/sections/agent.tsx"
click node_engine_hooks "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/hooks/use-engine.ts"
click node_run_types "https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/lib/types.ts"

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_money_rules,node_matcher,node_assignment toneBlue
class node_investigator,node_agent,node_tools,node_llm,node_qa,node_taxonomy toneAmber
class node_analysis_json,node_api,node_html_report toneMint
class node_web_app,node_web_api,node_workbench,node_lineage,node_evidence,node_agent_panel,node_engine_hooks,node_run_types toneRose
class node_generator,node_evaluator,node_adversarial,node_merchant,node_source_files toneIndigo
```

## Components

### Reconciliation engine

- [Money and date rules](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/core.py): `src/core.py`
- [Tiered reconciliation](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/matcher.py): `src/matcher.py`
- [Ambiguous assignment](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/assignment.py): `src/assignment.py`

### Investigation and analysis

- [Investigation runner](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/investigate.py): `src/investigate.py`
- [Resolution agent](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/agent.py): `src/agent.py`
- [Deterministic tools](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/tools.py): `src/tools.py`
- [LLM providers](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/llm.py): `src/llm.py`
- [Question answering](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/ask.py): `src/ask.py`
- [Exception taxonomy](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/taxonomy.py): `src/taxonomy.py`

### API and reporting

- [Run analysis JSON](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/analysis.py): `src/analysis.py`
- [Web API](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/app.py): `src/app.py`
- [HTML report](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/report.py): `src/report.py`

### Interactive dashboard

- [Dashboard composition](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Dashboard API client](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [Run workbench](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/sections/workbench.tsx): `web/src/sections/workbench.tsx`
- [Record lineage explorer](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/sections/run/lineage.tsx): `web/src/sections/run/lineage.tsx`
- [Evidence charts](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/sections/evidence.tsx): `web/src/sections/evidence.tsx`
- [Agent panel](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/sections/agent.tsx): `web/src/sections/agent.tsx`
- [Engine and data hooks](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/hooks/use-engine.ts): `web/src/hooks/use-engine.ts`
- [Run data types](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/web/src/lib/types.ts): `web/src/lib/types.ts`

### Data and evaluation

- [Batch generator](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/generate_data.py): `src/generate_data.py`
- [Evaluation harness](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/evaluate.py): `src/evaluate.py`
- [Adversarial batches](https://github.com/rahulpaul-07/three-way-financial-reconciliation-engine/blob/main/src/adversarial_data.py): `src/adversarial_data.py`

### Other components

- **Merchant analyst**
- **Four source CSVs**

## Connections

- Merchant analyst → Four source CSVs: supplies (evidence: `README.md`)
- Four source CSVs → Web API: uploads
- Four source CSVs → Tiered reconciliation: reconciles (evidence: `README.md`)
- Tiered reconciliation → Money and date rules: uses rules (evidence: `src/matcher.py`)
- Tiered reconciliation → Ambiguous assignment: delegates to (evidence: `src/matcher.py`)
- Web API → Tiered reconciliation: runs engine (evidence: `README.md`)
- Web API → Run analysis JSON: returns run data (evidence: `src/app.py`)
- Web API → HTML report: serves report (evidence: `src/app.py`)
- Tiered reconciliation → Investigation runner: unresolved cases (evidence: `README.md`)
- Investigation runner → Resolution agent: starts investigation (evidence: `src/investigate.py`)
- Resolution agent → Deterministic tools: calls tools (evidence: `src/agent.py`)
- Resolution agent → LLM providers: requests completions (evidence: `src/agent.py`)
- Investigation runner → LLM providers: configures provider (evidence: `src/investigate.py`)
- Web API → Investigation runner: offers investigations (evidence: `src/app.py`)
- Web API → Question answering: offers Q&A (evidence: `src/app.py`)
- Question answering → LLM providers: asks model (evidence: `src/ask.py`)
- Deterministic tools → Money and date rules: uses primitives (evidence: `src/tools.py`)
- Resolution agent → Exception taxonomy: uses classes (evidence: `src/agent.py`)
- Merchant analyst → Dashboard composition: views dashboard (evidence: `README.md`)
- Dashboard composition → Dashboard API client: loads snapshots (evidence: `web/src/App.tsx`)
- Dashboard composition → Run workbench: renders (evidence: `web/src/App.tsx`)
- Dashboard composition → Evidence charts: renders (evidence: `web/src/App.tsx`)
- Dashboard composition → Agent panel: renders (evidence: `web/src/App.tsx`)
- Dashboard composition → Engine and data hooks: reads status (evidence: `web/src/App.tsx`)
- Run workbench → Dashboard API client: requests runs
- Run workbench → Record lineage explorer: shows record paths
- Dashboard API client → Run data types: uses types (evidence: `web/src/lib/api.ts`)
- Batch generator → Four source CSVs: writes batches (evidence: `README.md`)
- Adversarial batches → Batch generator: extends batches (evidence: `src/adversarial_data.py`)
- Evaluation harness → Tiered reconciliation: grades resolutions (evidence: `src/evaluate.py`)
- Evaluation harness → Batch generator: runs scale batches (evidence: `src/evaluate.py`)
