bank-management-spring-boot

Bank Management System - Full Documentation

1. Overview

This document provides system documentation for the Bank Management System. Originally a simple monolithic web application, it has been architected into a multi-container system with a separate frontend landing page and a Spring Boot backend, orchestrated by Docker and served through an Nginx reverse proxy.

The application simulates core banking functionalities including user management (Manager, Staff, Customer), account management, loan/FD applications, and grievance filing.

2. Features

2.1 Core Features

• Decoupled Frontend: A static landing page built with Vite and Tailwind CSS provides the initial entry point.
• Powerful Backend: The core business logic is handled by a robust Spring Boot application.
• Role-Based Access Control: Distinct functionalities and views for Manager, Staff, and Customer roles.
• Secure Login: Uses Spring Security for form-based, session-cookie authentication.
• Responsive UI: The dynamic application interface, built with Thymeleaf, is fully responsive.
• Production-Ready: The entire system is containerized with Docker and configured for a PostgreSQL database.

2.2 Manager Features (ROLE_MANAGER)

• Logs in using credentials seeded via data.sql.
• Creates new Staff users (assigns credentials).
• Views pending account opening requests initiated by Staff.
• Approves or rejects pending account requests.
  • Account approval activates the customer profile and enables their login credentials.
• Views pending Loan and Fixed Deposit (FD) applications submitted by Customers.
• Approves or rejects Loan and FD applications.
• Views all filed grievances (overview).

2.3 Staff Features (ROLE_STAFF)

• Logs in using credentials created by a Manager.
• Creates new Customer profiles, including initial login credentials and the first (pending) account (Savings or Current). This request goes to the Manager for approval.
• Performs Deposits and Withdrawals on active customer accounts (simulated - updates balance and creates transaction record).
• Views and resolves pending customer grievances.
• (Potential) Views customer profile update requests (implementation detail).

2.4 Customer Features (ROLE_CUSTOMER)

• Receives login credentials after their first account is approved by a Manager.
• Logs in using credentials set by Staff.
• Views their dashboard, including account summaries, loan status, FD status, and grievance status.
• Views detailed transaction history for their accounts.
• Applies for Loans (only if their profile/account is active).
• Applies for Fixed Deposits (FDs) (only if their profile/account is active).
• Files Grievances regarding bank services.
• Requests updates to their profile information (e.g., PAN, Address) - requires review/approval.

3. Architecture

The application was initially developed as a pure Spring Boot monolith. To gain experience with modern DevOps practices, Nginx, and a decoupled frontend, the architecture was evolved into a multi-container system.

The system is orchestrated by Docker Compose and consists of three main services:

3.1 Nginx Reverse Proxy (nginx service):

*   Acts as the single entry point for all web traffic.
*   Listens on ports 80 and 443.
*   Serves the static landing page for the root path (`/`).
*   Routes all other requests starting with `/login`, `/dashboard`, `/manager`, `/staff`, `/customer`, etc., to the Spring Boot backend service.
*   Handles SSL/TLS termination, providing HTTPS for the entire application.

3.2 Frontend (frontend service):

*   A static website built using **Vite + Tailwind CSS**.
*   This container runs an Nginx server configured to serve the compiled `dist` folder generated by the Vite build process.
*   Contains a "Login" button that links to the `/login` path, which is handled by the backend.

3.3 Backend (backend service):

The application follows principles of Clean Code Architecture, promoting separation of concerns and maintainability. The main layers are:

3.3.1 Presentation Layer (controller, templates)

• Handles HTTP requests using Spring MVC (@Controller).
• Uses Thymeleaf (*.html) for rendering dynamic HTML views.
• Interacts with the Application Layer via Service interfaces.
• Uses DTOs for data transfer to/from views.

3.3.2 Application Layer (service, service.impl, dto, mapper)

• Contains the core business logic and use cases.
• Defines Service interfaces (AccountService, UserService, etc.).
• Provides Service implementations (AccountServiceImpl, etc.) which orchestrate calls to repositories and enforce business rules.
• Uses Data Transfer Objects (DTOs) to decouple the domain model from the presentation layer.
• Uses Mappers (AccountMapper, etc.) to convert between Entities and DTOs.

3.3.3 Domain Layer (model, exception)

• Contains core business entities/aggregates like User, Account, Customer, Loan, etc.
• Entities are plain Java objects (POJOs), annotated with JPA for schema definition (even though JDBC is primarily used).
• Includes domain-specific exceptions (ResourceNotFoundException, InsufficientBalanceException, etc.).

