# noureddinefatimi/savings-account-api architecture

> Architecture diagram of the GitHub repository noureddinefatimi/savings-account-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/noureddinefatimi/savings-account-api
- Repository: https://github.com/noureddinefatimi/savings-account-api

## Overview

1. This is a Spring Boot 2.7 REST API for savings-account management, built with Java 11 and Maven and persisted in MySQL. The runtime boundary is a single backend service: HTTP requests come in, are secured, mapped to controllers, translated through DTOs/services, and stored via Spring Data repositories.

2. The application entry point is `com.example.demo.DemoApplication`. Configuration lives in `src/main/resources/application.properties`, which is where the MySQL connection and other runtime settings are expected to be defined.

3. The domain model is centered on four entities in `com.example.model`: `User`, `Role`, `Contrat`, and `Prelevement`. These represent the core business objects for account holders, authorization roles, savings contracts, and withdrawal operations.

4. The API surface is split by business capability:
   - `AdminController` for administrative endpoints
   - `ContratController` for contract management
   - `PrelevementController` for withdrawal processing  
   The README describes the external REST paths as user-, contract-, and withdrawal-oriented APIs.

5. Request/response boundaries are explicit. Each major resource has DTOs in `com.example.dto`:
   - `UserRequestDTO` / `UserResponseDTO`
   - `RoleRequestDTO` / `RoleResponseDTO`
   - `ContratRequestDTO` / `ContratResponseDTO`
   - `PrelevementRequestDTO` / `PrelevementResponseDTO`  
   This indicates the API does not expose JPA entities directly; controllers exchange shaped payloads with clients.

6. Persistence is handled through Spring Data repositories in `com.example.repository`: `UserRepository`, `RoleRepository`, `ContratRepository`, and `PrelevementRepository`. These form the direct data-access layer between business logic and MySQL.

7. The service layer is present for user and role concerns via `UserService` and `RoleService`. That suggests business rules, validation, and role/user lifecycle logic are centralized there, while the domain controllers likely orchestrate their respective use cases above the repositories.

8. Security is a first-class subsystem. `SecurityConfig` defines the Spring Security setup, and the custom `CustomAuthenticationEntryPoint` and `CustomAccessDeniedHandler` indicate standardized handling for unauthenticated and unauthorized requests. The README states JWT authentication, so the intended architecture is a secured API rather than an open public service.

9. Error handling is centralized in `com.example.Exceptions` and `com.example.ErrorDetails`. `GlobalException`, `Result`, `StatusCode`, and `ErrorDetails` imply a shared error-response contract so controllers can return consistent failure payloads instead of ad hoc exceptions.

10. API documentation is part of the delivery surface. The README points to Swagger UI/OpenAPI, and the `src/main/resources/static` images suggest the repo includes documentation assets and screenshots rather than a separate front end.

11. From an architectural-diagram perspective, the main flow is: client → Spring Security filter/config → controller → DTO mapping → service/business logic → repository → MySQL, with exceptions routed through the global error layer and standardized responses returned to the client.

12. Test coverage appears minimal in the tree: there is only the default `DemoApplicationTests`, so the repo is currently structured more as a feature-complete API skeleton than as a heavily tested system.

