# shashankd06/idempotent-payment-ledger-api architecture

> Architecture diagram of the GitHub repository shashankd06/idempotent-payment-ledger-api, 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/shashankd06/idempotent-payment-ledger-api
- Repository: https://github.com/shashankd06/idempotent-payment-ledger-api

## Overview

This is a FastAPI payment-ledger API. Clients create accounts, query balances derived from ledger entries, and submit transfers; transfer requests are checked for idempotent replay before ledger execution. The ledger locks accounts, checks funds, and records balanced debit/credit entries. The README documents these capabilities, while the sampled source supports the specific route, ledger, and storage relationships shown here.

Main entry points: [`app/database.py`](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/database.py) (SQL database), [`app/routes.py`](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/routes.py) (API routes), [`app/ledger.py`](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/ledger.py) (Transfer execution), [`app/main.py`](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API surface"]
  node_app["FastAPI app<br/>[main.py]"]
  node_routes["API routes<br/>[routes.py]"]
  node_schemas["Request and response schemas<br/>[schemas.py]"]
  node_account_ops["Account creation<br/>[routes.py]"]
  node_balance_ops["Balance query<br/>[routes.py]"]
  node_transfer_ops["Transfer endpoint<br/>[routes.py]"]
end

subgraph group_ledger["Ledger operations"]
  node_idempotency["Idempotency checks<br/>[idempotency.py]"]
  node_ledger_ops["Transfer execution<br/>[ledger.py]"]
  node_balance_calc["Balance derivation<br/>[ledger.py]"]
end

subgraph group_persistence["Persistence"]
  node_models["Ledger data models<br/>[models.py]"]
  node_database[("SQL database<br/>[database.py]")]
end

node_client(("API client"))

node_client -->|"sends requests"| node_app
node_app -->|"registers routes"| node_routes
node_app -->|"creates tables"| node_database
node_routes -->|"dispatches"| node_account_ops
node_routes -->|"dispatches"| node_balance_ops
node_routes -->|"dispatches"| node_transfer_ops
node_account_ops -->|"validates and returns"| node_schemas
node_balance_ops -->|"returns"| node_schemas
node_transfer_ops -->|"validates and returns"| node_schemas
node_account_ops -->|"queries and writes"| node_database
node_account_ops -->|"funds opening balance"| node_ledger_ops
node_balance_ops -->|"loads account"| node_database
node_balance_ops -->|"requests balance"| node_balance_calc
node_transfer_ops -->|"checks and stores result"| node_idempotency
node_transfer_ops -->|"executes transfer"| node_ledger_ops
node_idempotency -->|"reads and writes records"| node_database
node_ledger_ops -->|"derives balances"| node_balance_calc
node_ledger_ops -->|"locks and writes entries"| node_database
node_balance_calc -->|"sums entries"| node_database
node_database -->|"maps tables"| node_models

click node_app "https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/main.py"
click node_routes "https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/routes.py"
click node_schemas "https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/schemas.py"
click node_account_ops "https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/routes.py"
click node_balance_ops "https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/routes.py"
click node_transfer_ops "https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/routes.py"
click node_idempotency "https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/idempotency.py"
click node_ledger_ops "https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/ledger.py"
click node_balance_calc "https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/ledger.py"
click node_models "https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/models.py"
click node_database "https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/database.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_routes,node_schemas,node_account_ops,node_balance_ops,node_transfer_ops,node_client toneBlue
class node_idempotency,node_ledger_ops,node_balance_calc toneAmber
class node_models,node_database toneMint
```

## Components

### API surface

- [FastAPI app](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/main.py): `app/main.py`
- [API routes](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/routes.py): `app/routes.py`
- [Request and response schemas](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/schemas.py): `app/schemas.py`
- [Account creation](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/routes.py): `app/routes.py`
- [Balance query](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/routes.py): `app/routes.py`
- [Transfer endpoint](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/routes.py): `app/routes.py`

### Ledger operations

- [Idempotency checks](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/idempotency.py): `app/idempotency.py`
- [Transfer execution](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/ledger.py): `app/ledger.py`
- [Balance derivation](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/ledger.py): `app/ledger.py`

### Persistence

- [Ledger data models](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/models.py): `app/models.py`
- [SQL database](https://github.com/shashankd06/idempotent-payment-ledger-api/blob/main/app/database.py): `app/database.py`

### Other components

- **API client**

## Connections

- API client → FastAPI app: sends requests
- FastAPI app → API routes: registers routes
- FastAPI app → SQL database: creates tables
- API routes → Account creation: dispatches
- API routes → Balance query: dispatches
- API routes → Transfer endpoint: dispatches
- Account creation → Request and response schemas: validates and returns
- Balance query → Request and response schemas: returns
- Transfer endpoint → Request and response schemas: validates and returns
- Account creation → SQL database: queries and writes
- Account creation → Transfer execution: funds opening balance
- Balance query → SQL database: loads account
- Balance query → Balance derivation: requests balance
- Transfer endpoint → Idempotency checks: checks and stores result
- Transfer endpoint → Transfer execution: executes transfer
- Idempotency checks → SQL database: reads and writes records
- Transfer execution → Balance derivation: derives balances
- Transfer execution → SQL database: locks and writes entries
- Balance derivation → SQL database: sums entries
- SQL database → Ledger data models: maps tables