# ankit-cybertron/ledger-ai architecture

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

- Interactive diagram: https://gitdiagram.com/ankit-cybertron/ledger-ai
- Repository: https://github.com/ankit-cybertron/ledger-ai

## Overview

Ledger AI is a financial reconciliation and settlement workspace with a separate forward-cash forecaster. Finance users upload statements and review reconciliation results in the dashboard; the backend processes records through reconciliation and exposes outcomes, exceptions, forecasts, and audit exports. The README describes four matching passes, algebraic batch-fee resolution, and an optional LLM fallback; sampled code confirms pipeline orchestration, confidence scoring, chat delegation, and forecasting behavior. Several API and reconciliation implementation sections were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`reconciler/reconcile.py`](https://github.com/ankit-cybertron/ledger-ai/blob/main/reconciler/reconcile.py) (Reconciliation), [`reconciler/pipeline_runner.py`](https://github.com/ankit-cybertron/ledger-ai/blob/main/reconciler/pipeline_runner.py) (Pipeline Runner), [`frontend/api/routes.py`](https://github.com/ankit-cybertron/ledger-ai/blob/main/frontend/api/routes.py) (API Routes), [`frontend/api/chat_routes.py`](https://github.com/ankit-cybertron/ledger-ai/blob/main/frontend/api/chat_routes.py) (Chat API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["User Workspace"]
  node_dashboard_ui["Dashboard UI<br/>[dashboard.js]"]
  node_flask_app["Flask App<br/>[app.py]"]
  node_api_routes["API Routes<br/>[routes.py]"]
  node_statement_store[("Statement Store<br/>[statement_store.py]")]
end

subgraph group_reconciliation["Reconciliation Engine"]
  node_ingestion["File Ingestion"]
  node_canonical_schema["Canonical Transactions"]
  node_pipeline_runner["Pipeline Runner<br/>[pipeline_runner.py]"]
  node_reconcile["Reconciliation<br/>[reconcile.py]"]
  node_exact_matcher["Exact Matching<br/>[exact_matcher.py]"]
  node_tolerance_matcher["Tolerance Matching"]
  node_similarity_engine["Similarity Scoring"]
  node_scoring_engine["Confidence Scoring<br/>[scoring_engine.py]"]
  node_ambiguous_matcher["Ambiguous Matcher"]
end

subgraph group_operations["Audit Operations"]
  node_exception_ledger["Exception Ledger"]
  node_report_generation["Audit Reports"]
end

subgraph group_insights["Finance Insights"]
  node_forecast_engine["Cash Forecast<br/>[engine.py]"]
end

subgraph group_assistant["Settlement Assistant"]
  node_chat_routes["Chat API<br/>[chat_routes.py]"]
  node_chat_store[("Chat Sessions<br/>[chat_store.py]")]
  node_qa_agent["Settlement Q&amp;A"]
end

node_finance_user(("Finance User"))
node_groq_service{{"Groq LLM"}}

node_finance_user -->|"uses"| node_dashboard_ui
node_dashboard_ui -->|"requests"| node_api_routes
node_flask_app -->|"registers"| node_api_routes
node_api_routes -->|"manages statements"| node_statement_store
node_api_routes -->|"starts pipeline"| node_pipeline_runner
node_pipeline_runner -->|"runs reconciliation"| node_reconcile
node_reconcile -->|"matches identifiers"| node_exact_matcher
node_reconcile -->|"checks tolerances"| node_tolerance_matcher
node_reconcile -->|"finds candidates"| node_similarity_engine
node_similarity_engine -->|"scores evidence"| node_scoring_engine
node_reconcile -.->|"resolves ambiguity"| node_ambiguous_matcher
node_ambiguous_matcher -.->|"queries model"| node_groq_service
node_pipeline_runner -->|"builds exceptions"| node_exception_ledger
node_pipeline_runner -->|"generates reports"| node_report_generation
node_finance_user -->|"asks questions"| node_chat_routes
node_flask_app -->|"registers"| node_chat_routes
node_chat_routes -->|"stores messages"| node_chat_store
node_chat_routes -->|"delegates questions"| node_qa_agent
node_qa_agent -.->|"queries model"| node_groq_service
node_dashboard_ui -->|"views forecast"| node_forecast_engine
node_ingestion -->|"normalizes records"| node_canonical_schema

click node_dashboard_ui "https://github.com/ankit-cybertron/ledger-ai/blob/main/frontend/static/js/dashboard.js"
click node_flask_app "https://github.com/ankit-cybertron/ledger-ai/blob/main/frontend/app.py"
click node_api_routes "https://github.com/ankit-cybertron/ledger-ai/blob/main/frontend/api/routes.py"
click node_statement_store "https://github.com/ankit-cybertron/ledger-ai/blob/main/frontend/statement_store.py"
click node_ingestion "https://github.com/ankit-cybertron/ledger-ai/tree/main/ingestion"
click node_canonical_schema "https://github.com/ankit-cybertron/ledger-ai/blob/main/schema/canonical_transaction.py"
click node_pipeline_runner "https://github.com/ankit-cybertron/ledger-ai/blob/main/reconciler/pipeline_runner.py"
click node_reconcile "https://github.com/ankit-cybertron/ledger-ai/blob/main/reconciler/reconcile.py"
click node_exact_matcher "https://github.com/ankit-cybertron/ledger-ai/blob/main/matcher/exact_matcher.py"
click node_tolerance_matcher "https://github.com/ankit-cybertron/ledger-ai/blob/main/matcher/tolerance_matcher.py"
click node_similarity_engine "https://github.com/ankit-cybertron/ledger-ai/blob/main/matcher/similarity_engine.py"
click node_scoring_engine "https://github.com/ankit-cybertron/ledger-ai/blob/main/matcher/scoring_engine.py"
click node_ambiguous_matcher "https://github.com/ankit-cybertron/ledger-ai/blob/main/llm/ambiguous_matcher.py"
click node_exception_ledger "https://github.com/ankit-cybertron/ledger-ai/blob/main/exceptions/exception_ledger.py"
click node_report_generation "https://github.com/ankit-cybertron/ledger-ai/tree/main/reports"
click node_forecast_engine "https://github.com/ankit-cybertron/ledger-ai/blob/main/forecasting/engine.py"
click node_chat_routes "https://github.com/ankit-cybertron/ledger-ai/blob/main/frontend/api/chat_routes.py"
click node_chat_store "https://github.com/ankit-cybertron/ledger-ai/blob/main/frontend/api/chat_store.py"
click node_qa_agent "https://github.com/ankit-cybertron/ledger-ai/blob/main/agents/settlement_qa_agent.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_dashboard_ui,node_flask_app,node_api_routes,node_statement_store,node_finance_user toneBlue
class node_ingestion,node_canonical_schema,node_pipeline_runner,node_reconcile,node_exact_matcher,node_tolerance_matcher,node_similarity_engine,node_scoring_engine,node_ambiguous_matcher toneAmber
class node_exception_ledger,node_report_generation toneMint
class node_forecast_engine toneRose
class node_chat_routes,node_chat_store,node_qa_agent,node_groq_service toneIndigo
```

## Components

### User Workspace

- [Dashboard UI](https://github.com/ankit-cybertron/ledger-ai/blob/main/frontend/static/js/dashboard.js): `frontend/static/js/dashboard.js`
- [Flask App](https://github.com/ankit-cybertron/ledger-ai/blob/main/frontend/app.py): `frontend/app.py`
- [API Routes](https://github.com/ankit-cybertron/ledger-ai/blob/main/frontend/api/routes.py): `frontend/api/routes.py`
- [Statement Store](https://github.com/ankit-cybertron/ledger-ai/blob/main/frontend/statement_store.py): `frontend/statement_store.py`

### Reconciliation Engine

- [File Ingestion](https://github.com/ankit-cybertron/ledger-ai/tree/main/ingestion): `ingestion`
- [Canonical Transactions](https://github.com/ankit-cybertron/ledger-ai/blob/main/schema/canonical_transaction.py): `schema/canonical_transaction.py`
- [Pipeline Runner](https://github.com/ankit-cybertron/ledger-ai/blob/main/reconciler/pipeline_runner.py): `reconciler/pipeline_runner.py`
- [Reconciliation](https://github.com/ankit-cybertron/ledger-ai/blob/main/reconciler/reconcile.py): `reconciler/reconcile.py`
- [Exact Matching](https://github.com/ankit-cybertron/ledger-ai/blob/main/matcher/exact_matcher.py): `matcher/exact_matcher.py`
- [Tolerance Matching](https://github.com/ankit-cybertron/ledger-ai/blob/main/matcher/tolerance_matcher.py): `matcher/tolerance_matcher.py`
- [Similarity Scoring](https://github.com/ankit-cybertron/ledger-ai/blob/main/matcher/similarity_engine.py): `matcher/similarity_engine.py`
- [Confidence Scoring](https://github.com/ankit-cybertron/ledger-ai/blob/main/matcher/scoring_engine.py): `matcher/scoring_engine.py`
- [Ambiguous Matcher](https://github.com/ankit-cybertron/ledger-ai/blob/main/llm/ambiguous_matcher.py): `llm/ambiguous_matcher.py`

### Audit Operations

- [Exception Ledger](https://github.com/ankit-cybertron/ledger-ai/blob/main/exceptions/exception_ledger.py): `exceptions/exception_ledger.py`
- [Audit Reports](https://github.com/ankit-cybertron/ledger-ai/tree/main/reports): `reports`

### Finance Insights

- [Cash Forecast](https://github.com/ankit-cybertron/ledger-ai/blob/main/forecasting/engine.py): `forecasting/engine.py`

### Settlement Assistant

- [Chat API](https://github.com/ankit-cybertron/ledger-ai/blob/main/frontend/api/chat_routes.py): `frontend/api/chat_routes.py`
- [Chat Sessions](https://github.com/ankit-cybertron/ledger-ai/blob/main/frontend/api/chat_store.py): `frontend/api/chat_store.py`
- [Settlement Q&A](https://github.com/ankit-cybertron/ledger-ai/blob/main/agents/settlement_qa_agent.py): `agents/settlement_qa_agent.py`

### Other components

- **Finance User**
- **Groq LLM**

## Connections

- Finance User → Dashboard UI: uses
- Dashboard UI → API Routes: requests
- Flask App → API Routes: registers
- API Routes → Statement Store: manages statements
- API Routes → Pipeline Runner: starts pipeline
- Pipeline Runner → Reconciliation: runs reconciliation
- Reconciliation → Exact Matching: matches identifiers
- Reconciliation → Tolerance Matching: checks tolerances
- Reconciliation → Similarity Scoring: finds candidates
- Similarity Scoring → Confidence Scoring: scores evidence
- Reconciliation → Ambiguous Matcher: resolves ambiguity
- Ambiguous Matcher → Groq LLM: queries model
- Pipeline Runner → Exception Ledger: builds exceptions
- Pipeline Runner → Audit Reports: generates reports
- Finance User → Chat API: asks questions
- Flask App → Chat API: registers
- Chat API → Chat Sessions: stores messages
- Chat API → Settlement Q&A: delegates questions
- Settlement Q&A → Groq LLM: queries model
- Dashboard UI → Cash Forecast: views forecast
- File Ingestion → Canonical Transactions: normalizes records