How albelizgh/sorteador-i2t works
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.