Application Bootstrap and Codebase Structure - Application Entry Point and Package Responsibilities
Overview
src/main/java/com/bankasap/BankAsapApplication.java is the application entry point. It starts the Spring Boot runtime through SpringApplication.run and also publishes a PasswordEncoder bean backed by BCryptPasswordEncoder, which is then injected into the authentication service.
The codebase is partitioned by responsibility rather than by screen or workflow. controller owns HTTP request handling, dto carries request and response contracts, model contains domain state and the JPA entity, repository provides persistence access, and service contains authentication workflow logic plus email delivery.
Package Structure and Responsibilities
| Package | Path | Responsibility | Key types |
|---|---|---|---|
| Bootstrap | src/main/java/com/bankasap/BankAsapApplication.java |
Starts the Spring application and registers shared beans | BankAsapApplication |
| Controller | src/main/java/com/bankasap/controller/ |
Exposes authentication HTTP endpoints and adapts request bodies to service calls | AuthController |
| DTO | src/main/java/com/bankasap/dto/ |
Defines request and response payloads used at the HTTP boundary | AuthResponse, LoginRequest, ResendCodeRequest, ResendSignUpCodeRequest, SignUpRequest, VerifyCodeRequest, VerifySignUpRequest |
| Model | src/main/java/com/bankasap/model/ |
Holds application state and the persisted User entity |
PendingSignUp, User |
| Repository | src/main/java/com/bankasap/repository/ |
Provides persistence access for User records |
UserRepository |
| Service | src/main/java/com/bankasap/service/ |
Implements sign-up, login, verification, and email workflows | AuthService, EmailService |
Architecture and Dependency Flow
flowchart TB
subgraph bootstrap [Bootstrap]
n1[BankAsapApplication]
n2[passwordEncoder bean]
end
subgraph controller [Controller package]
n3[AuthController]
end
subgraph dto [DTO package]
n4[SignUpRequest]
n5[VerifySignUpRequest]
n6[ResendSignUpCodeRequest]
n7[LoginRequest]
n8[VerifyCodeRequest]
n9[ResendCodeRequest]
n10[AuthResponse]
end
subgraph model [Model package]
n11[PendingSignUp]
n12[User]
end
subgraph repository [Repository package]
n13[UserRepository]
end
subgraph service [Service package]
n14[AuthService]
n15[EmailService]
end
n1 --> n2
n3 --> n14
n3 --> n4
n3 --> n5
n3 --> n6
n3 --> n7
n3 --> n8
n3 --> n9
n3 --> n10
n14 --> n15
n14 --> n13
n14 --> n11
n14 --> n12
n13 --> n12
Bootstrap Entry Point
Bank Asap Application
src/main/java/com/bankasap/BankAsapApplication.java
BankAsapApplication is annotated with @SpringBootApplication, so it acts as both the launch point and the component-scan root for the application. Its main method delegates to SpringApplication.run(BankAsapApplication.class, args), which starts the Spring context.
The class also defines a passwordEncoder() bean that returns a BCryptPasswordEncoder. That bean is consumed by AuthService through constructor injection.
Public Methods
| Method | Description |
|---|---|
main |
Starts the Spring Boot application by running BankAsapApplication |
passwordEncoder |
[REDACTED] |
Bean Role
| Type | Description |
|---|---|
PasswordEncoder |
[REDACTED] |
Controller Package
Auth Controller
src/main/java/com/bankasap/controller/AuthController.java
AuthController is the HTTP boundary for the authentication feature set. It is annotated with @RestController and class-level @RequestMapping("/auth"), then maps individual POST handlers for sign-up, verification, login, and resend flows.
Each handler delegates immediately to AuthService and wraps the returned text in ResponseEntity.ok(new AuthResponse(message)). That means the controller keeps HTTP status handling uniform while the service decides the user-facing message.
Properties
| Property | Type | Description |
|---|---|---|
authService |
AuthService |
Service dependency used by every handler |
Constructor Dependencies
| Type | Description |
|---|---|
AuthService |
Executes authentication and verification workflows |
Public Methods
| Method | Description |
|---|---|
signUp |
Calls authService.signUp and returns the resulting message in AuthResponse |
verifySignUp |
Calls authService.verifySignUp and returns the resulting message in AuthResponse |
resendSignUpCode |
Calls authService.resendSignUpCode and returns the resulting message in AuthResponse |
login |
Calls authService.login and returns the resulting message in AuthResponse |
verifyCode |
Calls authService.verifyCode and returns the resulting message in AuthResponse |
resendCode |
Calls authService.resendCode and returns the resulting message in AuthResponse |
HTTP Contracts Exposed by the Controller
Sign Up
{
"title": "Sign Up",
"description": "Starts the sign-up workflow by validating the input, creating a pending sign-up record, and sending a verification code by email.",
"method": "POST",
"baseUrl": "/auth",
"endpoint": "/signup",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"email\": \"[email protected]\",\n \"password\": \"BankAsap!123\",\n \"confirmPassword\": \"BankAsap!123\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"message\": \"Signup verification code sent to email\"\n}"
}
}
}
Verify Sign Up
{
"title": "Verify Sign Up",
"description": "Completes sign-up after the verification code is validated and the pending user is stored.",
"method": "POST",
"baseUrl": "/auth",
"endpoint": "/verify-signup",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"email\": \"[email protected]\",\n \"code\": \"A1B2C3D4E5\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"message\": \"User registered successfully\"\n}"
}
}
}
Resend Sign Up Code
{
"title": "Resend Sign Up Code",
"description": "Generates a new sign-up verification code for an existing pending sign-up request and sends it by email.",
"method": "POST",
"baseUrl": "/auth",
"endpoint": "/resend-signup-code",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"email\": \"[email protected]\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"message\": \"New signup verification code sent to email\"\n}"
}
}
}
Login
{
"title": "Login",
"description": "Validates email and password, updates login attempt state, and sends a two-factor code by email.",
"method": "POST",
"baseUrl": "/auth",
"endpoint": "/login",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"email\": \"[email protected]\",\n \"password\": \"BankAsap!123\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"message\": \"2FA code sent to email\"\n}"
}
}
}
Verify Code
{
"title": "Verify Code",
"description": "Checks the login two-factor code and clears the stored code state when the code matches.",
"method": "POST",
"baseUrl": "/auth",
"endpoint": "/verify-code",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"email\": \"[email protected]\",\n \"code\": \"A1B2C3D4E5\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"message\": \"Login successful\"\n}"
}
}
}
Resend Login Code
{
"title": "Resend Login Code",
"description": "Generates a new login two-factor code and sends it by email for an existing user.",
"method": "POST",
"baseUrl": "/auth",
"endpoint": "/resend-login-code",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"email\": \"[email protected]\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"message\": \"New 2FA code sent to email\"\n}"
}
}
}
DTO Package
Auth Response
[!IMPORTANT] The controller always uses
ResponseEntity.ok. The service returns success and error outcomes as text insideAuthResponse.messagerather than through different HTTP status codes. [!NOTE] The class is prefixed with@RequestMapping("/auth"), so the runtime route composition includes that prefix. The extracted endpoint contracts below follow the verified method-level paths.
src/main/java/com/bankasap/dto/AuthResponse.java
AuthResponse is the single-field response envelope returned by AuthController. It carries the textual outcome of the service call in message.
Properties
| Property | Type | Description |
|---|---|---|
message |
String |
Human-readable result returned from the service layer |
Login Request
src/main/java/com/bankasap/dto/LoginRequest.java
LoginRequest carries the credentials used by the login endpoint.
Properties
| Property | Type | Description |
|---|---|---|
email |
String |
User email submitted to the login handler |
password |
String |
Raw password submitted to the login handler |
Resend Code Request
src/main/java/com/bankasap/dto/ResendCodeRequest.java
ResendCodeRequest identifies the account that should receive a new login verification code.
Properties
| Property | Type | Description |
|---|---|---|
email |
String |
User email submitted to the resend-code handler |
Resend Sign Up Code Request
src/main/java/com/bankasap/dto/ResendSignUpCodeRequest.java
ResendSignUpCodeRequest identifies the pending sign-up that should receive a new verification code.
Properties
| Property | Type | Description |
|---|---|---|
email |
String |
Email address used to locate the pending sign-up record |
Sign Up Request
src/main/java/com/bankasap/dto/SignUpRequest.java
SignUpRequest carries the credentials and confirmation value required to start registration.
Properties
| Property | Type | Description |
|---|---|---|
email |
String |
Requested account email |
password |
String |
Raw password supplied for registration |
confirmPassword |
String |
Confirmation value checked against password |
Verify Code Request
src/main/java/com/bankasap/dto/VerifyCodeRequest.java
VerifyCodeRequest carries the data required to verify the login two-factor code.
Properties
| Property | Type | Description |
|---|---|---|
email |
String |
Email address associated with the login attempt |
code |
String |
Two-factor code entered by the user |
Verify Sign Up Request
src/main/java/com/bankasap/dto/VerifySignUpRequest.java
VerifySignUpRequest carries the email and code required to complete registration.
Properties
| Property | Type | Description |
|---|---|---|
email |
String |
Email address associated with the pending sign-up |
code |
String |
Verification code sent during sign-up |
Model Package
Pending Sign Up
src/main/java/com/bankasap/model/PendingSignUp.java
PendingSignUp is the in-memory registration state used by AuthService before a user is persisted. It stores the email, the encoded password, the current verification code, and the code expiry timestamp.
Properties
| Property | Type | Description |
|---|---|---|
email |
String |
Email address waiting for sign-up verification |
hashedPassword |
String |
Encoded password stored until verification succeeds |
code |
String |
Current sign-up verification code |
codeExpiresAt |
LocalDateTime |
Expiration time for the current sign-up code |
User
src/main/java/com/bankasap/model/User.java
User is the persisted authentication entity. It is annotated with @Entity and @Table(name="AllUsers"), and it contains the login lockout and two-factor fields consumed by AuthService.
Properties
| Property | Type | Description |
|---|---|---|
id |
Long |
Generated primary key |
email |
String |
User email stored in the AllUsers table |
password |
String |
Stored password value used for password matching |
failedLoginAttempts |
int |
Counter updated during failed login attempts |
lockedUntil |
LocalDateTime |
Timestamp used by isLocked() to gate access |
twoFactorCode |
String |
Login verification code |
twoFactorCodeExpiresAt |
LocalDateTime |
Expiration time for the login verification code |
isLocked() checks whether lockedUntil is present and later than LocalDateTime.now(). That method is used by AuthService.login and AuthService.resendCode to block locked accounts.
Repository Package
User Repository
[!NOTE]
AuthService.loginreturns"Account locked for 15 minutes"after three failed attempts, but the code setslockedUntilwithLocalDateTime.now().plusSeconds(15). The stored lock duration and the returned message do not match.
src/main/java/com/bankasap/repository/UserRepository.java
UserRepository is the Spring Data repository boundary for User persistence. It extends CrudRepository<User,Long> and is the persistence dependency consumed by AuthService.
| Type | Role |
|---|---|
UserRepository |
Repository interface for User records |
CrudRepository<User,Long> |
Backing Spring Data contract used for CRUD access |
AuthService uses userRepository.findAll() inside findUserByEmail and uses userRepository.save(newUser) when sign-up verification succeeds.
Service Package
Auth Service
src/main/java/com/bankasap/service/AuthService.java
AuthService owns the authentication workflow. It validates registration input, stores pending sign-ups in memory, persists verified users, tracks login failures, generates two-factor codes, and delegates email delivery to EmailService.
It also keeps local state in pendingSignUps, which is an in-memory List<PendingSignUp>. The class uses DateTimeFormatter.ofPattern("dd/MM/yyyy HH:mm:ss") to render lock expiration timestamps in response messages.
Properties
| Property | Type | Description |
|---|---|---|
emailService |
EmailService |
Used to send two-factor and lock-related emails |
formatter |
DateTimeFormatter |
Formats lock expiration timestamps for user-facing messages |
passwordEncoder |
PasswordEncoder |
Hashes registration passwords and checks login passwords |
pendingSignUps |
List<PendingSignUp> |
In-memory list of pending registration records |
userRepository |
UserRepository |
Repository used to look up and persist User records |
Constructor Dependencies
| Type | Description |
|---|---|
EmailService |
Sends email notifications during auth workflows |
PasswordEncoder |
[REDACTED] |
UserRepository |
Loads and saves User records |
Public Methods
| Method | Description |
|---|---|
signUp |
Validates email and password rules, checks for existing users, stores a PendingSignUp, and sends a verification code |
verifySignUp |
Validates the sign-up code, creates a User, persists it with userRepository.save, and removes the pending record |
resendSignUpCode |
Replaces the pending sign-up code and expiry, then sends a new verification email |
login |
Checks user credentials, increments failed attempts, optionally locks the account, creates a two-factor code, and sends it by email |
verifyCode |
Verifies the login two-factor code and clears the stored code state when validation succeeds |
resendCode |
Regenerates the login two-factor code for a user and sends it by email |
Authentication State Flow
signUpcreates aPendingSignUpentry inpendingSignUps.verifySignUpremoves the pending entry after creating the persistedUser.resendSignUpCodeupdates the code and expiry on the existingPendingSignUp.loginupdatesfailedLoginAttempts,lockedUntil,twoFactorCode, andtwoFactorCodeExpiresAton theUser.verifyCodeclearstwoFactorCodeandtwoFactorCodeExpiresAt.resendCodegenerates a newtwoFactorCodeand expiry for the sameUser.
Validation and Response Strings
[!NOTE] The only explicit repository save in this class is
userRepository.save(newUser)insideverifySignUp. The laterUserfield updates inlogin,verifyCode, andresendCodeare performed on the object returned fromfindUserByEmailwithout a correspondingsavecall in the source.
signUpreturns:"User already exists""Invalid email format""Password must be 8-20 characters and include uppercase letter, number, special character and letters""Passwords do not match""Signup verification code sent to email"
verifySignUpreturns:"No signup process was started""Signup code expired""Invalid signup verification code""User registered successfully"
resendSignUpCodereturns:"No signup process was started""New signup verification code sent to email"
loginreturns:"Invalid email or password""Account is locked until " + user.getLockedUntil().format(formatter)"Account locked for 15 minutes""Invalid email or password. Attempts: " + attempts"2FA code sent to email"
verifyCodereturns:"User not found""No 2FA code was generated""2FA code expired""Invalid 2FA code""Login successful"
resendCodereturns:"User not found""Account is locked until " + user.getLockedUntil().format(formatter)"New 2FA code sent to email"
Email Service
src/main/java/com/bankasap/service/EmailService.java
EmailService is the mail delivery boundary used by AuthService. It creates SimpleMailMessage instances and sends them through JavaMailSender.
Properties
| Property | Type | Description |
|---|---|---|
mailSender |
JavaMailSender |
Spring mail sender used to dispatch messages |
Constructor Dependencies
| Type | Description |
|---|---|
JavaMailSender |
Sends prepared mail messages |
Public Methods
| Method | Description |
|---|---|
sendTwoFactorCode |
Sends a message with subject Bank ASAP - 2FA Code and the supplied code in the body |
sendAccountLockedEmail |
Sends a message with subject Bank ASAP - Account Locked and a lockout notice in the body |
AuthService calls sendTwoFactorCode during sign-up, login, and resend flows. sendAccountLockedEmail is defined in the service but is not invoked by AuthService in the provided source.
Email Delivery Flow
sequenceDiagram
participant S as AuthService
participant E as EmailService
participant M as JavaMailSender
S->>E: sendTwoFactorCode
E->>M: send
M-->>E: void
E-->>S: void
Request Handling Flow
sequenceDiagram
participant U as User
participant C as AuthController
participant S as AuthService
participant R as UserRepository
participant E as EmailService
participant M as JavaMailSender
U->>C: POST /signup
C->>S: signUp
S->>R: findAll
S->>E: sendTwoFactorCode
E->>M: send
S-->>C: message
C-->>U: ResponseEntity AuthResponse