# dasdristanta13/self_correcting_ledger_agent architecture

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

- Interactive diagram: https://gitdiagram.com/dasdristanta13/self_correcting_ledger_agent
- Repository: https://github.com/dasdristanta13/self_correcting_ledger_agent

## Overview

Self-Correcting Ledger Agent is a browser-based invoice reconciliation product. A user uploads a PDF, the service queues a job, extracts a ledger, checks its arithmetic, and—when discrepancies arise—searches invoice evidence, verifies proposed corrections, and revalidates before returning results and a trace. The SPA supports upload, invoice review, dashboard and audit workflows. The graph follows documented runtime stages and major UI capabilities; some frontend view internals and backend helpers were not sampled, so their connections are shown only where the README or excerpts support them.

Main entry points: [`src/ledger_agent/graph.py`](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/graph.py) (Workflow graph), [`src/ledger_agent/api/app.py`](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/api/app.py) (Invoice API), [`frontend/src/api/client.ts`](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/frontend/src/api/client.ts) (API client), [`frontend/src/App.tsx`](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/frontend/src/App.tsx) (SPA shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser application"]
  node_app["SPA shell<br/>[App.tsx]"]
  node_views["Invoice views"]
  node_upload["Upload workflow<br/>[BulkUpload.tsx]"]
  node_jobhooks["Job polling<br/>[useJobs.tsx]"]
  node_api["API client<br/>[client.ts]"]
end

subgraph group_service["Job service"]
  node_jobapi["Invoice API<br/>[app.py]"]
  node_runner["Job runner<br/>[runner.py]"]
end

subgraph group_core["Reconciliation workflow"]
  node_graph["Workflow graph<br/>[graph.py]"]
  node_ingestion["PDF ingestion"]
  node_extraction["Ledger extraction<br/>[ledger.py]"]
  node_validation["Arithmetic checks<br/>[arithmetic.py]"]
  node_audit["Evidence audit<br/>[audit.py]"]
  node_retrieval["Evidence retrieval<br/>[hybrid.py]"]
  node_reconcile["Correction agent<br/>[reconciliation.py]"]
end

subgraph group_state["Persistence and tracing"]
  node_jobs[("Job and event store<br/>[chroma_store.py]")]
  node_vectors[("Invoice vector indexes<br/>[chroma_vector.py]")]
  node_traces["Trace sinks<br/>[sinks.py]"]
end

node_browser(("Invoice user"))

node_browser -->|"uses"| node_app
node_app -->|"renders"| node_views
node_browser -->|"submits PDF"| node_upload
node_upload -->|"uploads file"| node_api
node_jobhooks -->|"polls jobs"| node_api
node_api -->|"calls invoice API"| node_jobapi
node_jobapi -->|"queues job"| node_runner
node_runner -->|"runs invoice"| node_graph
node_graph -->|"ingests PDF"| node_ingestion
node_graph -->|"builds ledger"| node_extraction
node_graph -->|"checks arithmetic"| node_validation
node_graph -->|"audits discrepancy"| node_audit
node_graph -->|"retrieves evidence"| node_retrieval
node_graph -->|"applies corrections"| node_reconcile
node_graph -->|"revalidates"| node_validation
node_jobapi -->|"stores job state"| node_jobs
node_jobapi -->|"records trace"| node_traces
node_graph -->|"builds index"| node_vectors
node_traces -->|"persists events"| node_jobs
node_api -->|"supplies results"| node_views

click node_app "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/frontend/src/App.tsx"
click node_views "https://github.com/dasdristanta13/self_correcting_ledger_agent/tree/feature/core-loop/frontend/src/views"
click node_upload "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/frontend/src/components/BulkUpload.tsx"
click node_jobhooks "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/frontend/src/hooks/useJobs.tsx"
click node_api "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/frontend/src/api/client.ts"
click node_jobapi "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/api/app.py"
click node_runner "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/api/runner.py"
click node_graph "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/graph.py"
click node_ingestion "https://github.com/dasdristanta13/self_correcting_ledger_agent/tree/feature/core-loop/src/ledger_agent/ingestion"
click node_extraction "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/extraction/ledger.py"
click node_validation "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/validation/arithmetic.py"
click node_audit "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/agents/audit.py"
click node_retrieval "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/retrieval/hybrid.py"
click node_reconcile "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/agents/reconciliation.py"
click node_jobs "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/storage/chroma_store.py"
click node_vectors "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/retrieval/chroma_vector.py"
click node_traces "https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/observability/sinks.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_app,node_views,node_upload,node_jobhooks,node_api,node_browser toneBlue
class node_jobapi,node_runner toneAmber
class node_graph,node_ingestion,node_extraction,node_validation,node_audit,node_retrieval,node_reconcile toneMint
class node_jobs,node_vectors,node_traces toneRose
```

## Components

### Browser application

- [SPA shell](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Invoice views](https://github.com/dasdristanta13/self_correcting_ledger_agent/tree/feature/core-loop/frontend/src/views): `frontend/src/views`
- [Upload workflow](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/frontend/src/components/BulkUpload.tsx): `frontend/src/components/BulkUpload.tsx`
- [Job polling](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/frontend/src/hooks/useJobs.tsx): `frontend/src/hooks/useJobs.tsx`
- [API client](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Job service

- [Invoice API](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/api/app.py): `src/ledger_agent/api/app.py`
- [Job runner](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/api/runner.py): `src/ledger_agent/api/runner.py`

### Reconciliation workflow

- [Workflow graph](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/graph.py): `src/ledger_agent/graph.py`
- [PDF ingestion](https://github.com/dasdristanta13/self_correcting_ledger_agent/tree/feature/core-loop/src/ledger_agent/ingestion): `src/ledger_agent/ingestion`
- [Ledger extraction](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/extraction/ledger.py): `src/ledger_agent/extraction/ledger.py`
- [Arithmetic checks](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/validation/arithmetic.py): `src/ledger_agent/validation/arithmetic.py`
- [Evidence audit](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/agents/audit.py): `src/ledger_agent/agents/audit.py`
- [Evidence retrieval](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/retrieval/hybrid.py): `src/ledger_agent/retrieval/hybrid.py`
- [Correction agent](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/agents/reconciliation.py): `src/ledger_agent/agents/reconciliation.py`

### Persistence and tracing

- [Job and event store](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/storage/chroma_store.py): `src/ledger_agent/storage/chroma_store.py`
- [Invoice vector indexes](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/retrieval/chroma_vector.py): `src/ledger_agent/retrieval/chroma_vector.py`
- [Trace sinks](https://github.com/dasdristanta13/self_correcting_ledger_agent/blob/feature/core-loop/src/ledger_agent/observability/sinks.py): `src/ledger_agent/observability/sinks.py`

### Other components

- **Invoice user**

## Connections

- Invoice user → SPA shell: uses
- SPA shell → Invoice views: renders (evidence: `frontend/src/App.tsx`)
- Invoice user → Upload workflow: submits PDF
- Upload workflow → API client: uploads file (evidence: `frontend/src/components/BulkUpload.tsx`)
- Job polling → API client: polls jobs (evidence: `frontend/src/hooks/useJobs.tsx`)
- API client → Invoice API: calls invoice API
- Invoice API → Job runner: queues job (evidence: `src/ledger_agent/api/app.py`)
- Job runner → Workflow graph: runs invoice
- Workflow graph → PDF ingestion: ingests PDF (evidence: `src/ledger_agent/graph.py`)
- Workflow graph → Ledger extraction: builds ledger (evidence: `src/ledger_agent/graph.py`)
- Workflow graph → Arithmetic checks: checks arithmetic (evidence: `src/ledger_agent/graph.py`)
- Workflow graph → Evidence audit: audits discrepancy (evidence: `src/ledger_agent/graph.py`)
- Workflow graph → Evidence retrieval: retrieves evidence (evidence: `src/ledger_agent/graph.py`)
- Workflow graph → Correction agent: applies corrections (evidence: `src/ledger_agent/graph.py`)
- Workflow graph → Arithmetic checks: revalidates (evidence: `src/ledger_agent/graph.py`)
- Invoice API → Job and event store: stores job state (evidence: `src/ledger_agent/api/app.py`)
- Invoice API → Trace sinks: records trace (evidence: `src/ledger_agent/api/main.py`)
- Workflow graph → Invoice vector indexes: builds index (evidence: `src/ledger_agent/graph.py`)
- Trace sinks → Job and event store: persists events (evidence: `src/ledger_agent/api/main.py`)
- API client → Invoice views: supplies results
