chatok-jnr/legalaid-user-auth

1. Service role and deployment boundary

This repository is a single Spring Boot 3.2 microservice for the Legal Aid platform’s user authentication and profile domain. It exposes REST endpoints under /api/v1 and runs as a standalone Java 21 application, packaged with Maven and deployable as a JAR or Docker container.

2. Primary request flow

Incoming HTTP requests enter the controller layer, are authenticated/authorized by Spring Security and a JWT filter, then delegated to service classes. Services orchestrate validation, token logic, persistence, and external uploads before returning DTO responses. Error handling is centralized so controllers stay thin.

3. Security and identity subsystem

The core security boundary is JWT-based authentication built on Spring Security 6. Access tokens are HS256-signed JWTs handled by JwtService and enforced by JwtAuthenticationFilter. UserDetailsServiceImpl bridges Spring Security to the user store. SecurityConfig and CorsConfig define the filter chain, role-based access control, and cross-origin policy.

4. Authentication and session lifecycle

AuthController and AuthServiceImpl implement registration, login, refresh, and “me” endpoints. The system uses BCrypt for password hashing, opaque UUID refresh tokens persisted in the database, and refresh-token rotation with reuse detection. RefreshToken is a first-class entity, so session state is not purely stateless JWT.

5. User and role data model

The shared identity model centers on User, Role, and UserRole, with UserAddress and UserAddressId for user-owned addresses. UserRole and RoleRepository support multi-role users such as CLIENT, LAWYER, and ADMIN. The model is relational and JPA-backed rather than document-based.

6. Role-specific profile subsystems

The repository separates profile management by audience: ClientController / ClientService, LawyerController / LawyerService, and AdminController / AdminService. Each role has its own entity package, DTOs, and repositories, which keeps client, lawyer, and admin data isolated while still anchored to the shared User identity.

7. Address management subsystem

AddressController and UserAddressServiceImpl manage authenticated users’ addresses. The presence of UserAddress, UserAddressRepository, and a composite ID indicates addresses are uniquely keyed per user and address type. This is a user-owned subdomain layered on top of the common identity model.

8. Cloudinary integration boundary

Lawyer document uploads are the only explicit external file-storage integration. CloudinaryServiceImpl and CloudinaryConfig wrap Cloudinary credentials and upload settings, and are used for lawyer profile document storage. This is a separate external I/O boundary from the core database-backed profile logic.

9. Persistence layer

All durable state lives in PostgreSQL through Spring Data JPA/Hibernate repositories. The repository package is split by domain: shared identity, refresh tokens, user addresses, and role-specific profile repositories. Projection interfaces in the lawyer repository suggest read-optimized queries for admin or profile views without loading full entity graphs.

10. DTO and API contract layer

Request and response payloads are kept in dedicated DTO packages, grouped by domain and by direction. This indicates the API contract is intentionally decoupled from entity shapes, which is important for protecting internal persistence structure and supporting PATCH-style partial updates.

11. Error handling and response consistency

AuthExceptions and GlobalExceptionHandler define the domain error boundary. The exception handler likely maps business failures into consistent API errors rather than exposing persistence or security internals directly. This is important for diagramming because it sits cross-cutting over all controllers and services.

12. Operational and build context

The project is Maven-based, uses application.yml plus environment variables for runtime configuration, and includes Docker and deployment scripts, which means it is designed to run consistently across local, container, and production environments. The tests cover auth, JWT, cloudinary, controller, and lawyer service paths, showing those are the most critical integration seams.