# thnhan1/ibanking architecture

> Architecture diagram of the GitHub repository thnhan1/ibanking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thnhan1/ibanking
- Repository: https://github.com/thnhan1/ibanking

## Overview

##### Project Type and Purpose
- This is a Spring Boot–based RESTful backend API for handling tuition payments at TDTU University.
- It exposes endpoints under `/api/v1/` for authentication, tuition lookup, payment session creation, OTP handling, payment confirmation, and transaction history.
- It uses JWT for authentication/authorization, Mailtrap SMTP for OTP delivery, and PostgreSQL for persistence.

##### Main Architectural Layers & Components
a. Client Layer
- Web/Mobile frontend or API client (e.g., Postman, abc.http)
b. API & Security Layer
- Spring Security filters (JWT validation, CustomUserDetailsService)
- Controllers (`AuthController`, `TuitionController`, `PaymentController`, `UserController`)
c. Service Layer
- Business services (`AuthService`, `PaymentService`, `TuitionService`, `OtpNotificationService`, `UserService`, `JwtService`, `CurrentUserService`)
- Pessimistic locking and idempotency logic live here
d. Data Access Layer
- Spring Data JPA repositories (`AccountRepository`, `PaymentTransactionRepository`, `StudentRepository`, `TuitionFeeRepository`, `UserRepository`, `OtpTokenRepository`)
e. Persistence
- PostgreSQL database (entities: `User`, `Account`, `Student`, `TuitionFee`, `PaymentTransaction`, `OtpToken`, enums for statuses)
f. External Service
- Mailtrap SMTP (for sending OTP emails)

##### Relationships & Data Flow
- Client → HTTP Request → JWT Filter → Controllers → Services → Repositories → PostgreSQL
- Service → MailConfig → Mail Server (Mailtrap) → User email inbox
- Controllers validate via DTOs; Services map between DTOs and Entities; Repositories handle CRUD and locking.
- On login: AuthController → AuthService → JwtService → return JWT → client stores token.
- On payment session: PaymentController → PaymentService → generate OTP → OtpNotificationService → Mailtrap.
- On confirm: PaymentController → PaymentService (validate OTP, check balance, update entities) → Repository (pessimistic lock).

##### Key Patterns & Principles
- Layered (Controller → Service → Repository)
- DTOs separate API model from persistence model
- Dependency Injection (Spring-managed beans)
- JWT stateless auth
- Pessimistic locking for concurrency control
- Idempotency key support to prevent duplicate sessions
- Parameterized queries via Spring Data JPA to avoid SQL injection

