# aryan-sagar/idempotent-payments-ledger-reconciliation-backend architecture

> Architecture diagram of the GitHub repository aryan-sagar/idempotent-payments-ledger-reconciliation-backend, 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/aryan-sagar/idempotent-payments-ledger-reconciliation-backend
- Repository: https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend

## Overview

Payments Ledger is a FastAPI service for creating, capturing, settling, refunding, and inspecting payments backed by a double-entry ledger. A client submits a payment with an idempotency key; the API checks Redis and PostgreSQL for replay or in-progress work, then ledger logic advances transaction state and posts balanced entries. Settlement and refunds create further entries rather than editing history. A separate reconciliation command checks ledger totals, cached account balances, and duplicate owners. The map follows the README and sampled runtime source; unsampled details are represented only where documented.

Main entry points: [`app/routes_payments.py`](https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/routes_payments.py) (Payment Routes), [`app/reconciliation.py`](https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/reconciliation.py) (Ledger Reconciliation), [`app/idempotency.py`](https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/idempotency.py) (Idempotency Checks), [`app/ledger.py`](https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/ledger.py) (Payment State And Posting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Payment API"]
  node_api_app["FastAPI App<br/>[main.py]"]
  node_payment_routes["Payment Routes<br/>[routes_payments.py]"]
  node_schemas["Request And Response Schemas<br/>[schemas.py]"]
end

subgraph group_reliability["Request Reliability"]
  node_idempotency["Idempotency Checks<br/>[idempotency.py]"]
  node_redis_client["Redis Client<br/>[redis_client.py]"]
end

subgraph group_ledger["Payment Ledger"]
  node_ledger_logic["Payment State And Posting<br/>[ledger.py]"]
end

subgraph group_storage["Persistence And Audit"]
  node_models["Ledger Data Models<br/>[models.py]"]
  node_database["Database Sessions<br/>[database.py]"]
  node_reconciliation["Ledger Reconciliation<br/>[reconciliation.py]"]
end

node_client(("Payment Client"))
node_redis[("Redis")]
node_postgres[("PostgreSQL")]
node_operator(("Reconciliation Operator"))

node_client -->|"sends requests"| node_api_app
node_api_app -->|"dispatches routes"| node_payment_routes
node_payment_routes -->|"validates and shapes"| node_schemas
node_payment_routes -->|"checks and stores replay"| node_idempotency
node_idempotency -->|"uses cache and locks"| node_redis_client
node_redis_client -->|"reads and writes"| node_redis
node_payment_routes -->|"invokes payment operations"| node_ledger_logic
node_payment_routes -->|"gets request session"| node_database
node_database -->|"connects sessions"| node_postgres
node_idempotency -->|"reads and writes records"| node_postgres
node_ledger_logic -->|"queries and updates"| node_models
node_ledger_logic -->|"persists state and entries"| node_postgres
node_operator -->|"runs audit"| node_reconciliation
node_reconciliation -->|"opens session"| node_database
node_reconciliation -->|"checks ledger data"| node_models
node_reconciliation -->|"reads balances and entries"| node_postgres

click node_api_app "https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/main.py"
click node_payment_routes "https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/routes_payments.py"
click node_schemas "https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/schemas.py"
click node_idempotency "https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/idempotency.py"
click node_redis_client "https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/redis_client.py"
click node_ledger_logic "https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/ledger.py"
click node_models "https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/models.py"
click node_database "https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/database.py"
click node_reconciliation "https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/reconciliation.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_api_app,node_payment_routes,node_schemas,node_client toneBlue
class node_idempotency,node_redis_client,node_redis,node_postgres toneAmber
class node_ledger_logic toneMint
class node_models,node_database,node_reconciliation toneRose
class node_operator toneIndigo
```

## Components

### Payment API

- [FastAPI App](https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/main.py): `app/main.py`
- [Payment Routes](https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/routes_payments.py): `app/routes_payments.py`
- [Request And Response Schemas](https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/schemas.py): `app/schemas.py`

### Request Reliability

- [Idempotency Checks](https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/idempotency.py): `app/idempotency.py`
- [Redis Client](https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/redis_client.py): `app/redis_client.py`

### Payment Ledger

- [Payment State And Posting](https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/ledger.py): `app/ledger.py`

### Persistence And Audit

- [Ledger Data Models](https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/models.py): `app/models.py`
- [Database Sessions](https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/database.py): `app/database.py`
- [Ledger Reconciliation](https://github.com/aryan-sagar/idempotent-payments-ledger-reconciliation-backend/blob/main/app/reconciliation.py): `app/reconciliation.py`

### Other components

- **Payment Client**
- **Redis**
- **PostgreSQL**
- **Reconciliation Operator**

## Connections

- Payment Client → FastAPI App: sends requests
- FastAPI App → Payment Routes: dispatches routes
- Payment Routes → Request And Response Schemas: validates and shapes
- Payment Routes → Idempotency Checks: checks and stores replay
- Idempotency Checks → Redis Client: uses cache and locks
- Redis Client → Redis: reads and writes
- Payment Routes → Payment State And Posting: invokes payment operations
- Payment Routes → Database Sessions: gets request session
- Database Sessions → PostgreSQL: connects sessions
- Idempotency Checks → PostgreSQL: reads and writes records
- Payment State And Posting → Ledger Data Models: queries and updates
- Payment State And Posting → PostgreSQL: persists state and entries
- Reconciliation Operator → Ledger Reconciliation: runs audit
- Ledger Reconciliation → Database Sessions: opens session
- Ledger Reconciliation → Ledger Data Models: checks ledger data
- Ledger Reconciliation → PostgreSQL: reads balances and entries