Main entry points: [`src/main/java/com/example/controller/AdminController.java`](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/controller/AdminController.java) (Admin API), [`README.md`](https://github.com/noureddinefatimi/savings-account-api/blob/master/README.md) (README), [`src/main/java/com/example/controller/ContratController.java`](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/controller/ContratController.java) (Contrat API), [`src/main/java/com/example/controller/PrelevementController.java`](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/controller/PrelevementController.java) (Prelevement API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app(("DemoApp<br/>boot app"))
end

subgraph group_api["API"]
  node_admin_ctrl["Admin API<br/>controller"]
  node_contrat_ctrl["Contrat API<br/>controller"]
  node_prelevement_ctrl["Prelevement API<br/>controller"]
  node_user_dto["User DTOs<br/>dto bundle"]
  node_role_dto["Role DTOs<br/>dto bundle"]
  node_contrat_dto["Contrat DTOs<br/>dto bundle"]
  node_prelevement_dto["Prelevement DTOs<br/>dto bundle"]
end

subgraph group_domain["Domain"]
  node_user_service["User Service<br/>[UserService.java]"]
  node_role_service["Role Service<br/>[RoleService.java]"]
  node_user_model[("User<br/>entity<br/>[User.java]")]
  node_role_model[("Role<br/>entity<br/>[Role.java]")]
  node_contrat_model[("Contrat<br/>entity<br/>[Contrat.java]")]
  node_prelevement_model[("Prelevement<br/>entity<br/>[Prelevement.java]")]
end

subgraph group_infra["Infrastructure"]
  node_config["App Config<br/>properties"]
  node_security["Security"]
  node_auth_entry["Auth Entry<br/>security handler"]
  node_access_denied["Access Denied<br/>security handler"]
  node_user_repo["User Repo"]
  node_role_repo["Role Repo"]
  node_contrat_repo["Contrat Repo"]
  node_prelevement_repo["Prelevement Repo"]
end

subgraph group_crosscutting["Cross-cutting"]
  node_errors["Errors<br/>error contract"]
  node_details["Error Details<br/>error payload<br/>[ErrorDetails.java]"]
end

subgraph group_docs["Docs"]
  node_docs["README<br/>docs<br/>[README.md]"]
end

node_app -->|"boots with"| node_security
node_app -->|"reads"| node_config
node_security -->|"uses"| node_auth_entry
node_security -->|"uses"| node_access_denied
node_admin_ctrl -->|"exchanges"| node_user_dto
node_contrat_ctrl -->|"exchanges"| node_contrat_dto
node_prelevement_ctrl -->|"exchanges"| node_prelevement_dto
node_admin_ctrl -->|"orchestrates"| node_user_service
node_admin_ctrl -->|"orchestrates"| node_role_service
node_user_service -->|"persists via"| node_user_repo
node_user_service -->|"persists via"| node_role_repo
node_role_service -->|"persists via"| node_role_repo
node_contrat_ctrl -->|"loads/saves"| node_contrat_repo
node_prelevement_ctrl -->|"loads/saves"| node_prelevement_repo
node_user_repo -->|"maps"| node_user_model
node_role_repo -->|"maps"| node_role_model
node_contrat_repo -->|"maps"| node_contrat_model
node_prelevement_repo -->|"maps"| node_prelevement_model
node_contrat_ctrl -->|"handles via"| node_errors
node_prelevement_ctrl -->|"handles via"| node_errors
node_admin_ctrl -->|"handles via"| node_errors
node_errors -->|"formats"| node_details
node_docs -->|"describes"| node_security
node_docs -->|"describes"| node_admin_ctrl
node_docs -->|"describes"| node_contrat_ctrl
node_docs -->|"describes"| node_prelevement_ctrl

click node_app "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/demo/DemoApplication.java"
click node_config "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/resources/application.properties"
click node_security "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/config/SecurityConfig.java"
click node_auth_entry "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/config/CustomAuthenticationEntryPoint.java"
click node_access_denied "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/config/CustomAccessDeniedHandler.java"
click node_admin_ctrl "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/controller/AdminController.java"
click node_contrat_ctrl "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/controller/ContratController.java"
click node_prelevement_ctrl "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/controller/PrelevementController.java"
click node_user_service "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/service/UserService.java"
click node_role_service "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/service/RoleService.java"
click node_user_dto "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/dto/UserRequestDTO.java"
click node_role_dto "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/dto/RoleRequestDTO.java"
click node_contrat_dto "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/dto/ContratRequestDTO.java"
click node_prelevement_dto "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/dto/PrelevementRequestDTO.java"
click node_user_model "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/model/User.java"
click node_role_model "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/model/Role.java"
click node_contrat_model "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/model/Contrat.java"
click node_prelevement_model "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/model/Prelevement.java"
click node_user_repo "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/repository/UserRepository.java"
click node_role_repo "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/repository/RoleRepository.java"
click node_contrat_repo "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/repository/ContratRepository.java"
click node_prelevement_repo "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/repository/PrelevementRepository.java"
click node_errors "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/Exceptions/GlobalException.java"
click node_details "https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/ErrorDetails/ErrorDetails.java"
click node_docs "https://github.com/noureddinefatimi/savings-account-api/blob/master/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app toneBlue
class node_admin_ctrl,node_contrat_ctrl,node_prelevement_ctrl,node_user_dto,node_role_dto,node_contrat_dto,node_prelevement_dto toneAmber
class node_user_service,node_role_service,node_user_model,node_role_model,node_contrat_model,node_prelevement_model toneMint
class node_config,node_security,node_auth_entry,node_access_denied,node_user_repo,node_role_repo,node_contrat_repo,node_prelevement_repo toneRose
class node_errors,node_details toneIndigo
class node_docs toneTeal
```

## Components

### Runtime

Spring Boot application entry and runtime settings.

- [DemoApp](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/demo/DemoApplication.java): boot app · Spring Boot entry point. · `src/main/java/com/example/demo/DemoApplication.java`

### API

HTTP controllers and request/response boundary.

- [Admin API](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/controller/AdminController.java): controller · Administrative endpoints. · `src/main/java/com/example/controller/AdminController.java`
- [Contrat API](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/controller/ContratController.java): controller · Savings contract endpoints. · `src/main/java/com/example/controller/ContratController.java`
- [Prelevement API](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/controller/PrelevementController.java): controller · Withdrawal endpoints. · `src/main/java/com/example/controller/PrelevementController.java`
- [User DTOs](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/dto/UserRequestDTO.java): dto bundle · User request and response payloads. · `src/main/java/com/example/dto/UserRequestDTO.java`
- [Role DTOs](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/dto/RoleRequestDTO.java): dto bundle · Role request and response payloads. · `src/main/java/com/example/dto/RoleRequestDTO.java`
- [Contrat DTOs](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/dto/ContratRequestDTO.java): dto bundle · Contract request and response payloads. · `src/main/java/com/example/dto/ContratRequestDTO.java`
- [Prelevement DTOs](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/dto/PrelevementRequestDTO.java): dto bundle · Withdrawal request and response payloads. · `src/main/java/com/example/dto/PrelevementRequestDTO.java`

### Domain

Core business objects and persistence-facing contracts.

- [User Service](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/service/UserService.java): service · User lifecycle and business rules. · `src/main/java/com/example/service/UserService.java`
- [Role Service](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/service/RoleService.java): service · Role-related business logic. · `src/main/java/com/example/service/RoleService.java`
- [User](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/model/User.java): entity · Account holder domain model. · `src/main/java/com/example/model/User.java`
- [Role](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/model/Role.java): entity · Authorization role domain model. · `src/main/java/com/example/model/Role.java`
- [Contrat](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/model/Contrat.java): entity · Savings contract domain model. · `src/main/java/com/example/model/Contrat.java`
- [Prelevement](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/model/Prelevement.java): entity · Withdrawal operation domain model. · `src/main/java/com/example/model/Prelevement.java`

### Infrastructure

Security, persistence wiring, and application configuration.

- [App Config](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/resources/application.properties): properties · Runtime settings such as MySQL connection. · `src/main/resources/application.properties`
- [Security](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/config/SecurityConfig.java): spring security · JWT-oriented security configuration and access handling. · `src/main/java/com/example/config/SecurityConfig.java`
- [Auth Entry](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/config/CustomAuthenticationEntryPoint.java): security handler · Handles unauthenticated requests. · `src/main/java/com/example/config/CustomAuthenticationEntryPoint.java`
- [Access Denied](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/config/CustomAccessDeniedHandler.java): security handler · Handles unauthorized requests. · `src/main/java/com/example/config/CustomAccessDeniedHandler.java`
- [User Repo](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/repository/UserRepository.java): repository · Spring Data access for users. · `src/main/java/com/example/repository/UserRepository.java`
- [Role Repo](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/repository/RoleRepository.java): repository · Spring Data access for roles. · `src/main/java/com/example/repository/RoleRepository.java`
- [Contrat Repo](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/repository/ContratRepository.java): repository · Spring Data access for contracts. · `src/main/java/com/example/repository/ContratRepository.java`
- [Prelevement Repo](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/repository/PrelevementRepository.java): repository · Spring Data access for withdrawals. · `src/main/java/com/example/repository/PrelevementRepository.java`

### Cross-cutting

Shared error and response handling.

- [Errors](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/Exceptions/GlobalException.java): error contract · Shared exception and response format. · `src/main/java/com/example/Exceptions/GlobalException.java`
- [Error Details](https://github.com/noureddinefatimi/savings-account-api/blob/master/src/main/java/com/example/ErrorDetails/ErrorDetails.java): error payload · Standardized error response body. · `src/main/java/com/example/ErrorDetails/ErrorDetails.java`

### Docs

Repository documentation and examples.

- [README](https://github.com/noureddinefatimi/savings-account-api/blob/master/README.md): docs · API overview, Swagger notes, and usage examples. · `README.md`

## Connections

- DemoApp → Security: boots with · Application starts with security configuration.
- DemoApp → App Config: reads · Loads runtime properties.
- Security → Auth Entry: uses · Configures unauthenticated handling.
- Security → Access Denied: uses · Configures unauthorized handling.
- Admin API → User DTOs: exchanges · Uses shaped request/response payloads.
- Contrat API → Contrat DTOs: exchanges · Uses shaped request/response payloads.
- Prelevement API → Prelevement DTOs: exchanges · Uses shaped request/response payloads.
- Admin API → User Service: orchestrates · Delegates user admin logic.
- Admin API → Role Service: orchestrates · Delegates role logic.
- User Service → User Repo: persists via · Reads and writes user data.
- User Service → Role Repo: persists via · Resolves roles for users.
- Role Service → Role Repo: persists via · Reads and writes role data.
- Contrat API → Contrat Repo: loads/saves · Contract lifecycle persistence.
- Prelevement API → Prelevement Repo: loads/saves · Withdrawal lifecycle persistence.
- User Repo → User: maps · Repository manages user entity state.
- Role Repo → Role: maps · Repository manages role entity state.
- Contrat Repo → Contrat: maps · Repository manages contract entity state.
- Prelevement Repo → Prelevement: maps · Repository manages withdrawal entity state.
- Contrat API → Errors: handles via · Uses global exception contract.
- Prelevement API → Errors: handles via · Uses global exception contract.
- Admin API → Errors: handles via · Uses global exception contract.
- Errors → Error Details: formats · Produces standardized error bodies.
- README → Security: describes · Documents secured API behavior.
- README → Admin API: describes · Documents admin endpoints.
- README → Contrat API: describes · Documents contract endpoints.
- README → Prelevement API: describes · Documents withdrawal endpoints.
