How ayshasharaf/double-entry-ledger works
DoubleLedger is a REST ledger service: callers create accounts, submit balanced multi-leg postings, read balances and transaction history, and reverse entries. The controller hashes requests and delegates posting or reversal through idempotency handling; posting validates and persists journal legs, while account and transaction reads assemble responses from stored records. PostgreSQL is the source of truth, with advisory and row locks protecting concurrent work. The graph follows README capabilities and sampled calls; unsampled wiring is omitted.
Main entry points: LedgerPostingService.java Posting and reversal · LedgerController.java Ledger controller · IdempotencyService.java Idempotency service · JournalEntryResponseService.java Journal responses
Components 17
HTTP API
- Ledger controller
ledger/src/main/java/com/doubleledger/ledger/controller/LedgerController.java - Exception mapping
ledger/src/main/java/com/doubleledger/ledger/controller/GlobalExceptionHandler.java
Ledger operations
- Account service
ledger/src/main/java/com/doubleledger/ledger/service/AccountService.java - Balance service
ledger/src/main/java/com/doubleledger/ledger/service/AccountBalanceService.java - Posting and reversal
ledger/src/main/java/com/doubleledger/ledger/service/LedgerPostingService.java - Journal responses
ledger/src/main/java/com/doubleledger/ledger/service/JournalEntryResponseService.java
Persistence
- Account repository
ledger/src/main/java/com/doubleledger/ledger/repository/AccountRepository.java - Journal repository
ledger/src/main/java/com/doubleledger/ledger/repository/JournalEntryRepository.java - Ledger repository
ledger/src/main/java/com/doubleledger/ledger/repository/LedgerEntryRepository.java - Idempotency repository
ledger/src/main/java/com/doubleledger/ledger/repository/IdempotencyKeyRepository.java
Reliability
- Request hasher
ledger/src/main/java/com/doubleledger/ledger/util/RequestHasher.java - Idempotency service
ledger/src/main/java/com/doubleledger/ledger/service/IdempotencyService.java - Advisory locks
ledger/src/main/java/com/doubleledger/ledger/persistence/PostgresAdvisoryLockService.java - Forensic audit
ledger/src/main/java/com/doubleledger/ledger/audit/ForensicAuditService.java - Async audit logger
ledger/src/main/java/com/doubleledger/ledger/audit/AsyncForensicAuditLogger.java
Other components
- API client
- PostgreSQL
Connections 28
- API client → Ledger controller: calls REST API
- Ledger controller → Account service: manages accounts
- Ledger controller → Request hasher: hashes requests
- Ledger controller → Idempotency service: guards writes
- Ledger controller → Posting and reversal: reads entries
- Ledger controller → Journal responses: reads transaction
- Ledger controller → Exception mapping: maps failures
- Idempotency service → Posting and reversal: invokes action
- Idempotency service → Journal responses: builds response
- Idempotency service → Idempotency repository: reads and writes cache
- Idempotency service → Advisory locks: locks key
- Account service → Account repository: reads and writes accounts
- Account service → Balance service: computes responses
- Balance service → Ledger repository: sums entries
- Posting and reversal → Account repository: locks accounts
- Posting and reversal → Journal repository: reads and writes journals
- Posting and reversal → Ledger repository: reads and writes legs
- Posting and reversal → Balance service: checks balances
- Posting and reversal → Advisory locks: serializes operations
- Posting and reversal → Forensic audit: reports failures
- Journal responses → Journal repository: loads journal
- Journal responses → Ledger repository: loads legs
- Forensic audit → Async audit logger: dispatches failures
- Account repository → PostgreSQL: persists accounts
- Journal repository → PostgreSQL: persists journals
- Ledger repository → PostgreSQL: persists ledger legs
- Idempotency repository → PostgreSQL: persists replay cache
- Advisory locks → PostgreSQL: acquires advisory lock