3.3.4 Persistence Layer (repository, util)

• Manages all data persistence logic.
• Defines Repository interfaces (e.g., AccountRepository) using Spring Data conventions.
• Interfaces may be implemented manually or rely on Spring Data’s proxy-based implementations.
• Connects to a GCP Cloud SQL PostgreSQL database via JDBC.
• Utility classes like AccountNumberGenerator may reside here.

3.3.5 Security Layer (security)

• Configures and enforces application-level security using Spring Security.
• Includes components like:
  • SecurityConfig – defines HTTP security rules.
  • UserDetailsServiceImpl – loads user-specific data for authentication.
  • CustomAccessDeniedHandler – handles unauthorized access attempts.

Production Deployment Architecture:

• The three-container system (Nginx Proxy, Frontend, Backend) runs on a GCP Compute Engine VM.
• The database is a managed Aiven for PostgreSQL instance.
• The VM’s firewall allows traffic on ports 80/443.
• The backend container connects securely to the Cloud SQL instance, which has firewall rules to only allow connections from the VM.

4. Technology Stack

• Backend: Java 17+, Spring Boot 3.4.4, Spring Security, Spring Data JPA, Thymeleaf, Lombok, Maven
• Frontend: Vite, Tailwind CSS
• Database: PostgreSQL (JDBC Driver)
• Web Server / Proxy: Nginx
• Containerization: Docker, Docker Compose

5. Project Structure

The project structure has evolved to support the multi-container setup:

bank-management/
├── pom.xml # Maven build configuration
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/example/bankmanagement/
│ │ │ ├── BankManagementApplication.java # Main application class
│ │ │ ├── controller/ # Spring MVC Controllers (Presentation Layer)
│ │ │ ├── dto/ # Data Transfer Objects
│ │ │ ├── exception/ # Custom Exceptions & Global Handler
│ │ │ ├── mapper/ # DTO <-> Entity Mappers
│ │ │ ├── model/ # Domain Entities & Enums
│ │ │ ├── repository/ # Data Access Interfaces
│ │ │ ├── security/ # Spring Security Configuration
│ │ │ ├── service/ # Business Logic Interfaces
│ │ │ │ └── impl/ # Business Logic Implementations
│ │ │ └── util/ # Utility classes (e.g., AccountNumberGenerator)
│ │ └── resources/
│ │ ├── application.properties # Spring Boot configuration (DB, server, etc.)
│ │ ├── data.sql # Initial data seeding (Manager user)
│ │ ├── static/ # Static web resources (CSS, JS, images)
│ │ │ └── css/style.css
│ │ └── templates/ # Thymeleaf view templates (.html)
│ │ ├── layout.html # Main layout template
│ │ ├── login.html # Login page
│ │ ├── error.html # Generic error page
│ │ ├── dashboard-.html # Role-specific dashboards
│ │ ├── manager/ # Manager-specific views
│ │ ├── staff/ # Staff-specific views
│ │ └── customer/ # Customer-specific views
│ └── test/ # Unit and integration tests
├── frontend/ # Contains the Vite + Tailwind CSS landing page
├── nginx/ # Configuration for the reverse proxy
│ └── nginx.conf
├── Dockerfile # Instructions to build Docker image
├── Dockerfile.frontend # Instructions to build Docker image
└── docker-compose-db.yml # Running PostgreSQL locally with Docker Compose
└── docker-compose.prod.yml # Docker Compose for production
└── env.example # Template for environment variables

6. Database Schema

The database schema is derived from the JPA entity definitions in the model package. Key entities include:

• users (User.java): Stores login credentials (username, password), role (Enum: MANAGER, STAFF, CUSTOMER), and enabled status.
• managers (Manager.java): Manager-specific details, linked one-to-one with users.
• staff (Staff.java): Staff-specific details, linked one-to-one with users.
• customers (Customer.java): Customer profile information (name, email, phone, address, panNumber, active status), linked one-to-one with users.
• accounts (Account.java): Bank account details (accountNumber, balance, status [Enum: PENDING_APPROVAL, ACTIVE, etc.], accountType [Enum: SAVINGS, CURRENT]), linked many-to-one with customers and optionally managers (approver).
• transactions (Transaction.java): Records deposits/withdrawals (transactionType [Enum], amount, timestamp, description), linked many-to-one with accounts and optionally staff (performer). Note: Table name is transactions due to SQL keyword conflict.
• loans (Loan.java): Loan application details (loanAmount, interestRate, termMonths, status [Enum: PENDING, APPROVED, REJECTED, etc.]), linked many-to-one with customers and optionally managers (approver).
• fixed_deposits (FixedDeposit.java): FD details (principalAmount, interestRate, termMonths, maturityDate, status), linked many-to-one with customers and optionally managers (approver).
• grievances (Grievance.java): Customer grievance details (subject, description, status, submittedDate, resolvedDate), linked many-to-one with customers and optionally users (handler).

