How ashwinn-si/banking_application works
This repository is a Spring Boot backend for a banking platform. Its architecture is a classic layered server application with additional cross-cutting concerns for security, auditing, async notifications, and infrastructure integration.
1) High-level system shape
The application is organized around these major boundaries:
• HTTP/API layer: Controller
• Business logic layer: Service
• Persistence layer: Repository and Domain
• Transport models: DTO
• Cross-cutting concerns: Config, Utils
• Async messaging: Kafka
• Startup/bootstrap: BankingApplication, DatabaseSeeder
The system exposes REST APIs for:
• authentication
• account management
• transactions
• admin-only transaction operations
• OTP-related flows
The backend likely talks to:
• a relational database via Spring Data JPA
• Redis for rate limiting and/or caching use cases
• Kafka for asynchronous email delivery
• an email subsystem through Kafka-backed events rather than direct synchronous mail sending
2) Main functional subsystems
Authentication and authorization
Classes involved:
• AuthController
• AuthService
• JwtService
• BcryptService
• SecurityConfig
• JwtFilter
• AdminFilter
• User, Admin, RoleEnum
• JwtDTO
This subsystem handles:
• user signup and login
• admin login
• JWT issuance and validation
• password hashing
• role-based access control
The request flow is likely:
1. A client calls an auth endpoint.
2. AuthService validates credentials.
3. BcryptService hashes/checks passwords.
4. JwtService creates a JWT.
5. SecurityConfig and JwtFilter protect downstream endpoints by validating JWTs on incoming requests.
6. AdminFilter adds an additional boundary for admin-only routes.
This is the main security boundary for the system.
Account management
Classes involved:
• AccountController
• AccountService
• AccountRepository
• Account
• AccountDTO
• GetAllDTO
• UserService
• UserRepository
• User
This subsystem handles:
• creating accounts
• fetching account details
• listing accounts for a user
The service layer probably enforces ownership and access rules before reading or modifying account state. The controller layer only exposes the API; all validation and persistence logic sits below it.
Transaction management
Classes involved:
• TransactionController
• TranscationService (note the spelling in the codebase)
• TransactionRepository
• Transaction
• TranscationDTO
• enums:
- TransactionTypeEnum
- TransactionStatusEnum
• account and user services/repositories
The README and naming indicate a transaction workflow with safety checks:
• withdraw
• transfer
• deposit
• transaction history
• transaction details
• a start/confirm flow
• transaction expiry window
• balance validation
This subsystem is the core domain workflow and likely coordinates multiple repositories:
• reads current account balances
• verifies ownership and permissions
• creates or updates transaction records
• changes account balances in a transactional boundary
• stores status transitions using the transaction status enum
The Transaction entity is probably the source of truth for lifecycle state, while account balances are updated atomically in the service layer.
OTP flow
Classes involved:
• OtpController
• OtpService
• Otp
• OtpRepository
• OtpStatusEnum
This suggests a secondary verification or confirmation mechanism. The presence of OTP entities and statuses implies OTP issuance, validation, and expiry handling. In a banking context, this likely supports transaction confirmation or sensitive action verification.
Audit logging
Classes involved:
• AuditAspect
• Auditable
• AuditLog
• AuditLogService
• AuditLogRepository
This is a cross-cutting subsystem that records important domain actions. The aspect-based design means auditing is not embedded directly in controllers/services; instead, annotated methods are intercepted and persisted as audit entries.
This boundary is important in an architecture diagram because it sits alongside the main request flow and persists operational history independently of business entities.
Async email notifications
Classes involved:
• EmailProducer
• EmailConsumer
• EmailServiceWrapper
• EmailEventDTO
• EmailContentDTO
• EmailType
• Kafka config classes
This subsystem decouples notification generation from request handling.
Likely flow:
1. A service publishes an email event.
2. EmailProducer sends the event to Kafka.
3. EmailConsumer receives the event.
4. EmailServiceWrapper prepares or forwards the email content.
5. Actual email delivery is handled asynchronously.
This is a classic event-driven boundary: request handlers do not send mail directly, which reduces latency and isolates failures.
3) Request/data flow by API area
Authentication flow
• Client hits AuthController.
• AuthService performs signup/login logic.
• Passwords are handled through BcryptService.
• JWT is created via JwtService.
• Response data is returned using DTOs such as JwtDTO and UserDTO.
• Subsequent requests include the JWT and are validated by JwtFilter.
Account flow
• Client calls AccountController.
• AccountService applies business rules such as ownership checks.
• AccountRepository persists/loads Account records.
• Responses are shaped through DTOs like AccountDTO and GetAllDTO.
Transaction flow
• Client calls TransactionController.
• TranscationService validates account state, balance, roles, and transaction eligibility.
• TransactionRepository persists transaction records.
• Depending on transaction type and status, the service may:
- update account balances
- create audit entries
- emit email events through Kafka
• Admin-only transaction operations are separated under the admin path and guarded by role checks.
OTP flow
• Client calls OtpController.
• OtpService generates or validates OTPs.
• OtpRepository persists OTP records and status changes.
• This flow likely supports confirmation or step-up security.
4) Persistence boundary
The persistence layer is separated into:
• Repository interfaces for Spring Data JPA access
• Domain entities as the database model
Domain entities include:
• User
• Admin
• Account
• Transaction
• Otp
• AuditLog
This makes the architecture data-centric and relational. Service classes should be considered the boundary where invariants are enforced before persistence operations happen.
5) Cross-cutting infrastructure and configuration
Security configuration
• SecurityConfig defines the app’s protection model.
• JwtFilter authenticates requests.
• AdminFilter enforces admin boundaries.
This makes security an infrastructure layer wrapped around the controllers rather than embedded inside them.
Kafka configuration
Classes:
• KafkaProducerConfig
• KafkaConsumerConfig
• KafkaTopicConfig
These define the async messaging topology used by the email subsystem. Kafka is an external broker dependency and is part of the runtime architecture, not just a library detail.
Environment and runtime configuration
• EnvConfig
• application.properties
• .env
• pom.xml
These point to a configuration-driven deployment model. Secrets and environment-specific values include:
• database URL/user/password
• JWT secret and expiration
• salt value
• mail/Redis/Kafka settings
Global error handling and response formatting
• GlobalErrorHandler
• ResponseHandler
• CustomError
These establish a uniform API contract:
• errors are normalized centrally
• successful responses likely follow a standard wrapper
• exception handling is centralized rather than repeated in controllers
This is important for a diagram because it sits at the boundary of every controller response.
6) Supporting utilities and startup behavior
Utilities include:
• Constants
• EmailContextService
• DatabaseSeeder
These imply:
• shared constants used across services
• email message composition/context assembly
• startup seeding for local/dev data
The seeder suggests the app can bootstrap sample users/admins or other reference data on startup.
7) External systems and deployment dependencies
From the README and project files, the runtime environment depends on:
• Relational database: primary persistence for users, accounts, transactions, OTPs, audit logs
• Kafka: async event transport for email workflows
• Redis: mentioned for rate limiting and caching use cases
• Docker Compose: used to provision Redis, Kafka, and Zookeeper locally
The database is the core system of record, while Kafka and Redis are supporting infrastructure.
8) Architectural boundaries to show in a diagram
If you are drawing this repository, the key boundaries are:
1. Client boundary
- external API consumers
2. HTTP/controller boundary
- AuthController
- AccountController
- TransactionController
- OtpController
3. Security boundary
- SecurityConfig
- JwtFilter
- AdminFilter
- JWT creation/validation services
4. Business service boundary
- auth, account, transaction, otp, audit, user, admin services
5. Persistence boundary
- repositories and domain entities
- relational database
6. Async messaging boundary
- Kafka producer/consumer
- email event flow
7. Cross-cutting observability/error boundary
- auditing via aspect
- global exception handling
- response wrapping
9) What makes this repository distinct
This is not just a CRUD banking backend. Its architecture includes:
• secure JWT-based authentication
• admin/user role separation
• transaction state management with safety checks
• OTP support for sensitive operations
• auditing via AOP
• asynchronous email notifications via Kafka
• infrastructure-driven setup with Docker Compose
Overall, the system is a layered, domain-oriented Spring Boot service with strong separation between request handling, business rules, persistence, and asynchronous side effects.
Main entry points: TranscationService.java Txn Service · AccountService.java Account Service · UserService.java User Service · User.java Domain Models
Components 28
Bootstrap
Application startup and initialization
API Layer
HTTP controllers exposed to clients
- Auth API · Authentication and authorization endpoints
src/main/java/com/ashwinsi/bankingApplication/Controller/AuthController.java - Account API · Account management endpoints
src/main/java/com/ashwinsi/bankingApplication/Controller/AccountController.java - Txn API · Transaction workflow endpoints
src/main/java/com/ashwinsi/bankingApplication/Controller/TransactionController.java - OTP API · OTP verification and issuance endpoints
src/main/java/com/ashwinsi/bankingApplication/Controller/OtpController.java
Business Layer
Core application services and orchestration
- Auth Service · Login, signup, token issuance, and password checks
src/main/java/com/ashwinsi/bankingApplication/Service/AuthService.java - Account Service · Account creation and lookup rules
src/main/java/com/ashwinsi/bankingApplication/Service/AccountService.java - Txn Service · Transaction validation and balance updates
src/main/java/com/ashwinsi/bankingApplication/Service/TranscationService.java - OTP Service · OTP generation, validation, and expiry handling
src/main/java/com/ashwinsi/bankingApplication/Service/OtpService.java - User Service · User lookup and coordination helper
src/main/java/com/ashwinsi/bankingApplication/Service/UserService.java - Admin Service · Admin-facing coordination and checks
src/main/java/com/ashwinsi/bankingApplication/Service/AdminService.java - Audit Service · Persists audit records
src/main/java/com/ashwinsi/bankingApplication/Service/AuditLogService.java
Infrastructure
Security, configuration, and cross-cutting runtime concerns
- Security · HTTP security and filter chain setup
src/main/java/com/ashwinsi/bankingApplication/Config/SecurityConfig.java - JWT Filter · Validates bearer tokens on requests
src/main/java/com/ashwinsi/bankingApplication/Config/Filters/JwtFilter.java - Admin Filter · Enforces admin-only access boundaries
src/main/java/com/ashwinsi/bankingApplication/Config/Filters/AdminFilter.java - Error Handler · Centralized exception-to-response mapping
src/main/java/com/ashwinsi/bankingApplication/Config/GlobalErrorHandler.java - Audit Aspect · Intercepts auditable operations
src/main/java/com/ashwinsi/bankingApplication/Utils/AuditAspect.java
Async Messaging
Kafka-backed notification pipeline
- Email Facade · Builds and forwards email content
src/main/java/com/ashwinsi/bankingApplication/Service/EmailServiceWrapper.java - Kafka Producer · Publishes email events to Kafka
src/main/java/com/ashwinsi/bankingApplication/Kafka/EmailProducer.java - Kafka Consumer · Consumes email events from Kafka
src/main/java/com/ashwinsi/bankingApplication/Kafka/EmailConsumer.java
Persistence
Domain entities and repository interfaces
- User Repo · User persistence access
src/main/java/com/ashwinsi/bankingApplication/Repository/UserRepository.java - Admin Repo · Admin persistence access
src/main/java/com/ashwinsi/bankingApplication/Repository/AdminRepository.java - Account Repo · Account persistence access
src/main/java/com/ashwinsi/bankingApplication/Repository/AccountRepository.java - Txn Repo · Transaction persistence access
src/main/java/com/ashwinsi/bankingApplication/Repository/TransactionRepository.java - OTP Repo · OTP persistence access
src/main/java/com/ashwinsi/bankingApplication/Repository/OtpRepository.java - Audit Repo · Audit log persistence access
src/main/java/com/ashwinsi/bankingApplication/Repository/AuditLogRepository.java - Domain Models · Core banking entities and enums
src/main/java/com/ashwinsi/bankingApplication/Domain/User.java
Connections 31
- App → Seeder: starts · Bootstraps initial data on startup
- App → Security: wires · Initializes the security and filter chain
- App → Error Handler: registers · Installs centralized exception handling
- Security → JWT Filter: uses · Adds JWT validation to requests
- Security → Admin Filter: uses · Adds admin-only request boundaries
- Auth API → Auth Service: calls · Delegates authentication flows
- Account API → Account Service: calls · Delegates account operations
- Txn API → Txn Service: calls · Delegates transaction workflows
- OTP API → OTP Service: calls · Delegates OTP flows
- Auth Service → User Repo: reads/writes · Persists and loads users
- Auth Service → Domain Models: uses · Operates on user and role entities
- Account Service → Account Repo: reads/writes · Persists and loads accounts
- Account Service → User Service: coordinates · Resolves user ownership and access
- Account Service → Domain Models: uses · Works with account entities
- Txn Service → Txn Repo: reads/writes · Persists transaction lifecycle state
- Txn Service → Account Repo: updates · Adjusts account balances atomically
- Txn Service → User Service: checks · Validates ownership and access
- Txn Service → Audit Service: records · Emits audit entries for sensitive actions
- Txn Service → Email Facade: notifies · Triggers async email notifications
- OTP Service → OTP Repo: reads/writes · Persists OTP state and expiry
- OTP Service → Domain Models: uses · Works with OTP entities
- Admin Service → Admin Repo: reads/writes · Persists and loads admin data
- Admin Service → User Repo: queries · Coordinates user/admin lookup
- Audit Aspect → Audit Service: persists · Writes audit records after intercepted actions
- Audit Aspect → Audit Repo: stores · Backs audit log persistence
- Email Facade → Kafka Producer: publishes · Converts mail requests into Kafka events
- Kafka Producer → Kafka Consumer: delivers · Sends events through Kafka topics
- Kafka Consumer → Email Facade: processes · Consumes events and prepares delivery content
- Audit Service → Audit Repo: writes · Stores audit log entries
- User Service → User Repo: reads · Provides user lookup for other services
- User Service → Domain Models: uses · Works with user entities