KaraboVilakazi/imali-banking-api

Production-grade banking REST API for the South African market # 🏦 Imali Banking API **A production-style retail banking REST API — concurrency-safe, audit-compliant, fraud-aware.** *Imali (isiZulu) — money.* *Full retail banking lifecycle — auth, accounts, deposits, withdrawals, transfers — with the real-world constraints a production system actually needs.* --- ## ⚡ Engineering Highlights ### Deadlock-Safe Concurrent Transfers Two users transferring money to each other simultaneously is the classic deadlock scenario. Imali prevents it by always acquiring pessimistic locks on both accounts in consistent UUID order before touching any balance. The order is deterministic regardless of which direction the transfer flows — so threads never wait on each other in a cycle. ### Audit Log That Survives Failures `AuditLogService` runs under `Propagation.REQUIRES_NEW` — its transaction commits independently of the parent. If a transfer fails and rolls back, the audit record of that attempt still exists. This mirrors real compliance requirements: the trail must be complete even when the operation wasn't. ### Balance Snapshots for Point-in-Time Reconstruction Every `Transaction` record stores `balanceAfter` at the moment it completes. Account state at any point in history can be read directly from a single row — no need to replay the full transaction history. ### Non-Blocking Fraud Detection Flagged transactions are not rejected. They proceed and are marked `flagged: true` with a `fraudReason`. This mirrors how real banking fraud systems work — quarantine for review, don't block the customer. A dedicated `FRAUD_FLAGGED` audit entry is written separately so the event is queryable independently of the transaction log. --- ## 🏗️ Architecture ``` Client │ ▼ [JwtAuthenticationFilter] ← validates Bearer token on every protected request │ ▼ [Controllers] ← AuthController / AccountController / TransactionController │ ▼ [Services] ├── AccountService ← Pessimistic locking, deadlock prevention ├── Transacti …