How kgonzagao/todolistapi works
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: UserServiceImpl.java User service · TaskServiceImpl.java Task service · GlobalExceptionHandler.java Errors · TaskController.java Task API
Components 19
Bootstrap
Application entrypoint and runtime wiring
Auth
Identity, security, and JWT flows
- Auth API · Registration, login, and token refresh endpoints
src/main/java/com/kg/ToDoListAPI/auth/presentation/controller/AuthController.java - User service · Creates users, authenticates credentials, and issues auth responses
src/main/java/com/kg/ToDoListAPI/auth/service/impl/UserServiceImpl.java - Current user · Resolves the authenticated principal for downstream logic
src/main/java/com/kg/ToDoListAPI/auth/service/impl/AuthenticatedUserServiceImpl.java - JWT filter · Validates bearer tokens before protected endpoints
src/main/java/com/kg/ToDoListAPI/auth/util/jwt/JwtAuthenticationFilter.java - JWT service · Creates and validates JWTs for login and request authentication
src/main/java/com/kg/ToDoListAPI/auth/util/jwt/JwtService.java - JWT support · Shared JWT helper utilities used by security and auth flows
src/main/java/com/kg/ToDoListAPI/auth/util/jwt/JwtSupport.java - User repo · Persistence access for users and account data
src/main/java/com/kg/ToDoListAPI/auth/persistence/UserRepository.java - Role repo · Persistence access for roles and permissions
src/main/java/com/kg/ToDoListAPI/auth/persistence/RoleRepository.java - User · Account and identity aggregate root
src/main/java/com/kg/ToDoListAPI/auth/persistence/UserEntity.java - Role · Role-based authorization model
src/main/java/com/kg/ToDoListAPI/auth/persistence/RoleEntity.java - Permission · 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 · Task CRUD endpoints scoped to the authenticated user
src/main/java/com/kg/ToDoListAPI/module/task/presentation/TaskController.java - Task service · Enforces task rules and ownership checks
src/main/java/com/kg/ToDoListAPI/module/task/service/impl/TaskServiceImpl.java - Task repo · Persistence access for task records
src/main/java/com/kg/ToDoListAPI/module/task/persistence/TaskRepository.java - Task · Task domain state
src/main/java/com/kg/ToDoListAPI/module/task/persistence/TaskEntity.java
Shared
Cross-cutting utilities and error handling
- Paged response · Shared pagination envelope for list endpoints
src/main/java/com/kg/ToDoListAPI/util/common/PagedResponse.java - Errors · Central HTTP exception-to-response mapping
src/main/java/com/kg/ToDoListAPI/util/exception/GlobalExceptionHandler.java
Connections 21
- 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