# josh-png12/ms-usuarios architecture

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

- Interactive diagram: https://gitdiagram.com/josh-png12/ms-usuarios
- Repository: https://github.com/josh-png12/ms-usuarios

## Overview

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: [`src/main/java/dan/ms/tp/msusuarios/rest`](https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/rest) (REST API), [`src/main/java/dan/ms/tp/msusuarios/service/UsuarioService.java`](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/service/UsuarioService.java) (Usuario svc), [`src/main/java/dan/ms/tp/msusuarios/service/ClienteService.java`](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/service/ClienteService.java) (Cliente svc), [`src/main/java/dan/ms/tp/msusuarios/security`](https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/security) (Security)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app["Spring app<br/>boot entrypoint"]
  node_controllers["REST API<br/>http layer"]
  node_authctrl["Auth<br/>controller"]
  node_userctrl["Usuarios<br/>controller"]
  node_clientctrl["Clientes<br/>controller"]
  node_tipoctrl["Tipos<br/>controller"]
  node_sec["Security"]
  node_jwtfilter["JWT filter"]
  node_jwtservice["JWT service<br/>token service<br/>[JwtService.java]"]
  node_usersvc["Usuario svc"]
  node_clientsvc["Cliente svc"]
  node_tiposvc["Tipo svc"]
  node_dto["DTOs<br/>api contract"]
end

subgraph group_domain["Domain"]
  node_domainmodel[("Models<br/>jpa entities")]
  node_repos["Repositories"]
  node_exceptions["Errors<br/>exception handling"]
end

subgraph group_infra["Infrastructure"]
  node_flyway["Flyway schema<br/>db migration"]
  node_config["Config"]
  node_appprops["Runtime config<br/>properties"]
  node_external{{"External deps<br/>runtime dependencies"}}
end

subgraph group_ops["Operations"]
  node_health(("Ops endpoints<br/>actuator/rest"))
  node_openapi["API docs<br/>openapi<br/>[OpenApiConfig.java]"]
end

node_app -->|"loads"| node_config
node_app -->|"hosts"| node_controllers
node_app -->|"exposes"| node_health
node_controllers -->|"includes"| node_authctrl
node_controllers -->|"includes"| node_userctrl
node_controllers -->|"includes"| node_clientctrl
node_controllers -->|"includes"| node_tipoctrl
node_authctrl -->|"issues tokens"| node_jwtservice
node_authctrl -->|"uses"| node_dto
node_jwtfilter -->|"verifies"| node_jwtservice
node_sec -->|"registers"| node_jwtfilter
node_sec -->|"configures"| node_jwtservice
node_sec -.->|"depends on"| node_external
node_userctrl -->|"delegates"| node_usersvc
node_clientctrl -->|"delegates"| node_clientsvc
node_tipoctrl -->|"delegates"| node_tiposvc
node_usersvc -->|"reads/writes"| node_repos
node_clientsvc -->|"reads/writes"| node_repos
node_tiposvc -->|"reads"| node_repos
node_usersvc -->|"maps"| node_domainmodel
node_clientsvc -->|"maps"| node_domainmodel
node_tiposvc -->|"returns"| node_domainmodel
node_controllers -->|"exchanges"| node_dto
node_usersvc -->|"throws"| node_exceptions
node_clientsvc -->|"throws"| node_exceptions
node_repos -->|"persists"| node_domainmodel
node_flyway -->|"creates schema"| node_external
node_appprops -.->|"configures"| node_external
node_config -->|"enables"| node_openapi
node_config -->|"defines"| node_sec
node_health -.->|"reports to"| node_external

