# albelizgh/sorteador-i2t architecture

> Architecture diagram of the GitHub repository albelizgh/sorteador-i2t, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/albelizgh/sorteador-i2t
- Repository: https://github.com/albelizgh/sorteador-i2t

## Overview

Para guiar al ingeniero principal en la creación de un diagrama de arquitectura fiel al proyecto “Sistema de Gestión de Reemplazos – Backend”, sigue estos pasos detallados:

##### Identificación del tipo de proyecto y propósito
- Es un servicio RESTful monolítico desarrollado con Spring Boot.
- Su misión es exponer una API para gestionar sorteos, asignaciones y reemplazos de empleados, con seguridad JWT, persistencia en MySQL y documentación automática OpenAPI.

##### Análisis de la estructura de carpetas
- src/main/java/com/pentabyte/projects/sorteador: código de la aplicación.
- config: configuración de seguridad (JwtService, filtros), SpringDoc.
- controller: controladores divididos en subpaquetes auth, crud, auxiliar, coordinador.
- service: lógica de negocio por entidad (AsignacionService, CategoriaService, etc.).
- repository: interfaces JPA para acceso a datos.
- model: entidades JPA.
- dto & mapper: objetos de transferencia y conversores entidad↔DTO.
- exception: manejo global de errores.
- src/main/resources/db/migration: scripts Flyway para versionado de la base.
- pom.xml: dependencias clave (Spring Boot, Spring Data JPA, Security, Flyway, Lombok).

##### Componentes principales a mostrar
- Clientes:
- Frontend web o clientes HTTP (Postman, CURL).
- Coordinadores, auxiliares, autoridades.
- Capa de acceso:
- Spring Security (JwtAuthenticationFilter, SecurityConfiguration).
- Punto de entrada HTTP (DispatcherServlet).
- API REST:
- Controladores (AuthController, CrudController, AsignacionAuxiliarController, etc.).
- Capa de servicio:
- Servicios de negocio (AsignacionService, SorteoService, SolicitudDeReemplazoService, …).
- Capa de persistencia:
- Repositories JPA conectados a MySQL.
- Flyway ejecutando las migraciones (V1__…, V2__…).
- Utilidades transversales:
- Mappers (MapStruct o manual) para DTO↔Entidad.
- Exception Handler global.
- Documentación:
- SpringDoc OpenAPI expuesto en /api/v1/documentacion.
- Base de datos MySQL (o PostgreSQL).

##### Relaciones e interacciones
- Las flechas van: Cliente → Gateway HTTP → Filtro JWT → Controlador → Servicio → Repositorio → Base de datos → Repositorio → Servicio → Controlador → Cliente.
- En paralelo, al inicio la configuración de seguridad intercepta y valida token.
- Flyway se invoca al arranque para preparar el esquema.
- SpringDoc se monta en un hilo separado pero expone un endpoint de la misma app.

##### Patrones y principios arquitectónicos
- Arquitectura en capas (Controller → Service → Repository).
- DTO + Mapper para aislar la capa de persistencia de la capa de presentación.
- Filtro de seguridad en el pipeline de Spring Security.
- Manejo centralizado de excepciones (GlobalExceptionHandler).
- Versionado de DB con Flyway.
- Configuración externa a través de application.properties y variables de entorno.

##### Cómo reflejarlo en el diagrama
a. Componentes:
- Rectángulos grandes para “API Server (Spring Boot)”, “MySQL DB”.
- Dentro del servidor, subdividir en cajas: Security & Auth, Controllers, Services, Repositories, Flyway, OpenAPI.
b. Interacciones:
- Flechas con dirección y etiquetas (“HTTP Request”, “JWT validation”, “JPA query”).
c. Tecnologías:
- Anotar junto a cada componente: Spring Security, Spring Data JPA, Flyway, SpringDoc.
d. Detalles específicos:
- Muestra ejemplos de controladores (AuthController vs. AsignacionCoordinadorController).
- Incluye flujo de una solicitud de reemplazo desde el cliente hasta la persistencia y notificación.

##### Recomendaciones de formato
- Azul claro: capa de presentación / HTTP
- Verde: lógica de negocio
- Naranja: persistencia
- Gris: infra (Flyway, SpringDoc)
- Usa formas distintas:
- Rectángulos con esquinas redondeadas para componentes Spring
- Bases de datos cilíndricas para MySQL
- Líneas continuas para llamadas síncronas
- Etiqueta cada flecha con el tipo de mensaje o protocolo (REST, JWT Token).
- Añade una leyenda para colores y formas.

