# kgonzagao/todolistapi architecture

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

- Interactive diagram: https://gitdiagram.com/kgonzagao/todolistapi
- Repository: https://github.com/kgonzagao/todolistapi

## Overview

1. **Overall shape**
   - This is a single Spring Boot REST API organized as a layered monolith.
   - The code is split into two business modules: `auth` for identity/security and `module/task` for task management, plus shared `util` and `config` support.

2. **Request entrypoint**
   - `ToDoListApiApplication` boots the application.
   - HTTP requests enter through Spring MVC controllers, then move down into services, then repositories, and finally the database via Spring Data JPA.

3. **Authentication and authorization subsystem**
   - The `auth` package owns registration, login, token refresh, and user/account persistence.
   - Core entities are `UserEntity`, `RoleEntity`, and `PermissionEntity`, backed by `UserRepository` and `RoleRepository`.
   - This indicates role/permission-based access control rather than simple “authenticated vs anonymous” checks.

4. **JWT security boundary**
   - Security is centralized in `SecurityConfig` and the JWT utility/filter classes under `auth/util/jwt`.
   - `JwtAuthenticationFilter` sits in the request pipeline and validates tokens before protected endpoints are reached.
   - `JwtService` and `JwtSupport` handle token creation/validation and are shared across login and protected-request flows.

5. **Authentication flow**
   - `AuthController` accepts DTOs such as `RegisterUserRequest`, `LoginUserRequest`, and `RefreshTokenRequest`.
   - Requests are processed by `UserService` / `UserServiceImpl`, which likely creates users, verifies credentials, and issues JWT-backed `AuthResponse` payloads.
   - `AuthenticatedUserService` provides access to the current authenticated principal for downstream business logic.

6. **Task management subsystem**
   - `module/task` is the second major domain area and contains its own controller, service, persistence model, and request/response DTOs.
   - `TaskController` exposes CRUD endpoints; `TaskServiceImpl` contains the task rules; `TaskRepository` persists `TaskEntity`.
   - The README and DTO structure suggest task operations are scoped to the authenticated user, not globally shared.

7. **Data ownership and isolation**
   - Task access is logically bound to the current user identity from the auth subsystem.
   - That means security context data flows into the task service layer, where ownership checks and filtering are enforced before repository access or mutation.

8. **API contract boundary**
   - Controllers do not expose JPA entities directly; they use DTOs for both inbound requests and outbound responses.
   - This keeps the REST contract stable and separates transport concerns from persistence concerns.

9. **Common utility and error handling**
   - `util/common/PagedResponse` indicates list endpoints return structured pagination metadata rather than raw lists.
   - `GlobalExceptionHandler` centralizes HTTP error mapping for validation failures, missing resources, access problems, and domain exceptions like `UserAlreadyExistsException`.

10. **Persistence layer**
   - Persistence is implemented with Spring Data JPA repositories and entity classes under the two modules.
   - The architecture is relational-database oriented, with entities representing the main domain state and repositories mediating all database access.

11. **Validation and response shaping**
   - Bean Validation is used on request DTOs to enforce input constraints before services run.
   - The combination of DTOs, validation, and global exception handling suggests the API returns consistent error responses for invalid client input.

12. **Testing structure**
   - Tests mirror the production package structure, with coverage for entities, repositories, services, controllers, JWT utilities, and the global exception handler.
   - The presence of controller tests and repository tests suggests both unit and integration-style validation of the main request paths.

13. **Runtime and build tooling**
   - The project is built with Maven using the wrapper (`mvnw`), so it is intended to be run consistently across environments.
   - Configuration lives in `application.properties`, with a separate test properties file under `src/test/resources`.

14. **What to draw in an architecture diagram**
   - Show two primary business flows: authentication/security and task CRUD.
   - Place JWT/security as a cross-cutting gate in front of both protected endpoints.
   - Show controllers at the edge, services as the business layer, repositories as the persistence layer, and a shared exception/response utility layer spanning the API.

