# shreya-14-git/ledgerlens architecture

> Architecture diagram of the GitHub repository shreya-14-git/ledgerlens, 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/shreya-14-git/ledgerlens
- Repository: https://github.com/shreya-14-git/ledgerlens

## Overview

LedgerLens reconciles order, payment, and settlement records, surfaces exceptions, and supports investigation and transaction entry through a dashboard. The main path runs from CSV inputs through the reconciliation script to persisted results; the FastAPI service exposes those results and AI analysis to the React interface. The README also documents dashboard metrics, search/filtering, validation, persistent additions, and an audit trail. The frontend excerpt confirms API requests in places but omits most request-loading code, so only documented or directly evidenced connections are drawn; data files are represented as sources, not implementation modules.

Main entry points: [`backend/main.py`](https://github.com/shreya-14-git/ledgerlens/blob/main/backend/main.py) (FastAPI service), [`reconcile.py`](https://github.com/shreya-14-git/ledgerlens/blob/main/reconcile.py) (Reconciliation engine), [`frontend/src/App.jsx`](https://github.com/shreya-14-git/ledgerlens/blob/main/frontend/src/App.jsx) (Dashboard and forms), [`data/reconciliation_results.csv`](https://github.com/shreya-14-git/ledgerlens/blob/main/data/reconciliation_results.csv) (Reconciliation results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reconciliation["Reconciliation"]
  node_orders["Order records<br/>[orders.csv]"]
  node_payments["Payment records<br/>[payments.csv]"]
  node_settlements["Settlement records<br/>[settlements.csv]"]
  node_engine["Reconciliation engine<br/>[reconcile.py]"]
  node_results["Reconciliation results"]
end

subgraph group_investigation["Investigation"]
  node_investigation_cli["CLI investigation<br/>[investigate.py]"]
  node_analysis["Transaction analysis<br/>[ai_analysis.py]"]
  node_openai_probe["OpenAI connectivity probe<br/>[ai_agent.py]"]
end

subgraph group_service["API and state"]
  node_api["FastAPI service<br/>[main.py]"]
  node_new_records[("Added transactions")]
  node_audit["Audit trail<br/>[main.py]"]
end

subgraph group_interface["Dashboard"]
  node_dashboard["Dashboard and forms<br/>[App.jsx]"]
  node_app_entry["React app entry<br/>[main.jsx]"]
end

node_operator(("Finance operator"))
node_browser(("Dashboard user"))

node_engine -->|"reads"| node_orders
node_engine -->|"reads"| node_payments
node_engine -->|"reads"| node_settlements
node_engine -->|"writes"| node_results
node_investigation_cli -->|"reads"| node_results
node_api -->|"reads"| node_results
node_api -->|"loads and saves"| node_new_records
node_api -->|"calls"| node_analysis
node_api -->|"records activity"| node_audit
node_browser -.->|"uses"| node_dashboard
node_dashboard -->|"requests API"| node_api
node_app_entry -->|"renders"| node_dashboard
node_operator -->|"enters order ID"| node_investigation_cli
node_openai_probe -->|"prints response"| node_operator

click node_orders "https://github.com/shreya-14-git/ledgerlens/blob/main/data/orders.csv"
click node_payments "https://github.com/shreya-14-git/ledgerlens/blob/main/data/payments.csv"
click node_settlements "https://github.com/shreya-14-git/ledgerlens/blob/main/data/settlements.csv"
click node_engine "https://github.com/shreya-14-git/ledgerlens/blob/main/reconcile.py"
click node_results "https://github.com/shreya-14-git/ledgerlens/blob/main/data/reconciliation_results.csv"
click node_investigation_cli "https://github.com/shreya-14-git/ledgerlens/blob/main/investigate.py"
click node_analysis "https://github.com/shreya-14-git/ledgerlens/blob/main/ai_analysis.py"
click node_api "https://github.com/shreya-14-git/ledgerlens/blob/main/backend/main.py"
click node_new_records "https://github.com/shreya-14-git/ledgerlens/blob/main/data/new_transactions.json"
click node_audit "https://github.com/shreya-14-git/ledgerlens/blob/main/backend/main.py"
click node_dashboard "https://github.com/shreya-14-git/ledgerlens/blob/main/frontend/src/App.jsx"
click node_app_entry "https://github.com/shreya-14-git/ledgerlens/blob/main/frontend/src/main.jsx"
click node_openai_probe "https://github.com/shreya-14-git/ledgerlens/blob/main/ai_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_orders,node_payments,node_settlements,node_engine,node_results,node_browser toneBlue
class node_investigation_cli,node_analysis,node_openai_probe toneAmber
class node_api,node_new_records,node_audit toneMint
class node_dashboard,node_app_entry toneRose
class node_operator toneIndigo
```

## Components

### Reconciliation

- [Order records](https://github.com/shreya-14-git/ledgerlens/blob/main/data/orders.csv): `data/orders.csv`
- [Payment records](https://github.com/shreya-14-git/ledgerlens/blob/main/data/payments.csv): `data/payments.csv`
- [Settlement records](https://github.com/shreya-14-git/ledgerlens/blob/main/data/settlements.csv): `data/settlements.csv`
- [Reconciliation engine](https://github.com/shreya-14-git/ledgerlens/blob/main/reconcile.py): `reconcile.py`
- [Reconciliation results](https://github.com/shreya-14-git/ledgerlens/blob/main/data/reconciliation_results.csv): `data/reconciliation_results.csv`

### Investigation

- [CLI investigation](https://github.com/shreya-14-git/ledgerlens/blob/main/investigate.py): `investigate.py`
- [Transaction analysis](https://github.com/shreya-14-git/ledgerlens/blob/main/ai_analysis.py): `ai_analysis.py`
- [OpenAI connectivity probe](https://github.com/shreya-14-git/ledgerlens/blob/main/ai_agent.py): `ai_agent.py`

### API and state

- [FastAPI service](https://github.com/shreya-14-git/ledgerlens/blob/main/backend/main.py): `backend/main.py`
- [Added transactions](https://github.com/shreya-14-git/ledgerlens/blob/main/data/new_transactions.json): `data/new_transactions.json`
- [Audit trail](https://github.com/shreya-14-git/ledgerlens/blob/main/backend/main.py): `backend/main.py`

### Dashboard

- [Dashboard and forms](https://github.com/shreya-14-git/ledgerlens/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [React app entry](https://github.com/shreya-14-git/ledgerlens/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`

### Other components

- **Finance operator**
- **Dashboard user**

## Connections

- Reconciliation engine → Order records: reads (evidence: `reconcile.py`)
- Reconciliation engine → Payment records: reads (evidence: `reconcile.py`)
- Reconciliation engine → Settlement records: reads (evidence: `reconcile.py`)
- Reconciliation engine → Reconciliation results: writes (evidence: `reconcile.py`)
- CLI investigation → Reconciliation results: reads (evidence: `investigate.py`)
- FastAPI service → Reconciliation results: reads (evidence: `backend/main.py`)
- FastAPI service → Added transactions: loads and saves (evidence: `backend/main.py`)
- FastAPI service → Transaction analysis: calls (evidence: `backend/main.py`)
- FastAPI service → Audit trail: records activity (evidence: `backend/main.py`)
- Dashboard user → Dashboard and forms: uses
- Dashboard and forms → FastAPI service: requests API (evidence: `frontend/src/App.jsx`)
- React app entry → Dashboard and forms: renders (evidence: `frontend/src/main.jsx`)
- Finance operator → CLI investigation: enters order ID (evidence: `investigate.py`)
- OpenAI connectivity probe → Finance operator: prints response (evidence: `ai_agent.py`)