##### Detailed Elements to Capture
- Security filter chain (JWT auth flow) preceding Controllers.
- Endpoint grouping by Controller.
- Service classes where OTP generation, idempotency, and locking occur.
- Database entities and how repositories map to them.
- Mail service integration for OTP delivery.
- Data flow for main user stories: login, tuition lookup, payment session creation, OTP confirmation, history retrieval.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Client (Web/Mobile/API)"]:::client

    %% Security Layer
    SecurityConfig["SecurityConfig\n(JWT Filter Chain)"]:::config
    CustomUserDetailsService["CustomUserDetailsService"]:::config

    %% Controllers
    AuthController["AuthController\n(/api/v1/auth)"]:::controller
    TuitionController["TuitionController\n(/api/v1/tuition)"]:::controller
    PaymentController["PaymentController\n(/api/v1/payment)"]:::controller
    UserController["UserController\n(/api/v1/users)"]:::controller

    %% Service Layer
    AuthService["AuthService"]:::service
    JwtService["JwtService"]:::service
    CurrentUserService["CurrentUserService"]:::service
    TuitionService["TuitionService"]:::service
    PaymentService["PaymentService"]:::service
    OtpNotificationService["OtpNotificationService"]:::service
    UserService["UserService"]:::service

    %% Data Access Layer
    AccountRepository["AccountRepository"]:::repo
    PaymentTransactionRepository["PaymentTransactionRepository"]:::repo
    StudentRepository["StudentRepository"]:::repo
    TuitionFeeRepository["TuitionFeeRepository"]:::repo
    UserRepository["UserRepository"]:::repo
    OtpTokenRepository["OtpTokenRepository"]:::repo

    %% Persistence
    Database[(PostgreSQL)]:::db

    %% External Service
    Mailtrap["Mailtrap SMTP"]:::external

    %% DTOs and Config
    DTOs["DTOs Package"]:::dto
    MailConfig["MailConfig"]:::config
    Application["IbankingApplication"]:::config

    %% Connections
    Client -->|"HTTP Request"| SecurityConfig
    SecurityConfig --> CustomUserDetailsService
    SecurityConfig --> AuthController
    SecurityConfig --> TuitionController
    SecurityConfig --> PaymentController
    SecurityConfig --> UserController

    AuthController -->|"login(), lookup(), session(), confirm(), history()"| AuthService
    AuthController --> AuthService
    AuthController --> JwtService
    AuthController --> CurrentUserService

    TuitionController --> TuitionService

    PaymentController --> PaymentService
    PaymentController --> AuthService

    UserController --> UserService

    AuthService --> JwtService
    AuthService --> UserRepository

    JwtService --> UserRepository

    CurrentUserService --> UserRepository

    TuitionService --> TuitionFeeRepository
    TuitionService --> StudentRepository

    PaymentService --> PaymentTransactionRepository
    PaymentService --> AccountRepository
    PaymentService --> TuitionFeeRepository
    PaymentService --> OtpTokenRepository
    PaymentService --> OtpNotificationService

    OtpNotificationService --> MailConfig
    OtpNotificationService -->|"sendOtp()"| Mailtrap

    %% Repositories to DB
    AccountRepository --> Database
    PaymentTransactionRepository --> Database
    StudentRepository --> Database
    TuitionFeeRepository --> Database
    UserRepository --> Database
    OtpTokenRepository --> Database

    %% Click Events
    click AuthController "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/controller/AuthController.java"
    click TuitionController "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/controller/TuitionController.java"
    click PaymentController "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/controller/PaymentController.java"
    click UserController "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/controller/UserController.java"
    click AuthService "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/service/AuthService.java"
    click PaymentService "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/service/PaymentService.java"
    click TuitionService "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/service/TuitionService.java"
    click OtpNotificationService "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/service/OtpNotificationService.java"
    click UserService "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/service/UserService.java"
    click JwtService "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/service/JwtService.java"
    click CurrentUserService "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/service/CurrentUserService.java"
    click AccountRepository "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/repository/AccountRepository.java"
    click PaymentTransactionRepository "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/repository/PaymentTransactionRepository.java"
    click StudentRepository "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/repository/StudentRepository.java"
    click TuitionFeeRepository "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/repository/TuitionFeeRepository.java"
    click UserRepository "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/repository/UserRepository.java"
    click OtpTokenRepository "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/repository/OtpTokenRepository.java"
    click SecurityConfig "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/config/SecurityConfig.java"
    click MailConfig "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/config/MailConfig.java"
    click CustomUserDetailsService "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/security/CustomUserDetailsService.java"
    click DTOs "https://github.com/thnhan1/ibanking/tree/main/src/main/java/vn/id/nhanbe/ibanking/dto/"
    click Application "https://github.com/thnhan1/ibanking/blob/main/src/main/java/vn/id/nhanbe/ibanking/IbankingApplication.java"

    %% Styles
    classDef client fill:#f9e79f,stroke:#000,stroke-width:1px;
    classDef controller fill:#aed6f1,stroke:#000,stroke-width:1px;
    classDef service fill:#abebc6,stroke:#000,stroke-width:1px;
    classDef repo fill:#f5b041,stroke:#000,stroke-width:1px;
    classDef db fill:#d5dbdb,stroke:#000,stroke-width:1px;
    classDef external fill:#f8c8dc,stroke:#000,stroke-width:1px;
    classDef config fill:#d6eaf8,stroke:#000,stroke-width:1px;
    classDef dto fill:#d2b4de,stroke:#000,stroke-width:1px;
```
