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:
PendingSignUpholds email, hashed password, verification code, and code expiry while sign-up is incomplete.Useris the persistent account record stored throughUserRepository.AuthResponsecarries 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.loginreturns the messageAccount locked for 15 minuteswhenfailedLoginAttemptsreaches 3, but the code setslockedUntilwithLocalDateTime.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.