Wallet
Spring Boot wallet API with accounts, deposits, withdrawals, transfers, idempotency keys, optimistic locking, and JWT auth.
What it is
Wallet is a transactional account API in Spring Boot. It creates accounts, deposits, withdraws, and transfers money with idempotency keys, optimistic locking, and JWT auth. Replay the same key and you get the original result — not a double debit.
Architecture
JWT filter sits in front of the account and transfer controllers. Services run inside Spring transactions: a deposit writes a ledger row and updates the account balance in one commit. @Version on the account entity rejects concurrent writes with HTTP 409. Postgres is the source of truth; H2 is used in tests.
Client → JWT filter → Controllers
→ AccountService / TransactionService
→ JPA (@Transactional, @Version)
→ Postgres (accounts, transactions)API
All wallet endpoints require a Bearer token from POST /auth/login.
| Method | Path | What it does |
|---|---|---|
| POST | /auth/login | Issue a JWT |
| POST | /accounts | Create an account |
| GET | /accounts/{id} | Balance + owner |
| GET | /accounts/{id}/transactions | Ledger for one account |
| POST | /accounts/{id}/deposit | Credit with idempotency key |
| POST | /accounts/{id}/withdraw | Debit with idempotency key |
| POST | /transfers | Move funds between accounts |
Run locally
Postgres + app
docker compose up postgres -d ./gradlew bootRun
Full stack in Docker
./gradlew clean bootJar docker compose up -d --build
App on http://localhost:8080. Swagger at /swagger-ui/index.html. Java 21.
What the tests prove
Fourteen tests across repositories, services, and controllers. The concurrency test runs ten threads against one account: with @Version only one withdrawal wins; without it the balance can go negative. Service tests cover transactional rollback and idempotent replays.
./gradlew test