Key Enums: Role, AccountStatus, AccountType, RequestStatus, TransactionType.

7. Security Implementation

• Authentication: Handled by Spring Security’s form login mechanism (SecurityConfig.java).
  • Uses UserDetailsServiceImpl to load user data from the users table.
  • Uses BCryptPasswordEncoder for secure password hashing (jBCrypt recommended if not using Spring Security).
  • Login page at /login.
  • Redirects authenticated users away from /login.
• Authorization:
  • URL patterns are secured in SecurityConfig.java using http.authorizeHttpRequests() and role checks (.hasRole("MANAGER"), etc.).
  • .anyRequest().authenticated() ensures all other paths require login.
  • Method-level security can be added using @PreAuthorize (requires @EnableMethodSecurity).
• Access Denied Handling:
  • A CustomAccessDeniedHandler intercepts 403 Forbidden errors.
  • It redirects logged-in users to their respective dashboards instead of showing a generic error page if they try to access unauthorized areas.
• CSRF: Currently disabled (csrf(AbstractHttpConfigurer::disable)) for simplicity. Enable and configure properly for production.

8. Setup and Running Locally

Prerequisites:

• Java 17 JDK or later
• Apache Maven 3.6+
• Git (for cloning)
• Docker
• PostgreSQL database instance

Steps:

1. Clone the Repository:

   git clone https://github.com/frhanjav/bank-management-spring-boot.git
   cd bank-management-spring-boot
   

2. Update data.sql:
   • Open src/main/resources/data.sql.
   • IMPORTANT: Replace the placeholder bcrypt hash for the manager user with a hash generated for your desired password. You can use online tools or a simple Java program with BCryptPasswordEncoder.

3. Build the Application:

   ./mvnw clean package
   

4. Create .env File: The application is configured to read database credentials from an environment file. Copy the example file:

   cp env.example .env
   

5. Configure Credentials: Open the newly created .env file and fill in the connection details for your PostgreSQL database:

   # .env file
   DB_HOST=<your_database_host_ip>
   DB_PORT=<your_database_port>
   DB_NAME=<your_database_name>
   DB_USERNAME=<your_database_username>
   DB_PASSWORD=<your_database_password>
   

6. Run the Docker Container: Execute the docker run command, which pulls the image from GitHub Container Registry and injects the environment variables from your .env file.

    docker compose -f docker-compose-db.yml up -d
   

7. Run the Application:

   ./mvnw spring-boot:run
   # OR run the JAR directly:
   # java -jar target/bank-management-0.0.1-SNAPSHOT.jar
   

8. Access: Open your web browser and navigate to http://localhost:8080. You will be redirected to the login page (http://localhost:8080/login).

9. Login: Use the manager credentials (username: manager, password: the one you hashed and put in data.sql).

9. Key Workflows Summary

• Manager Seed: Initial Manager user/password created via data.sql.
• Staff Creation: Manager logs in -> Creates Staff user (sets username/password).
• Customer & Account Creation: Staff logs in -> Fills form with Customer details + initial username/password + selects Account Type -> Submits. System creates disabled User, inactive Customer, and PENDING_APPROVAL Account.
• Account Approval: Manager logs in -> Views Pending Accounts -> Approves request. System sets Account to ACTIVE, Customer to active=true, User to enabled=true.
• Customer Login: Customer can now log in with credentials set by Staff.
• Loan/FD Application: Active Customer logs in -> Applies for Loan/FD. Request status is PENDING.
• Loan/FD Approval: Manager logs in -> Views Pending Loans/FDs -> Approves/Rejects. Status is updated. Customer sees updated status on their dashboard.
• Grievance: Customer logs in -> Files Grievance. Status is PENDING. Staff/Manager can view/resolve. Customer sees status on dashboard.

---

This documentation provides a snapshot of the system. Refer to the source code for the most up-to-date implementation details.