How josh-png12/ms-usuarios works
1. What this service is
ms-usuarios is a Spring Boot 3.3.6 microservice for user authentication and CRUD management of three business entities: Usuario, Cliente, and TipoUsuario. It is built as a stateless REST service with JWT-based security and persists data in MySQL 8.
2. Top-level runtime boundaries
The application runs with a main HTTP port on 8080 under the context path /usuarios, and a separate management/Actuator port on 8081. That split matters for architecture because business APIs and operational endpoints are intentionally isolated.
3. Request flow through the application
Incoming requests enter the rest package controllers, which delegate to the service layer. Services enforce business rules and map DTOs to entities, then call Spring Data JPA repositories in dao to read/write the database. Responses are returned as dedicated response DTOs rather than exposing entities directly.
4. Authentication and authorization subsystem
Authentication is handled by AuthController, JwtService, JwtAuthenticationFilter, and UserDetailsServiceImpl. Login produces a JWT, and subsequent requests are authenticated statelessly via the filter. SecurityConfig defines route protection, with role-based access controlling administrative vs read-only operations.
5. Domain model and persistence
The core persistence model lives in modelo: Usuario, Cliente, TipoUsuario, plus a small Echo model for diagnostics. The repositories are standard JPA interfaces for these aggregates. The schema is managed by Flyway, with V1__init_schema.sql as the authoritative database definition.
6. Business service boundaries
UsuarioService, ClienteService, and TipoUsuarioService encapsulate domain rules and validation that sit between HTTP and persistence. This is where uniqueness checks, password handling, and entity lookups are enforced. The service layer is the main business boundary in the system.
7. DTO boundary
The dto/request and dto/response packages separate API contracts from persistence structures. Requests are shaped for input validation, while responses are trimmed representations suitable for client consumption. This boundary prevents controllers from leaking JPA entities and helps the API evolve independently of the schema.
8. Error handling and API consistency
GlobalExceptionHandler and ResourceNotFoundException provide centralized error translation. This keeps the REST layer from returning raw persistence errors in normal cases, although the README notes some uniqueness violations can still surface as unhandled database exceptions if not validated before save.
9. Operational endpoints and observability
HealthController and Actuator provide service health and runtime metrics. Prometheus integration is enabled, and logging can be sent via GELF to Graylog. There is also an EchoController intended for development-only diagnostics, gated by profile.
10. External infrastructure dependencies
The service expects a MySQL database, a JWT secret, and optional Eureka registration. Docker Compose supplies a local development environment, while production-like deployment relies on environment variables for database, JWT, Eureka, and logging configuration. These external systems are part of the service’s runtime architecture, not just tooling.
11. Build, deployment, and tooling
The repository is Maven-based with wrapper scripts, Dockerfile, Jenkins pipeline, and Docker Compose. springdoc-openapi provides Swagger/OpenAPI documentation at runtime, and the repo includes a PlantUML architecture diagram under docs/architecture, indicating the service is designed to be documented as a deployable microservice component.
12. Test and maintenance notes relevant to architecture
Tests exist for the service layer and application context, but the README indicates they currently depend on external configuration such as datasource and JWT environment variables. There is also a duplicate repository package outside the main Spring scan path, which is a maintenance artifact rather than a functional subsystem.
Main entry points: rest REST API · UsuarioService.java Usuario svc · ClienteService.java Cliente svc · security Security
Components 22
Runtime
Request handling, security, and business execution
- Spring app · Main Spring Boot application and package root
src/main/java/dan/ms/tp/msusuarios/MsUsuariosApplication.java - REST API · Primary REST controllers for auth and business resources
src/main/java/dan/ms/tp/msusuarios/rest - Auth · Login and token issuance endpoints
src/main/java/dan/ms/tp/msusuarios/rest/AuthController.java - Usuarios · Usuario CRUD endpoints
src/main/java/dan/ms/tp/msusuarios/rest/UsuarioController.java - Clientes · Cliente CRUD endpoints
src/main/java/dan/ms/tp/msusuarios/rest/ClienteController.java - Tipos · TipoUsuario management endpoints
src/main/java/dan/ms/tp/msusuarios/rest/TipoUsuarioController.java - Security · Stateless authentication, authorization, and user lookup
src/main/java/dan/ms/tp/msusuarios/security - JWT filter · Validates bearer tokens on incoming requests
src/main/java/dan/ms/tp/msusuarios/security/JwtAuthenticationFilter.java - JWT service · Creates and parses JWTs
src/main/java/dan/ms/tp/msusuarios/security/JwtService.java - Usuario svc · Business rules for usuarios and credentials
src/main/java/dan/ms/tp/msusuarios/service/UsuarioService.java - Cliente svc · Business rules for clientes
src/main/java/dan/ms/tp/msusuarios/service/ClienteService.java - Tipo svc · Business rules for tipo usuario lookups
src/main/java/dan/ms/tp/msusuarios/service/TipoUsuarioService.java - DTOs · Request and response models used by the REST boundary
src/main/java/dan/ms/tp/msusuarios/dto
Domain
Core business entities and persistence
- Models · Persistent domain entities
src/main/java/dan/ms/tp/msusuarios/modelo - Repositories · Spring Data repositories for domain persistence
src/main/java/dan/ms/tp/msusuarios/dao - Errors · Centralized REST error translation
src/main/java/dan/ms/tp/msusuarios/exception
Infrastructure
Database migration and external dependencies
- Flyway schema · Authoritative database migration script
src/main/resources/db/migration/V1__init_schema.sql - Config · Security and OpenAPI configuration
src/main/java/dan/ms/tp/msusuarios/config - Runtime config · Application configuration for ports, datasource, JWT, and logging
src/main/resources/application.properties - External deps · MySQL, JWT secret, optional Eureka, Prometheus, and Graylog at runtime
Operations
Health, docs, and deployment support
- Ops endpoints · Health and diagnostic endpoints, including management port exposure
src/main/java/dan/ms/tp/msusuarios/rest/HealthController.java - API docs · Swagger/OpenAPI documentation configuration
src/main/java/dan/ms/tp/msusuarios/config/OpenApiConfig.java
Connections 31
- Spring app → Config: loads · Bootstraps application configuration and security setup
- Spring app → REST API: hosts · Starts the REST layer on the main HTTP port
- Spring app → Ops endpoints: exposes · Separates operational endpoints on the management port
- REST API → Auth: includes · Authentication endpoints
- REST API → Usuarios: includes · Usuario resource endpoints
- REST API → Clientes: includes · Cliente resource endpoints
- REST API → Tipos: includes · TipoUsuario resource endpoints
- Auth → JWT service: issues tokens · Login delegates token creation to JWT service
- Auth → DTOs: uses · Consumes login requests and returns auth responses
- JWT filter → JWT service: verifies · Extracts and validates bearer tokens
- Security → JWT filter: registers · Installs stateless authentication filter
- Security → JWT service: configures · Wires JWT handling into security rules
- Security → External deps: depends on · Uses secret material and protected routes from runtime config
- Usuarios → Usuario svc: delegates · Controller calls business service
- Clientes → Cliente svc: delegates · Controller calls business service
- Tipos → Tipo svc: delegates · Controller calls business service
- Usuario svc → Repositories: reads/writes · Uses repositories for persistence
- Cliente svc → Repositories: reads/writes · Uses repositories for persistence
- Tipo svc → Repositories: reads · Uses repositories for lookups and validation
- Usuario svc → Models: maps · Converts between DTOs and entities
- Cliente svc → Models: maps · Converts between DTOs and entities
- Tipo svc → Models: returns · Works with persistent domain entities
- REST API → DTOs: exchanges · API boundary uses request and response DTOs
- Usuario svc → Errors: throws · Maps missing resources and validation failures
- Cliente svc → Errors: throws · Maps missing resources and validation failures
- Repositories → Models: persists · Spring Data repositories manage JPA entities
- Flyway schema → External deps: creates schema · Initializes the MySQL database schema
- Runtime config → External deps: configures · Points the service at database, JWT, logging, and discovery dependencies
- Config → API docs: enables · Provides API documentation setup
- Config → Security: defines · Encodes route protection and authorization rules
- Ops endpoints → External deps: reports to · Exposes operational status and metrics integration