Main entry points: [`src/main/java/com/kg/ToDoListAPI/auth/service/impl/UserServiceImpl.java`](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/service/impl/UserServiceImpl.java) (User service), [`src/main/java/com/kg/ToDoListAPI/module/task/service/impl/TaskServiceImpl.java`](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/module/task/service/impl/TaskServiceImpl.java) (Task service), [`src/main/java/com/kg/ToDoListAPI/util/exception/GlobalExceptionHandler.java`](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/util/exception/GlobalExceptionHandler.java) (Errors), [`src/main/java/com/kg/ToDoListAPI/module/task/presentation/TaskController.java`](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/module/task/presentation/TaskController.java) (Task API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_bootstrap["Bootstrap"]
  node_node_app(("App"))
  node_node_security["Security<br/>Spring config"]
end

subgraph group_grp_auth["Auth"]
  node_node_auth_controller["Auth API<br/>REST controller"]
  node_node_auth_service["User service<br/>service layer"]
  node_node_auth_principal["Current user<br/>auth context"]
  node_node_jwt_filter["JWT filter<br/>security filter"]
  node_node_jwt_service["JWT service<br/>token service<br/>[JwtService.java]"]
  node_node_jwt_support["JWT support<br/>token helper<br/>[JwtSupport.java]"]
  node_node_user_repo[("User repo<br/>JPA repository")]
  node_node_role_repo[("Role repo<br/>JPA repository")]
  node_node_user_entity["User<br/>entity<br/>[UserEntity.java]"]
  node_node_role_entity["Role<br/>entity<br/>[RoleEntity.java]"]
  node_node_perm_entity["Permission<br/>entity"]
end

subgraph group_grp_task["Task"]
  node_node_task_controller["Task API<br/>REST controller"]
  node_node_task_service["Task service<br/>service layer"]
  node_node_task_repo[("Task repo<br/>JPA repository")]
  node_node_task_entity["Task<br/>entity<br/>[TaskEntity.java]"]
end

subgraph group_grp_shared["Shared"]
  node_node_paged["Paged response<br/>response util<br/>[PagedResponse.java]"]
  node_node_errors["Errors<br/>exception handler"]
end

node_node_app -->|"wires"| node_node_security
node_node_security -->|"registers"| node_node_jwt_filter
node_node_jwt_filter -->|"uses"| node_node_jwt_service
node_node_jwt_service -->|"delegates"| node_node_jwt_support
node_node_auth_controller -->|"calls"| node_node_auth_service
node_node_auth_service -->|"reads/writes"| node_node_user_repo
node_node_auth_service -->|"reads"| node_node_role_repo
node_node_auth_service -->|"issues"| node_node_jwt_service
node_node_auth_service -->|"uses"| node_node_auth_principal
node_node_user_repo -->|"persists"| node_node_user_entity
node_node_role_repo -->|"persists"| node_node_role_entity
node_node_role_entity -->|"contains"| node_node_perm_entity
node_node_task_controller -->|"calls"| node_node_task_service
node_node_task_service -->|"scopes by"| node_node_auth_principal
node_node_task_service -->|"reads/writes"| node_node_task_repo
node_node_task_repo -->|"persists"| node_node_task_entity
node_node_task_controller -->|"returns"| node_node_paged
node_node_auth_controller -->|"handled by"| node_node_errors
node_node_task_controller -->|"handled by"| node_node_errors
node_node_auth_service -->|"raises"| node_node_errors
node_node_task_service -->|"raises"| node_node_errors

click node_node_app "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/ToDoListApiApplication.java"
click node_node_security "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/config/SecurityConfig.java"
click node_node_auth_controller "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/presentation/controller/AuthController.java"
click node_node_auth_service "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/service/impl/UserServiceImpl.java"
click node_node_auth_principal "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/service/impl/AuthenticatedUserServiceImpl.java"
click node_node_jwt_filter "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/util/jwt/JwtAuthenticationFilter.java"
click node_node_jwt_service "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/util/jwt/JwtService.java"
click node_node_jwt_support "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/util/jwt/JwtSupport.java"
click node_node_user_repo "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/persistence/UserRepository.java"
click node_node_role_repo "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/persistence/RoleRepository.java"
click node_node_user_entity "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/persistence/UserEntity.java"
click node_node_role_entity "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/persistence/RoleEntity.java"
click node_node_perm_entity "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/persistence/PermissionEntity.java"
click node_node_task_controller "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/module/task/presentation/TaskController.java"
click node_node_task_service "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/module/task/service/impl/TaskServiceImpl.java"
click node_node_task_repo "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/module/task/persistence/TaskRepository.java"
click node_node_task_entity "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/module/task/persistence/TaskEntity.java"
click node_node_paged "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/util/common/PagedResponse.java"
click node_node_errors "https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/util/exception/GlobalExceptionHandler.java"

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_node_app,node_node_security toneBlue
class node_node_auth_controller,node_node_auth_service,node_node_auth_principal,node_node_jwt_filter,node_node_jwt_service,node_node_jwt_support,node_node_user_repo,node_node_role_repo,node_node_user_entity,node_node_role_entity,node_node_perm_entity toneAmber
class node_node_task_controller,node_node_task_service,node_node_task_repo,node_node_task_entity toneMint
class node_node_paged,node_node_errors toneRose
```

## Components

### Bootstrap

Application entrypoint and runtime wiring

- [App](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/ToDoListApiApplication.java): Spring Boot app · Application bootstrap and component scan entrypoint · `src/main/java/com/kg/ToDoListAPI/ToDoListApiApplication.java`
- [Security](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/config/SecurityConfig.java): Spring config · HTTP security configuration and filter chain · `src/main/java/com/kg/ToDoListAPI/config/SecurityConfig.java`

### Auth

Identity, security, and JWT flows

- [Auth API](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/presentation/controller/AuthController.java): REST controller · Registration, login, and token refresh endpoints · `src/main/java/com/kg/ToDoListAPI/auth/presentation/controller/AuthController.java`
- [User service](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/service/impl/UserServiceImpl.java): service layer · Creates users, authenticates credentials, and issues auth responses · `src/main/java/com/kg/ToDoListAPI/auth/service/impl/UserServiceImpl.java`
- [Current user](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/service/impl/AuthenticatedUserServiceImpl.java): auth context · Resolves the authenticated principal for downstream logic · `src/main/java/com/kg/ToDoListAPI/auth/service/impl/AuthenticatedUserServiceImpl.java`
- [JWT filter](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/util/jwt/JwtAuthenticationFilter.java): security filter · Validates bearer tokens before protected endpoints · `src/main/java/com/kg/ToDoListAPI/auth/util/jwt/JwtAuthenticationFilter.java`
- [JWT service](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/util/jwt/JwtService.java): token service · Creates and validates JWTs for login and request authentication · `src/main/java/com/kg/ToDoListAPI/auth/util/jwt/JwtService.java`
- [JWT support](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/util/jwt/JwtSupport.java): token helper · Shared JWT helper utilities used by security and auth flows · `src/main/java/com/kg/ToDoListAPI/auth/util/jwt/JwtSupport.java`
- [User repo](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/persistence/UserRepository.java): JPA repository · Persistence access for users and account data · `src/main/java/com/kg/ToDoListAPI/auth/persistence/UserRepository.java`
- [Role repo](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/persistence/RoleRepository.java): JPA repository · Persistence access for roles and permissions · `src/main/java/com/kg/ToDoListAPI/auth/persistence/RoleRepository.java`
- [User](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/persistence/UserEntity.java): entity · Account and identity aggregate root · `src/main/java/com/kg/ToDoListAPI/auth/persistence/UserEntity.java`
- [Role](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/persistence/RoleEntity.java): entity · Role-based authorization model · `src/main/java/com/kg/ToDoListAPI/auth/persistence/RoleEntity.java`
- [Permission](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/auth/persistence/PermissionEntity.java): entity · Fine-grained permission model for access control · `src/main/java/com/kg/ToDoListAPI/auth/persistence/PermissionEntity.java`

### Task

Task CRUD and ownership-scoped business logic

- [Task API](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/module/task/presentation/TaskController.java): REST controller · Task CRUD endpoints scoped to the authenticated user · `src/main/java/com/kg/ToDoListAPI/module/task/presentation/TaskController.java`
- [Task service](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/module/task/service/impl/TaskServiceImpl.java): service layer · Enforces task rules and ownership checks · `src/main/java/com/kg/ToDoListAPI/module/task/service/impl/TaskServiceImpl.java`
- [Task repo](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/module/task/persistence/TaskRepository.java): JPA repository · Persistence access for task records · `src/main/java/com/kg/ToDoListAPI/module/task/persistence/TaskRepository.java`
- [Task](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/module/task/persistence/TaskEntity.java): entity · Task domain state · `src/main/java/com/kg/ToDoListAPI/module/task/persistence/TaskEntity.java`

### Shared

Cross-cutting utilities and error handling

- [Paged response](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/util/common/PagedResponse.java): response util · Shared pagination envelope for list endpoints · `src/main/java/com/kg/ToDoListAPI/util/common/PagedResponse.java`
- [Errors](https://github.com/kgonzagao/todolistapi/blob/main/src/main/java/com/kg/ToDoListAPI/util/exception/GlobalExceptionHandler.java): exception handler · Central HTTP exception-to-response mapping · `src/main/java/com/kg/ToDoListAPI/util/exception/GlobalExceptionHandler.java`

## Connections

- App → Security: wires · Bootstraps application security and web configuration
- Security → JWT filter: registers · Places JWT validation in the request pipeline
- JWT filter → JWT service: uses · Validates and interprets bearer tokens
- JWT service → JWT support: delegates · Shares token parsing and generation helpers
- Auth API → User service: calls · Handles login, registration, and refresh operations
- User service → User repo: reads/writes · Creates users and verifies credentials
- User service → Role repo: reads · Resolves authorization metadata
- User service → JWT service: issues · Creates auth tokens during successful login or refresh
- User service → Current user: uses · Accesses the current authenticated user when needed
- User repo → User: persists · Stores account records
- Role repo → Role: persists · Stores roles
- Role → Permission: contains · Roles aggregate permissions
- Task API → Task service: calls · Exposes task CRUD operations
- Task service → Current user: scopes by · Uses current user identity for ownership and filtering
- Task service → Task repo: reads/writes · Loads and saves task data
- Task repo → Task: persists · Stores task records
- Task API → Paged response: returns · Wraps list responses with paging metadata
- Auth API → Errors: handled by · Validation and domain errors are mapped centrally
- Task API → Errors: handled by · Validation and domain errors are mapped centrally
- User service → Errors: raises · Domain failures such as duplicate users flow to the global handler
- Task service → Errors: raises · Missing resources and access issues flow to the global handler