Product Scope and Requirements - Business Context, Objectives, and Stakeholders

Overview

This codebase implements a focused banking authentication scope. The application is centered on account creation, email verification, login, two-factor code delivery, and account lockout after repeated failed access attempts. The runtime entrypoint in src/main/java/com/bankasap/BankAsapApplication.java starts the Spring Boot application and exposes a PasswordEncoder bean that supports the authentication rules in AuthService.

The rest of src/main/java/com/bankasap/ is organized around that scope: AuthController receives client requests, AuthService applies the business rules, EmailService delivers verification and login codes, UserRepository persists verified users, and the DTO and model classes carry the request and response data that the business flow requires.

Business Context

The application’s business context is a controlled customer onboarding and access path for bank accounts. A user does not move directly from registration to a stored account record; instead, sign-up creates a temporary pending record, sends a code by email, and only persists a User after verification succeeds. Login is also code-based after password validation, which keeps the scope aligned with the authentication-first purpose of the system.

The code shows a clear split between temporary and persistent state:

  • PendingSignUp holds email, hashed password, verification code, and code expiry while sign-up is incomplete.
  • User is the persistent account record stored through UserRepository.
  • AuthResponse carries the message text returned to the client for each authentication outcome.

Objectives

Objective Source-backed support in the code Implementation areas
Register a user only after email verification AuthService.signUp creates a PendingSignUp, sends a code, and verifySignUp saves a User only when the code matches AuthController, AuthService, PendingSignUp, UserRepository
Protect credentials BankAsapApplication.passwordEncoder supplies a BCryptPasswordEncoder, and AuthService uses passwordEncoder.encode and passwordEncoder.matches BankAsapApplication, AuthService
Add a second verification step for login AuthService.login generates a code, stores it on User, and sends it through EmailService AuthService, EmailService, User
Limit repeated failed access attempts User tracks failedLoginAttempts and lockedUntil, and AuthService.login updates those fields after password failures User, AuthService
Return clear, human-readable status messages AuthController wraps every service result in AuthResponse.message AuthController, AuthResponse

Stakeholders and Expectations

Stakeholder Expectations reflected in the code Supporting behavior
Customer using the banking application Create an account with email and password, receive a verification code, log in with password plus code, and receive status messages that explain the result signUp, verifySignUp, login, verifyCode, resendSignUpCode, resendCode
Customer recovering access Request a new sign-up code or a new login code without starting over resendSignUpCode, resendCode
Backend operator or support function Account access is restricted through verification codes and lockout state after repeated failures User.failedLoginAttempts, User.lockedUntil, User.isLocked
Application runtime Authentication logic depends on email delivery, password encoding, and persistence services already present in the Spring context EmailService, PasswordEncoder, UserRepository

Implementation Areas in src/main/java/com/bankasap/

File path Role in the scope
src/main/java/com/bankasap/BankAsapApplication.java Starts the application and registers the PasswordEncoder bean used by authentication logic
src/main/java/com/bankasap/controller/AuthController.java Exposes the authentication actions that map the business requirements to HTTP requests
src/main/java/com/bankasap/service/AuthService.java Implements the sign-up, verification, login, and resend rules
src/main/java/com/bankasap/service/EmailService.java Sends verification and account-related emails through JavaMailSender
src/main/java/com/bankasap/repository/UserRepository.java Persists verified User records through CrudRepository
src/main/java/com/bankasap/model/User.java Stores the persistent account state, including lock and two-factor fields
src/main/java/com/bankasap/model/PendingSignUp.java Stores temporary sign-up state before the user is verified
src/main/java/com/bankasap/dto/AuthResponse.java Returns the message text shown to the client
src/main/java/com/bankasap/dto/SignUpRequest.java Carries sign-up input data
src/main/java/com/bankasap/dto/VerifySignUpRequest.java Carries sign-up verification input data
src/main/java/com/bankasap/dto/ResendSignUpCodeRequest.java Carries the email used to resend a sign-up code
src/main/java/com/bankasap/dto/LoginRequest.java Carries login input data
src/main/java/com/bankasap/dto/VerifyCodeRequest.java Carries login verification input data
src/main/java/com/bankasap/dto/ResendCodeRequest.java Carries the email used to resend a login code

Authentication Actions Exposed by the Scope

[!NOTE] AuthService.login returns the message Account locked for 15 minutes when failedLoginAttempts reaches 3, but the code sets lockedUntil with LocalDateTime.now().plusSeconds(15). The user-facing message and the runtime lock duration do not match.

The business scope is implemented as six HTTP actions in AuthController. Each one returns an AuthResponse with a message that explains the outcome of the request.

Sign Up

