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 inside AuthResponse.message rather 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.login returns "Account locked for 15 minutes" after three failed attempts, but the code sets lockedUntil with LocalDateTime.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

  • signUp creates a PendingSignUp entry in pendingSignUps.
  • verifySignUp removes the pending entry after creating the persisted User.
  • resendSignUpCode updates the code and expiry on the existing PendingSignUp.
  • login updates failedLoginAttempts, lockedUntil, twoFactorCode, and twoFactorCodeExpiresAt on the User.
  • verifyCode clears twoFactorCode and twoFactorCodeExpiresAt.
  • resendCode generates a new twoFactorCode and expiry for the same User.

Validation and Response Strings

[!NOTE] The only explicit repository save in this class is userRepository.save(newUser) inside verifySignUp. The later User field updates in login, verifyCode, and resendCode are performed on the object returned from findUserByEmail without a corresponding save call in the source.

  • signUp returns:
    • "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"
  • verifySignUp returns:
    • "No signup process was started"
    • "Signup code expired"
    • "Invalid signup verification code"
    • "User registered successfully"
  • resendSignUpCode returns:
    • "No signup process was started"
    • "New signup verification code sent to email"
  • login returns:
    • "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"
  • verifyCode returns:
    • "User not found"
    • "No 2FA code was generated"
    • "2FA code expired"
    • "Invalid 2FA code"
    • "Login successful"
  • resendCode returns:
    • "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