# baran-ozkann/ledger-payment-core architecture

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

## Overview

Ledger Payment Core is a single-currency, double-entry payment service. Clients create accounts, fund them, transfer money, reverse transactions, and query account or transaction history. Mutating API calls pass through request hashing and idempotency before LedgerService posts balanced entries and outbox events in one database transaction. The outbox relay publishes account activity for a deduplicated projection; reconciliation checks ledger invariants, while retention jobs clean old records. The README documents these capabilities and integrations; unsampled subsystem links are omitted where callers were not shown.

Main entry points: [`src/main/java/com/baran/ledger/service/LedgerService.java`](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/service/LedgerService.java) (Ledger service), [`src/main/java/com/baran/ledger/config/RequestHashFilter.java`](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/config/RequestHashFilter.java) (Request hash), [`src/main/java/com/baran/ledger/api/TransferController.java`](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/api/TransferController.java) (Transfer API), [`src/main/java/com/baran/ledger/api/FundingController.java`](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/api/FundingController.java) (Funding API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and requests"]
  node_hash_filter["Request hash"]
  node_account_api["Account API"]
  node_transfer_api["Transfer API"]
  node_funding_api["Funding API"]
  node_api_responses["Response mapping"]
end

subgraph group_ledger["Ledger posting"]
  node_service["Ledger service<br/>[LedgerService.java]"]
  node_accounts[("Accounts store")]
  node_transactions[("Transactions store")]
  node_entries[("Entries store")]
  node_idempotency[("Idempotency store")]
end

subgraph group_events["Events and projections"]
  node_outbox_store[("Outbox store")]
  node_relay["Outbox relay<br/>[OutboxRelay.java]"]
  node_publisher["Activity publisher"]
  node_projection["Activity projection"]
  node_activity_store[("Activity and dedup")]
  node_consumed_store[("Consumed events")]
end

subgraph group_operations["Integrity and retention"]
  node_reconciliation["Reconciliation"]
  node_retention["Retention jobs"]
  node_key_cleanup["Key cleanup"]
  node_metrics["Transfer metrics"]
end

node_client(("Client"))
node_broker["Kafka"]
node_prometheus[("Prometheus")]
node_load_runner["Load scenarios<br/>[ledger.js]"]

node_client -->|"sends request"| node_hash_filter
node_hash_filter -->|"provides hash"| node_transfer_api
node_hash_filter -->|"provides hash"| node_account_api
node_hash_filter -->|"provides hash"| node_funding_api
node_transfer_api -->|"calls transfers"| node_service
node_funding_api -->|"calls funding"| node_service
node_account_api -->|"calls account ops"| node_service
node_transfer_api -->|"wraps response"| node_api_responses
node_funding_api -->|"wraps response"| node_api_responses
node_service -->|"reads and updates"| node_accounts
node_service -->|"records transaction"| node_transactions
node_service -->|"posts entries"| node_entries
node_service -->|"claims and replays"| node_idempotency
node_service -->|"appends events"| node_outbox_store
node_outbox_store -->|"supplies pending rows"| node_relay
node_relay -->|"publishes events"| node_publisher
node_publisher -.->|"sends activity"| node_broker
node_broker -.->|"delivers events"| node_projection
node_projection -->|"writes activity"| node_activity_store
node_projection -->|"deduplicates events"| node_consumed_store
node_reconciliation -->|"checks balances"| node_accounts
node_reconciliation -->|"sums postings"| node_entries
node_retention -->|"archives published"| node_outbox_store
node_key_cleanup -.->|"cleans expired keys"| node_idempotency
node_prometheus -.->|"scrapes metrics"| node_metrics
node_load_runner -->|"posts transfers"| node_transfer_api

click node_hash_filter "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/config/RequestHashFilter.java"
click node_account_api "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/api/AccountController.java"
click node_transfer_api "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/api/TransferController.java"
click node_funding_api "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/api/FundingController.java"
click node_api_responses "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/api/IdempotentResponse.java"
click node_service "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/service/LedgerService.java"
click node_accounts "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/store/AccountRepository.java"
click node_transactions "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/store/TransactionRepository.java"
click node_entries "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/store/EntryRepository.java"
click node_idempotency "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/store/IdempotencyRepository.java"
click node_outbox_store "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/store/OutboxRepository.java"
click node_relay "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/outbox/OutboxRelay.java"
click node_publisher "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/outbox/AccountActivityPublisher.java"
click node_projection "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/projection/AccountActivityProjection.java"
click node_activity_store "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/store/AccountActivityRepository.java"
click node_consumed_store "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/store/ConsumedEventRepository.java"
click node_reconciliation "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/recon/ReconciliationJob.java"
click node_retention "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/retention/OutboxArchivalJob.java"
click node_key_cleanup "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/retention/IdempotencyKeyCleanupJob.java"
click node_metrics "https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/config/TransferMetrics.java"
click node_load_runner "https://github.com/baran-ozkann/ledger-payment-core/blob/main/load/k6/ledger.js"

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_hash_filter,node_account_api,node_transfer_api,node_funding_api,node_api_responses,node_client toneBlue
class node_service,node_accounts,node_transactions,node_entries,node_idempotency,node_prometheus toneAmber
class node_outbox_store,node_relay,node_publisher,node_projection,node_activity_store,node_consumed_store toneMint
class node_reconciliation,node_retention,node_key_cleanup,node_metrics toneRose
class node_broker toneIndigo
class node_load_runner toneTeal
```

## Components

### API and requests

- [Request hash](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/config/RequestHashFilter.java): `src/main/java/com/baran/ledger/config/RequestHashFilter.java`
- [Account API](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/api/AccountController.java): `src/main/java/com/baran/ledger/api/AccountController.java`
- [Transfer API](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/api/TransferController.java): `src/main/java/com/baran/ledger/api/TransferController.java`
- [Funding API](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/api/FundingController.java): `src/main/java/com/baran/ledger/api/FundingController.java`
- [Response mapping](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/api/IdempotentResponse.java): `src/main/java/com/baran/ledger/api/IdempotentResponse.java`

### Ledger posting

- [Ledger service](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/service/LedgerService.java): `src/main/java/com/baran/ledger/service/LedgerService.java`
- [Accounts store](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/store/AccountRepository.java): `src/main/java/com/baran/ledger/store/AccountRepository.java`
- [Transactions store](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/store/TransactionRepository.java): `src/main/java/com/baran/ledger/store/TransactionRepository.java`
- [Entries store](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/store/EntryRepository.java): `src/main/java/com/baran/ledger/store/EntryRepository.java`
- [Idempotency store](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/store/IdempotencyRepository.java): `src/main/java/com/baran/ledger/store/IdempotencyRepository.java`

### Events and projections

- [Outbox store](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/store/OutboxRepository.java): `src/main/java/com/baran/ledger/store/OutboxRepository.java`
- [Outbox relay](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/outbox/OutboxRelay.java): `src/main/java/com/baran/ledger/outbox/OutboxRelay.java`
- [Activity publisher](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/outbox/AccountActivityPublisher.java): `src/main/java/com/baran/ledger/outbox/AccountActivityPublisher.java`
- [Activity projection](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/projection/AccountActivityProjection.java): `src/main/java/com/baran/ledger/projection/AccountActivityProjection.java`
- [Activity and dedup](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/store/AccountActivityRepository.java): `src/main/java/com/baran/ledger/store/AccountActivityRepository.java`
- [Consumed events](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/store/ConsumedEventRepository.java): `src/main/java/com/baran/ledger/store/ConsumedEventRepository.java`

### Integrity and retention

- [Reconciliation](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/recon/ReconciliationJob.java): `src/main/java/com/baran/ledger/recon/ReconciliationJob.java`
- [Retention jobs](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/retention/OutboxArchivalJob.java): `src/main/java/com/baran/ledger/retention/OutboxArchivalJob.java`
- [Key cleanup](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/retention/IdempotencyKeyCleanupJob.java): `src/main/java/com/baran/ledger/retention/IdempotencyKeyCleanupJob.java`
- [Transfer metrics](https://github.com/baran-ozkann/ledger-payment-core/blob/main/src/main/java/com/baran/ledger/config/TransferMetrics.java): `src/main/java/com/baran/ledger/config/TransferMetrics.java`

### Other components

- **Client**
- **Kafka**
- **Prometheus**
- [Load scenarios](https://github.com/baran-ozkann/ledger-payment-core/blob/main/load/k6/ledger.js): `load/k6/ledger.js`

## Connections

- Client → Request hash: sends request
- Request hash → Transfer API: provides hash (evidence: `src/main/java/com/baran/ledger/api/TransferController.java`)
- Request hash → Account API: provides hash (evidence: `src/main/java/com/baran/ledger/api/AccountController.java`)
- Request hash → Funding API: provides hash (evidence: `src/main/java/com/baran/ledger/api/FundingController.java`)
- Transfer API → Ledger service: calls transfers (evidence: `src/main/java/com/baran/ledger/api/TransferController.java`)
- Funding API → Ledger service: calls funding (evidence: `src/main/java/com/baran/ledger/api/FundingController.java`)
- Account API → Ledger service: calls account ops (evidence: `src/main/java/com/baran/ledger/api/AccountController.java`)
- Transfer API → Response mapping: wraps response (evidence: `src/main/java/com/baran/ledger/api/TransferController.java`)
- Funding API → Response mapping: wraps response (evidence: `src/main/java/com/baran/ledger/api/FundingController.java`)
- Ledger service → Accounts store: reads and updates (evidence: `src/main/java/com/baran/ledger/service/LedgerService.java`)
- Ledger service → Transactions store: records transaction (evidence: `src/main/java/com/baran/ledger/service/LedgerService.java`)
- Ledger service → Entries store: posts entries (evidence: `src/main/java/com/baran/ledger/service/LedgerService.java`)
- Ledger service → Idempotency store: claims and replays (evidence: `src/main/java/com/baran/ledger/service/LedgerService.java`)
- Ledger service → Outbox store: appends events (evidence: `src/main/java/com/baran/ledger/service/LedgerService.java`)
- Outbox store → Outbox relay: supplies pending rows (evidence: `src/main/java/com/baran/ledger/outbox/OutboxRelay.java`)
- Outbox relay → Activity publisher: publishes events (evidence: `src/main/java/com/baran/ledger/outbox/OutboxRelay.java`)
- Activity publisher → Kafka: sends activity
- Kafka → Activity projection: delivers events
- Activity projection → Activity and dedup: writes activity (evidence: `src/main/java/com/baran/ledger/projection/AccountActivityProjection.java`)
- Activity projection → Consumed events: deduplicates events (evidence: `src/main/java/com/baran/ledger/projection/AccountActivityProjection.java`)
- Reconciliation → Accounts store: checks balances (evidence: `src/main/java/com/baran/ledger/recon/ReconciliationJob.java`)
- Reconciliation → Entries store: sums postings (evidence: `src/main/java/com/baran/ledger/recon/ReconciliationJob.java`)
- Retention jobs → Outbox store: archives published (evidence: `src/main/java/com/baran/ledger/retention/OutboxArchivalJob.java`)
- Key cleanup → Idempotency store: cleans expired keys
- Prometheus → Transfer metrics: scrapes metrics
- Load scenarios → Transfer API: posts transfers (evidence: `load/k6/ledger.js`)