{
    "title": "Sign Up",
    "description": "Starts registration by validating the email and password, then sends a verification code by email.",
    "method": "POST",
    "baseUrl": "<ServiceBaseUrl>",
    "endpoint": "/signup",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"email\": \"[email protected]\",\n    \"password\": \"SecurePass1!\",\n    \"confirmPassword\": \"SecurePass1!\"\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": "Confirms the sign-up verification code and persists the new user record.",
    "method": "POST",
    "baseUrl": "<ServiceBaseUrl>",
    "endpoint": "/verify-signup",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"email\": \"[email protected]\",\n    \"code\": \"ABC123DEF4\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"message\": \"User registered successfully\"\n}"
        }
    }
}

Resend Sign Up Code

{
    "title": "Resend Sign Up Code",
    "description": "Issues a new sign-up verification code for a pending registration.",
    "method": "POST",
    "baseUrl": "<ServiceBaseUrl>",
    "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 credentials, starts two-factor verification, and sends a login code by email.",
    "method": "POST",
    "baseUrl": "<ServiceBaseUrl>",
    "endpoint": "/login",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"email\": \"[email protected]\",\n    \"password\": \"SecurePass1!\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"message\": \"2FA code sent to email\"\n}"
        }
    }
}

Verify Code

{
    "title": "Verify Code",
    "description": "Confirms the login two-factor code and completes the sign-in flow.",
    "method": "POST",
    "baseUrl": "<ServiceBaseUrl>",
    "endpoint": "/verify-code",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"email\": \"[email protected]\",\n    \"code\": \"ABC123DEF4\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"message\": \"Login successful\"\n}"
        }
    }
}

Resend Login Code

{
    "title": "Resend Login Code",
    "description": "Issues a new two-factor login code for an existing user.",
    "method": "POST",
    "baseUrl": "<ServiceBaseUrl>",
    "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}"
        }
    }
}

Major Requirement Flows

Sign Up and Verification Flow

sequenceDiagram
    participant U as Customer
    participant C as AuthController
    participant S as AuthService
    participant E as EmailService
    participant R as UserRepository

    U->>C: signUp
    C->>S: signUp
    S->>S: validate email password and confirmation
    S->>S: generateTwoFactorCode
    S->>E: sendTwoFactorCode
    E->>E: mailSender send
    S-->>C: Signup verification code sent to email
    C-->>U: AuthResponse message

    U->>C: verifySignUp
    C->>S: verifySignUp
    S->>R: save
    S-->>C: User registered successfully
    C-->>U: AuthResponse message

Login and Two-Factor Flow

sequenceDiagram
    participant U as Customer
    participant C as AuthController
    participant S as AuthService
    participant E as EmailService
    participant R as UserRepository

    U->>C: login
    C->>S: login
    S->>R: findAll
    S->>S: check password and lock state
    S->>E: sendTwoFactorCode
    E->>E: mailSender send
    S-->>C: 2FA code sent to email
    C-->>U: AuthResponse message

    U->>C: verifyCode
    C->>S: verifyCode
    S-->>C: Login successful
    C-->>U: AuthResponse message

Email Service

src/main/java/com/bankasap/service/EmailService.java is the outbound delivery point for authentication messages. It injects JavaMailSender and uses SimpleMailMessage to send the code-based messages that support both sign-up verification and login verification.

Method Role in the scope
sendTwoFactorCode Sends the verification code email with subject Bank ASAP - 2FA Code and the code in the message body
sendAccountLockedEmail Sends the account-locked notification with subject Bank ASAP - Account Locked

Persistence and Temporary State

The business rules depend on two different kinds of state:

State Location Purpose
Temporary sign-up state pendingSignUps in AuthService, represented by PendingSignUp Holds the email, hashed password, code, and expiry until sign-up is verified
Persistent user state User saved through UserRepository Stores the verified account record and authentication lock and two-factor fields

User is mapped to the AllUsers table through JPA annotations, which aligns the scope with persistent customer identity storage after verification. PendingSignUp remains an in-memory structure, so the sign-up scope is split between a temporary enrollment stage and a persisted account stage.

Application Bootstrap

src/main/java/com/bankasap/BankAsapApplication.java provides the runtime entrypoint for the scope. The main method starts the Spring Boot application, and the passwordEncoder bean returns a BCryptPasswordEncoder so the authentication service can encode and compare passwords consistently.

Bootstrap element Business purpose
main Launches the Bank ASAP application
passwordEncoder [REDACTED]

Scope Boundaries

The code in src/main/java/com/bankasap/ is centered on authentication and account access control. It supports the business context described above by handling sign-up, verification, login, resend actions, persistence of verified users, and email delivery of codes.