How muhaimin-mukammel/banking-system works
1. Overall shape
This is a single Spring Boot 3.5 Java 17 backend with a classic layered architecture: HTTP controllers at the edge, service interfaces plus implementations in the middle, JPA repositories for persistence, and entity/model classes for the banking domain.
2. Request entry path
Incoming requests hit /api/** endpoints in UserController, AccountController, and TransactionController. Before controller logic runs, requests pass through Spring Security and a custom rate-limit interceptor, so auth and throttling are enforced at the boundary.
3. Authentication and session model
The app is stateless and JWT-based. JwtAuthenticationFilter extracts and validates tokens, JwtService creates/parses them, and SecurityConfig wires the filter chain with BCrypt password hashing. There is no server-side session store.
4. Rate limiting subsystem
Rate limiting is implemented as a custom annotation and interceptor pair under annotation/ratelimit. RateLimitService uses Bucket4j with Caffeine-backed caching to track buckets per username or IP. This is applied globally to /api/**, with tighter limits on login, registration, and money-moving endpoints.
5. Domain boundaries
The core domain is split into User, Account, and Transaction entities, with enums for AccountType, TransactionType, and TransactionStatus. DTOs are kept separate for requests and responses, which isolates the API contract from persistence objects.
6. User subsystem
UserController exposes registration, login, profile retrieval/update, and password change. UserService handles account creation and credential logic, while repository access is limited to UserRepository. User identity also becomes the key for authenticated rate limiting.
7. Account subsystem
AccountController manages account creation, deposits, withdrawals, and transfers. AccountService encapsulates balance changes and account ownership checks. The repository layer includes account lookup methods needed for safe balance updates and locking.
8. Transaction subsystem
TransactionController serves transaction history and transaction lookups. TransactionService records and returns transaction state, including status tracking for pending/success/failed outcomes. Transaction endpoints sit close to account ownership boundaries, though one list endpoint currently returns all transactions.
9. Concurrency and consistency model
Money movement is protected with database-level pessimistic locking for critical operations, and the Account entity also uses optimistic versioning. Transfers lock accounts in a stable order to reduce deadlock risk. This makes the account service the main consistency boundary in the system.
10. Persistence and infrastructure
Data is stored in PostgreSQL via Spring Data JPA/Hibernate. Docker Compose provisions the database locally. Flyway is on the classpath, but schema creation is currently still handled by Hibernate ddl-auto=create-drop, so the persistence layer is not migration-driven yet.
11. Error and validation handling
Input validation is done with Jakarta Bean Validation on DTOs. Errors are normalized through GlobalExceptionHandler, which maps custom exceptions such as invalid credentials, insufficient balance, resource conflicts, not found, and rate-limit violations to precise HTTP responses.
12. Testing and quality boundary
The repo includes controller, service, and security tests using JUnit 5, Mockito, Spring Security Test, and MockMvc. The test suite mirrors the runtime boundaries: web layer, business logic, JWT/security utilities, and the application bootstrap.
13. What to draw in an architecture diagram
A good diagram would show: external clients → rate limit interceptor + security filter chain → controllers → services → repositories → PostgreSQL, with DTOs crossing the API boundary and entities staying inside the service/persistence boundary. Highlight the separate JWT, rate limiting, and exception-handling subsystems as cross-cutting concerns.
Main entry points: GlobalExceptionHandler.java Error handling · AccountService.java Account service · UserService.java User service · TransactionService.java Transaction service
Components 22
API edge
HTTP controllers and request boundary
- Clients · API consumers sending HTTP requests
- User API · Registration, login, profile, and password endpoints
src/main/java/com/banking/controller/UserController.java - Account API · Account creation and money movement endpoints
src/main/java/com/banking/controller/AccountController.java - Transaction API · Transaction history and lookup endpoints
src/main/java/com/banking/controller/TransactionController.java
Security
Authentication and rate limiting cross-cutting concerns
- Rate limit · Annotation-driven request throttling at the API boundary
src/main/java/com/banking/annotation/ratelimit/RateLimitInterceptor.java - Bucket4j cache · Per-user and per-IP bucket tracking with caching
src/main/java/com/banking/annotation/ratelimit/RateLimitService.java - JWT filter · Extracts and validates bearer tokens
src/main/java/com/banking/security/JwtAuthenticationFilter.java - JWT service · Creates and parses JWTs
src/main/java/com/banking/security/JwtService.java
Application
Service layer and business orchestration
- User service · User registration, profile, and credential flows
src/main/java/com/banking/service/UserService.java - Account service · Balance changes, ownership checks, and transfers
src/main/java/com/banking/service/AccountService.java - Transaction service · Transaction recording and history retrieval
src/main/java/com/banking/service/TransactionService.java
Domain
Banking entities, DTOs, and error models
- User · Authenticated banking user
src/main/java/com/banking/model/User.java - Account · Bank account with balance and versioning
src/main/java/com/banking/model/Account.java - Transaction · Recorded money movement and status
src/main/java/com/banking/model/Transaction.java - DTOs · Request and response models for auth, user, account, and transaction APIs
- Error handling · Custom exceptions and global HTTP mapping
src/main/java/com/banking/exception/GlobalExceptionHandler.java
Persistence
Repositories and database-backed storage
- User repo · User persistence and lookup
src/main/java/com/banking/repository/UserRepository.java - Account repo · Account lookup and locking queries
src/main/java/com/banking/repository/AccountRepository.java - Transaction repo · Transaction persistence and retrieval
src/main/java/com/banking/repository/TransactionRepository.java
Config
Application wiring and runtime configuration
- Security config · Wires the filter chain and password hashing
src/main/java/com/banking/config/SecurityConfig.java - Web config · Registers web interceptors and request rules
src/main/java/com/banking/config/WebConfig.java - Boot app · Application entry point
src/main/java/com/banking/BankingSystemApplication.java
Connections 29
- Clients → Rate limit: calls · All /api/** traffic is throttled before reaching controllers
- Clients → Security config: authenticates · Requests enter the JWT security filter chain
- Rate limit → Bucket4j cache: uses · Interceptor delegates bucket decisions to the rate-limit service
- Web config → Rate limit: registers · Web configuration applies the interceptor globally
- Security config → JWT filter: wires · Security configuration inserts the JWT filter into the chain
- JWT filter → JWT service: validates · Filter parses and verifies tokens via the JWT service
- User API → User service: uses · User API delegates business logic to the service
- Account API → Account service: uses · Account API delegates business logic to the service
- Transaction API → Transaction service: uses · Transaction API delegates business logic to the service
- User service → User repo: reads/writes · User workflows persist and load users
- Account service → Account repo: reads/writes · Account workflows persist and lock accounts
- Transaction service → Transaction repo: reads/writes · Transaction workflows persist and query transactions
- User repo → User: maps · Repository operates on user entities
- Account repo → Account: maps · Repository operates on account entities
- Transaction repo → Transaction: maps · Repository operates on transaction entities
- User API → DTOs: exchanges · Controllers use request and response DTOs
- Account API → DTOs: exchanges · Controllers use request and response DTOs
- Transaction API → DTOs: exchanges · Controllers use request and response DTOs
- User service → User: uses · Business logic works with persisted user state
- Account service → Account: uses · Business logic updates balances and ownership
- Transaction service → Transaction: uses · Business logic records transaction state
- Account service → Transaction service: emits · Money movement creates transaction records
- Security config → Boot app: boots · Security is part of the application startup wiring
- Error handling → User API: maps · Global handler turns domain errors into HTTP responses
- Error handling → Account API: maps · Global handler turns domain errors into HTTP responses
- Error handling → Transaction API: maps · Global handler turns domain errors into HTTP responses
- Account service → Error handling: raises · Balance, locking, and ownership failures surface as API errors
- User service → Error handling: raises · Credential and registration failures surface as API errors
- Bucket4j cache → Error handling: raises · Throttling failures become rate-limit exceptions