# muhaimin-mukammel/banking-system architecture

> Architecture diagram of the GitHub repository muhaimin-mukammel/banking-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muhaimin-mukammel/banking-system
- Repository: https://github.com/muhaimin-mukammel/banking-system

## Overview

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: [`src/main/java/com/banking/exception/GlobalExceptionHandler.java`](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/exception/GlobalExceptionHandler.java) (Error handling), [`src/main/java/com/banking/service/AccountService.java`](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/service/AccountService.java) (Account service), [`src/main/java/com/banking/service/UserService.java`](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/service/UserService.java) (User service), [`src/main/java/com/banking/service/TransactionService.java`](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/service/TransactionService.java) (Transaction service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["API edge"]
  node_clients(("Clients<br/>external"))
  node_user_controller["User API<br/>controller"]
  node_account_controller["Account API<br/>controller"]
  node_transaction_controller["Transaction API<br/>controller"]
end

subgraph group_security["Security"]
  node_rate_limit_interceptor["Rate limit<br/>web interceptor"]
  node_rate_limit_service["Bucket4j cache<br/>throttle service"]
  node_jwt_filter["JWT filter<br/>auth filter"]
  node_jwt_service["JWT service<br/>token service<br/>[JwtService.java]"]
end

subgraph group_app["Application"]
  node_user_service["User service<br/>business service<br/>[UserService.java]"]
  node_account_service["Account service<br/>business service"]
  node_transaction_service["Transaction service<br/>business service"]
end

subgraph group_domain["Domain"]
  node_user_entity[("User<br/>entity<br/>[User.java]")]
  node_account_entity[("Account<br/>entity<br/>[Account.java]")]
  node_transaction_entity[("Transaction<br/>entity<br/>[Transaction.java]")]
  node_dto_models["DTOs<br/>api contracts"]
  node_exceptions["Error handling<br/>exception layer"]
end

subgraph group_persistence["Persistence"]
  node_user_repo["User repo<br/>jpa repository"]
  node_account_repo["Account repo<br/>jpa repository"]
  node_transaction_repo["Transaction repo<br/>jpa repository"]
end

subgraph group_config["Config"]
  node_security_config["Security config"]
  node_web_config["Web config<br/>mvc config<br/>[WebConfig.java]"]
  node_application(("Boot app"))
end

node_clients -->|"calls"| node_rate_limit_interceptor
node_clients -->|"authenticates"| node_security_config
node_rate_limit_interceptor -->|"uses"| node_rate_limit_service
node_web_config -->|"registers"| node_rate_limit_interceptor
node_security_config -->|"wires"| node_jwt_filter
node_jwt_filter -->|"validates"| node_jwt_service
node_user_controller -->|"uses"| node_user_service
node_account_controller -->|"uses"| node_account_service
node_transaction_controller -->|"uses"| node_transaction_service
node_user_service -->|"reads/writes"| node_user_repo
node_account_service -->|"reads/writes"| node_account_repo
node_transaction_service -->|"reads/writes"| node_transaction_repo
node_user_repo -->|"maps"| node_user_entity
node_account_repo -->|"maps"| node_account_entity
node_transaction_repo -->|"maps"| node_transaction_entity
node_user_controller -->|"exchanges"| node_dto_models
node_account_controller -->|"exchanges"| node_dto_models
node_transaction_controller -->|"exchanges"| node_dto_models
node_user_service -->|"uses"| node_user_entity
node_account_service -->|"uses"| node_account_entity
node_transaction_service -->|"uses"| node_transaction_entity
node_account_service -->|"emits"| node_transaction_service
node_security_config -->|"boots"| node_application
node_exceptions -.->|"maps"| node_user_controller
node_exceptions -.->|"maps"| node_account_controller
node_exceptions -.->|"maps"| node_transaction_controller
node_account_service -.->|"raises"| node_exceptions
node_user_service -.->|"raises"| node_exceptions
node_rate_limit_service -.->|"raises"| node_exceptions

click node_user_controller "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/controller/UserController.java"
click node_account_controller "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/controller/AccountController.java"
click node_transaction_controller "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/controller/TransactionController.java"
click node_rate_limit_interceptor "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/annotation/ratelimit/RateLimitInterceptor.java"
click node_rate_limit_service "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/annotation/ratelimit/RateLimitService.java"
click node_jwt_filter "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/security/JwtAuthenticationFilter.java"
click node_jwt_service "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/security/JwtService.java"
click node_security_config "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/config/SecurityConfig.java"
click node_web_config "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/config/WebConfig.java"
click node_user_service "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/service/UserService.java"
click node_account_service "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/service/AccountService.java"
click node_transaction_service "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/service/TransactionService.java"
click node_user_repo "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/repository/UserRepository.java"
click node_account_repo "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/repository/AccountRepository.java"
click node_transaction_repo "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/repository/TransactionRepository.java"
click node_user_entity "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/model/User.java"
click node_account_entity "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/model/Account.java"
click node_transaction_entity "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/model/Transaction.java"
click node_exceptions "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/exception/GlobalExceptionHandler.java"
click node_application "https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/BankingSystemApplication.java"

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_clients,node_user_controller,node_account_controller,node_transaction_controller toneBlue
class node_rate_limit_interceptor,node_rate_limit_service,node_jwt_filter,node_jwt_service toneAmber
class node_user_service,node_account_service,node_transaction_service toneMint
class node_user_entity,node_account_entity,node_transaction_entity,node_dto_models,node_exceptions toneRose
class node_user_repo,node_account_repo,node_transaction_repo toneIndigo
class node_security_config,node_web_config,node_application toneTeal
```

## Components

### API edge

HTTP controllers and request boundary

- **Clients**: external · API consumers sending HTTP requests
- [User API](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/controller/UserController.java): controller · Registration, login, profile, and password endpoints · `src/main/java/com/banking/controller/UserController.java`
- [Account API](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/controller/AccountController.java): controller · Account creation and money movement endpoints · `src/main/java/com/banking/controller/AccountController.java`
- [Transaction API](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/controller/TransactionController.java): controller · Transaction history and lookup endpoints · `src/main/java/com/banking/controller/TransactionController.java`

### Security

Authentication and rate limiting cross-cutting concerns

- [Rate limit](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/annotation/ratelimit/RateLimitInterceptor.java): web interceptor · Annotation-driven request throttling at the API boundary · `src/main/java/com/banking/annotation/ratelimit/RateLimitInterceptor.java`
- [Bucket4j cache](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/annotation/ratelimit/RateLimitService.java): throttle service · Per-user and per-IP bucket tracking with caching · `src/main/java/com/banking/annotation/ratelimit/RateLimitService.java`
- [JWT filter](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/security/JwtAuthenticationFilter.java): auth filter · Extracts and validates bearer tokens · `src/main/java/com/banking/security/JwtAuthenticationFilter.java`
- [JWT service](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/security/JwtService.java): token service · Creates and parses JWTs · `src/main/java/com/banking/security/JwtService.java`

### Application

Service layer and business orchestration

- [User service](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/service/UserService.java): business service · User registration, profile, and credential flows · `src/main/java/com/banking/service/UserService.java`
- [Account service](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/service/AccountService.java): business service · Balance changes, ownership checks, and transfers · `src/main/java/com/banking/service/AccountService.java`
- [Transaction service](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/service/TransactionService.java): business service · Transaction recording and history retrieval · `src/main/java/com/banking/service/TransactionService.java`

### Domain

Banking entities, DTOs, and error models

- [User](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/model/User.java): entity · Authenticated banking user · `src/main/java/com/banking/model/User.java`
- [Account](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/model/Account.java): entity · Bank account with balance and versioning · `src/main/java/com/banking/model/Account.java`
- [Transaction](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/model/Transaction.java): entity · Recorded money movement and status · `src/main/java/com/banking/model/Transaction.java`
- **DTOs**: api contracts · Request and response models for auth, user, account, and transaction APIs
- [Error handling](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/exception/GlobalExceptionHandler.java): exception layer · Custom exceptions and global HTTP mapping · `src/main/java/com/banking/exception/GlobalExceptionHandler.java`

### Persistence

Repositories and database-backed storage

- [User repo](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/repository/UserRepository.java): jpa repository · User persistence and lookup · `src/main/java/com/banking/repository/UserRepository.java`
- [Account repo](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/repository/AccountRepository.java): jpa repository · Account lookup and locking queries · `src/main/java/com/banking/repository/AccountRepository.java`
- [Transaction repo](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/repository/TransactionRepository.java): jpa repository · Transaction persistence and retrieval · `src/main/java/com/banking/repository/TransactionRepository.java`

### Config

Application wiring and runtime configuration

- [Security config](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/config/SecurityConfig.java): security config · Wires the filter chain and password hashing · `src/main/java/com/banking/config/SecurityConfig.java`
- [Web config](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/config/WebConfig.java): mvc config · Registers web interceptors and request rules · `src/main/java/com/banking/config/WebConfig.java`
- [Boot app](https://github.com/muhaimin-mukammel/banking-system/blob/master/src/main/java/com/banking/BankingSystemApplication.java): spring boot app · Application entry point · `src/main/java/com/banking/BankingSystemApplication.java`

## Connections

- 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