click node_app "https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/MsUsuariosApplication.java"
click node_controllers "https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/rest"
click node_authctrl "https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/rest/AuthController.java"
click node_userctrl "https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/rest/UsuarioController.java"
click node_clientctrl "https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/rest/ClienteController.java"
click node_tipoctrl "https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/rest/TipoUsuarioController.java"
click node_sec "https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/security"
click node_jwtfilter "https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/security/JwtAuthenticationFilter.java"
click node_jwtservice "https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/security/JwtService.java"
click node_usersvc "https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/service/UsuarioService.java"
click node_clientsvc "https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/service/ClienteService.java"
click node_tiposvc "https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/service/TipoUsuarioService.java"
click node_dto "https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/dto"
click node_domainmodel "https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/modelo"
click node_repos "https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/dao"
click node_exceptions "https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/exception"
click node_flyway "https://github.com/josh-png12/ms-usuarios/blob/main/src/main/resources/db/migration/V1__init_schema.sql"
click node_config "https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/config"
click node_appprops "https://github.com/josh-png12/ms-usuarios/blob/main/src/main/resources/application.properties"
click node_health "https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/rest/HealthController.java"
click node_openapi "https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/config/OpenApiConfig.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_app,node_controllers,node_authctrl,node_userctrl,node_clientctrl,node_tipoctrl,node_sec,node_jwtfilter,node_jwtservice,node_usersvc,node_clientsvc,node_tiposvc,node_dto toneBlue
class node_domainmodel,node_repos,node_exceptions toneAmber
class node_flyway,node_config,node_appprops,node_external toneMint
class node_health,node_openapi toneRose
```

## Components

### Runtime

Request handling, security, and business execution

- [Spring app](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/MsUsuariosApplication.java): boot entrypoint · Main Spring Boot application and package root · `src/main/java/dan/ms/tp/msusuarios/MsUsuariosApplication.java`
- [REST API](https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/rest): http layer · Primary REST controllers for auth and business resources · `src/main/java/dan/ms/tp/msusuarios/rest`
- [Auth](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/rest/AuthController.java): controller · Login and token issuance endpoints · `src/main/java/dan/ms/tp/msusuarios/rest/AuthController.java`
- [Usuarios](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/rest/UsuarioController.java): controller · Usuario CRUD endpoints · `src/main/java/dan/ms/tp/msusuarios/rest/UsuarioController.java`
- [Clientes](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/rest/ClienteController.java): controller · Cliente CRUD endpoints · `src/main/java/dan/ms/tp/msusuarios/rest/ClienteController.java`
- [Tipos](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/rest/TipoUsuarioController.java): controller · TipoUsuario management endpoints · `src/main/java/dan/ms/tp/msusuarios/rest/TipoUsuarioController.java`
- [Security](https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/security): jwt security · Stateless authentication, authorization, and user lookup · `src/main/java/dan/ms/tp/msusuarios/security`
- [JWT filter](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/security/JwtAuthenticationFilter.java): filter · Validates bearer tokens on incoming requests · `src/main/java/dan/ms/tp/msusuarios/security/JwtAuthenticationFilter.java`
- [JWT service](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/security/JwtService.java): token service · Creates and parses JWTs · `src/main/java/dan/ms/tp/msusuarios/security/JwtService.java`
- [Usuario svc](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/service/UsuarioService.java): service · Business rules for usuarios and credentials · `src/main/java/dan/ms/tp/msusuarios/service/UsuarioService.java`
- [Cliente svc](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/service/ClienteService.java): service · Business rules for clientes · `src/main/java/dan/ms/tp/msusuarios/service/ClienteService.java`
- [Tipo svc](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/service/TipoUsuarioService.java): service · Business rules for tipo usuario lookups · `src/main/java/dan/ms/tp/msusuarios/service/TipoUsuarioService.java`
- [DTOs](https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/dto): api contract · Request and response models used by the REST boundary · `src/main/java/dan/ms/tp/msusuarios/dto`

### Domain

Core business entities and persistence

- [Models](https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/modelo): jpa entities · Persistent domain entities · `src/main/java/dan/ms/tp/msusuarios/modelo`
- [Repositories](https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/dao): jpa repositories · Spring Data repositories for domain persistence · `src/main/java/dan/ms/tp/msusuarios/dao`
- [Errors](https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/exception): exception handling · Centralized REST error translation · `src/main/java/dan/ms/tp/msusuarios/exception`

### Infrastructure

Database migration and external dependencies

- [Flyway schema](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/resources/db/migration/V1__init_schema.sql): db migration · Authoritative database migration script · `src/main/resources/db/migration/V1__init_schema.sql`
- [Config](https://github.com/josh-png12/ms-usuarios/tree/main/src/main/java/dan/ms/tp/msusuarios/config): app config · Security and OpenAPI configuration · `src/main/java/dan/ms/tp/msusuarios/config`
- [Runtime config](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/resources/application.properties): properties · Application configuration for ports, datasource, JWT, and logging · `src/main/resources/application.properties`
- **External deps**: runtime dependencies · MySQL, JWT secret, optional Eureka, Prometheus, and Graylog at runtime

### Operations

Health, docs, and deployment support

- [Ops endpoints](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/rest/HealthController.java): actuator/rest · Health and diagnostic endpoints, including management port exposure · `src/main/java/dan/ms/tp/msusuarios/rest/HealthController.java`
- [API docs](https://github.com/josh-png12/ms-usuarios/blob/main/src/main/java/dan/ms/tp/msusuarios/config/OpenApiConfig.java): openapi · Swagger/OpenAPI documentation configuration · `src/main/java/dan/ms/tp/msusuarios/config/OpenApiConfig.java`

## Connections

- 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
