# zachary-twh/ledger-txn-api architecture

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

- Interactive diagram: https://gitdiagram.com/zachary-twh/ledger-txn-api
- Repository: https://github.com/zachary-twh/ledger-txn-api

## Overview

Double-entry-ledger is a FastAPI bookkeeping API. Users register and authenticate, create accounts, then deposit, withdraw, or transfer funds; the API records balanced ledger entries and supports balance lookup, transaction history, and integrity checks. Authentication, rate limiting, idempotency, currency checks, and cache invalidation are API concerns. Celery Beat schedules reconciliation and exchange-rate fetching as background tasks. The excerpts show API/database/cache and task/database/exchange-rate interactions; queue deployment details and some endpoint internals are documented but not sampled.

Main entry points: [`app/main.py`](https://github.com/zachary-twh/ledger-txn-api/blob/main/app/main.py) (FastAPI routes), [`app/tasks.py`](https://github.com/zachary-twh/ledger-txn-api/blob/main/app/tasks.py) (Reconciliation and FX tasks), [`app/database.py`](https://github.com/zachary-twh/ledger-txn-api/blob/main/app/database.py) (Database sessions), [`app/models.py`](https://github.com/zachary-twh/ledger-txn-api/blob/main/app/models.py) (Ledger data model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Ledger API"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_auth["User authentication<br/>[main.py]"]
  node_accounts["Account management<br/>[main.py]"]
  node_ledger["Money operations<br/>[main.py]"]
  node_reads["History and integrity<br/>[main.py]"]
end

subgraph group_data["Persistence and cache"]
  node_schema["Ledger data model<br/>[models.py]"]
  node_dbsessions["Database sessions<br/>[database.py]"]
  node_cache["Account cache<br/>[redis_client.py]"]
end

subgraph group_background["Background processing"]
  node_scheduler["Celery Beat schedule<br/>[celery_app.py]"]
  node_tasks["Reconciliation and FX tasks<br/>[tasks.py]"]
end

subgraph group_external["External services"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
  node_queue["RabbitMQ broker"]
  node_fx["Frankfurter rates API"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_api
node_api -->|"routes authentication"| node_auth
node_api -->|"routes account actions"| node_accounts
node_api -->|"routes money operations"| node_ledger
node_api -->|"routes account reads"| node_reads
node_api -->|"opens sessions"| node_dbsessions
node_api -->|"queries and updates"| node_schema
node_dbsessions -->|"connects to"| node_postgres
node_schema -->|"uses declarative base"| node_dbsessions
node_api -->|"gets and invalidates"| node_cache
node_cache -->|"stores cached values"| node_redis
node_scheduler -->|"schedules tasks"| node_tasks
node_scheduler -->|"uses broker"| node_queue
node_tasks -->|"opens sessions"| node_dbsessions
node_tasks -->|"reads and writes records"| node_schema
node_tasks -->|"fetches exchange rates"| node_fx

click node_api "https://github.com/zachary-twh/ledger-txn-api/blob/main/app/main.py"
click node_auth "https://github.com/zachary-twh/ledger-txn-api/blob/main/app/main.py"
click node_accounts "https://github.com/zachary-twh/ledger-txn-api/blob/main/app/main.py"
click node_ledger "https://github.com/zachary-twh/ledger-txn-api/blob/main/app/main.py"
click node_reads "https://github.com/zachary-twh/ledger-txn-api/blob/main/app/main.py"
click node_schema "https://github.com/zachary-twh/ledger-txn-api/blob/main/app/models.py"
click node_dbsessions "https://github.com/zachary-twh/ledger-txn-api/blob/main/app/database.py"
click node_cache "https://github.com/zachary-twh/ledger-txn-api/blob/main/app/redis_client.py"
click node_scheduler "https://github.com/zachary-twh/ledger-txn-api/blob/main/app/celery_app.py"
click node_tasks "https://github.com/zachary-twh/ledger-txn-api/blob/main/app/tasks.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,node_auth,node_accounts,node_ledger,node_reads,node_client toneBlue
class node_schema,node_dbsessions,node_cache toneAmber
class node_scheduler,node_tasks toneMint
class node_postgres,node_redis,node_queue,node_fx toneRose
```

## Components

### Ledger API

- [FastAPI routes](https://github.com/zachary-twh/ledger-txn-api/blob/main/app/main.py): `app/main.py`
- [User authentication](https://github.com/zachary-twh/ledger-txn-api/blob/main/app/main.py): `app/main.py`
- [Account management](https://github.com/zachary-twh/ledger-txn-api/blob/main/app/main.py): `app/main.py`
- [Money operations](https://github.com/zachary-twh/ledger-txn-api/blob/main/app/main.py): `app/main.py`
- [History and integrity](https://github.com/zachary-twh/ledger-txn-api/blob/main/app/main.py): `app/main.py`

### Persistence and cache

- [Ledger data model](https://github.com/zachary-twh/ledger-txn-api/blob/main/app/models.py): `app/models.py`
- [Database sessions](https://github.com/zachary-twh/ledger-txn-api/blob/main/app/database.py): `app/database.py`
- [Account cache](https://github.com/zachary-twh/ledger-txn-api/blob/main/app/redis_client.py): `app/redis_client.py`

### Background processing

- [Celery Beat schedule](https://github.com/zachary-twh/ledger-txn-api/blob/main/app/celery_app.py): `app/celery_app.py`
- [Reconciliation and FX tasks](https://github.com/zachary-twh/ledger-txn-api/blob/main/app/tasks.py): `app/tasks.py`

### External services

- **PostgreSQL**
- **Redis**
- **RabbitMQ broker**
- **Frankfurter rates API**

### Other components

- **API client**

## Connections

- API client → FastAPI routes: sends requests (evidence: `README.md`)
- FastAPI routes → User authentication: routes authentication (evidence: `README.md`)
- FastAPI routes → Account management: routes account actions (evidence: `README.md`)
- FastAPI routes → Money operations: routes money operations (evidence: `README.md`)
- FastAPI routes → History and integrity: routes account reads (evidence: `README.md`)
- FastAPI routes → Database sessions: opens sessions (evidence: `app/main.py`)
- FastAPI routes → Ledger data model: queries and updates (evidence: `app/main.py`)
- Database sessions → PostgreSQL: connects to (evidence: `app/database.py`)
- Ledger data model → Database sessions: uses declarative base (evidence: `app/models.py`)
- FastAPI routes → Account cache: gets and invalidates (evidence: `app/main.py`)
- Account cache → Redis: stores cached values (evidence: `app/redis_client.py`)
- Celery Beat schedule → Reconciliation and FX tasks: schedules tasks (evidence: `app/celery_app.py`)
- Celery Beat schedule → RabbitMQ broker: uses broker (evidence: `app/celery_app.py`)
- Reconciliation and FX tasks → Database sessions: opens sessions (evidence: `app/tasks.py`)
- Reconciliation and FX tasks → Ledger data model: reads and writes records (evidence: `app/tasks.py`)
- Reconciliation and FX tasks → Frankfurter rates API: fetches exchange rates (evidence: `app/tasks.py`)