Con esta guía, el ingeniero podrá dibujar un diagrama de arquitectura detallado y adaptado al proyecto, abordando todas las piezas críticas y su interacción.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["Clients (Web/Postman/CURL)"]:::external

    %% API Server
    subgraph "API Server (Spring Boot)" 
        direction TB
        EntryPoint["SorteadorApplication"]:::infra

        subgraph "Security & Auth" 
            direction TB
            SecurityConfig["SecurityConfiguration"]:::infra
            JwtFilter["JwtAuthenticationFilter"]:::infra
            JwtService["JwtService"]:::infra
            BeansInjector["SecurityBeansInjector"]:::infra
            SecurityContext["SecurityContextService"]:::infra
            UserDetail["UserDetail"]:::infra
            CredDTO["CredencialesDTO"]:::infra
            AuthRespDTO["AuthenticationResponseDTO"]:::infra
        end

        subgraph "Controllers (HTTP Layer)" 
            direction TB
            AuthController["AuthController"]:::presentation
            CRUDControllers["Crud Controllers"]:::presentation
            AuxControllers["Auxiliar Controllers"]:::presentation
            CoordControllers["Coordinador Controllers"]:::presentation
        end

        subgraph "Services (Business Logic)" 
            direction TB
            AsignacionSvc["AsignacionService"]:::business
            CategoriaSvc["CategoriaService"]:::business
            CategoriaTopeSvc["CategoriaTopeService"]:::business
            GrupoSvc["GrupoService"]:::business
            IntegranteSvc["IntegranteService"]:::business
            ProductoSvc["ProductoService"]:::business
            SolicitudReempSvc["SolicitudDeReemplazoService"]:::business
            SorteoSvc["SorteoService"]:::business
        end

        subgraph "Repositories (JPA)" 
            direction TB
            Repos["JPA Repositories"]:::persistence
        end

        subgraph "DTOs & Mappers" 
            direction TB
            DTOs["DTO Packages"]:::business
            Mappers["Mapper Components"]:::business
        end

        subgraph "Exception Handling" 
            direction TB
            ExceptionHandler["GlobalExceptionHandler"]:::business
            Exceptions["Custom Exceptions"]:::business
        end

        subgraph "Infra Tools" 
            direction TB
            Flyway["Flyway Migrations"]:::infra
            OpenAPI["SpringDoc OpenAPI"]:::infra
            AppProps["application.properties"]:::infra
        end
    end

    %% Database
    DB["MySQL Database"]:::database

    %% Interactions
    Client -->|"HTTP Request (REST)"| EntryPoint
    EntryPoint -->|"init Security Beans"| BeansInjector
    EntryPoint -->|"run Flyway"| Flyway
    EntryPoint -->|"start SpringDoc"| OpenAPI
    EntryPoint --> SecurityConfig
    SecurityConfig --> JwtFilter
    JwtFilter --> AuthController
    AuthController --> AsignacionSvc
    CRUDControllers --> CategoriaSvc
    AuxControllers --> SolicitudReempSvc
    CoordControllers --> SorteoSvc
    AsignacionSvc --> Repos
    CategoriaSvc --> Repos
    CategoriaTopeSvc --> Repos
    GrupoSvc --> Repos
    IntegranteSvc --> Repos
    ProductoSvc --> Repos
    SolicitudReempSvc --> Repos
    SorteoSvc --> Repos
    Repos -->|"JPA Query"| DB
    DB -->|"Result"| Repos
    Repos -->|"Data"| AsignacionSvc
    ExceptionHandler --> AuthController
    DTOs --> AuthController
    DTOs --> CRUDControllers
    Mappers --> DTOs

    %% Click Events
    click EntryPoint "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/SorteadorApplication.java"
    click SecurityConfig "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/config/security/SecurityConfiguration.java"
    click JwtFilter "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/config/security/JwtAuthenticationFilter.java"
    click JwtService "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/config/security/JwtService.java"
    click BeansInjector "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/config/security/SecurityBeansInjector.java"
    click SecurityContext "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/config/security/SecurityContextService.java"
    click UserDetail "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/config/security/UserDetail.java"
    click CredDTO "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/config/security/CredencialesDTO.java"
    click AuthRespDTO "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/config/security/AuthenticationResponseDTO.java"
    click OpenAPI "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/config/SpringDocConfiguration.java"
    click AuthController "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/controller/auth/AuthController.java"
    click CRUDControllers "https://github.com/albelizgh/sorteador-i2t/tree/main/src/main/java/com/pentabyte/projects/sorteador/controller/crud/"
    click AuxControllers "https://github.com/albelizgh/sorteador-i2t/tree/main/src/main/java/com/pentabyte/projects/sorteador/controller/auxiliar/"
    click CoordControllers "https://github.com/albelizgh/sorteador-i2t/tree/main/src/main/java/com/pentabyte/projects/sorteador/controller/coordinador/"
    click AsignacionSvc "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/service/AsignacionService.java"
    click CategoriaSvc "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/service/CategoriaService.java"
    click CategoriaTopeSvc "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/service/CategoriaTopeService.java"
    click GrupoSvc "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/service/GrupoService.java"
    click IntegranteSvc "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/service/IntegranteService.java"
    click ProductoSvc "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/service/ProductoService.java"
    click SolicitudReempSvc "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/service/SolicitudDeReemplazoService.java"
    click SorteoSvc "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/service/SorteoService.java"
    click Repos "https://github.com/albelizgh/sorteador-i2t/tree/main/src/main/java/com/pentabyte/projects/sorteador/repository/"
    click DTOs "https://github.com/albelizgh/sorteador-i2t/tree/main/src/main/java/com/pentabyte/projects/sorteador/dto/"
    click Mappers "https://github.com/albelizgh/sorteador-i2t/tree/main/src/main/java/com/pentabyte/projects/sorteador/mapper/"
    click ExceptionHandler "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/java/com/pentabyte/projects/sorteador/exception/GlobalExceptionHandler.java"
    click Exceptions "https://github.com/albelizgh/sorteador-i2t/tree/main/src/main/java/com/pentabyte/projects/sorteador/exception/"
    click Flyway "https://github.com/albelizgh/sorteador-i2t/tree/main/src/main/resources/db/migration/"
    click AppProps "https://github.com/albelizgh/sorteador-i2t/blob/main/src/main/resources/application.properties"

    %% Styles
    classDef external fill:#e0f7fa,stroke:#006064,color:#006064
    classDef presentation fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef business fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20
    classDef persistence fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef infra fill:#eeeeee,stroke:#424242,color:#424242
    classDef database fill:#fff3e0,stroke:#bf360c,color:#bf360c
```
