# walter1705/sac architecture

> Architecture diagram of the GitHub repository walter1705/sac, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/walter1705/sac
- Repository: https://github.com/walter1705/sac

## Overview

1. **Repository shape**
   - This is a two-part system: a Spring Boot backend in `backend/` and a Next.js frontend in `frontend/`.
   - The backend contains the full business domain, persistence, security, and AI integration. The frontend is currently a lightweight UI shell, likely acting as the client for the REST API.

2. **Primary runtime flow**
   - User actions start in the frontend.
   - The frontend calls the backend REST controllers over HTTP.
   - Controllers delegate to services, which apply business rules and use repositories to persist/retrieve data from PostgreSQL.
   - Responses return as DTOs, not raw entities, which keeps the API boundary explicit.

3. **Backend layering**
   - `controller/` exposes REST endpoints for users, requests, and AI-related operations.
   - `service/` holds the business logic and orchestration.
   - `repository/` contains Spring Data JPA interfaces for database access.
   - `model/` contains the domain entities and enums.
   - `model/dto/` separates API request/response shapes from persistence models.
   - `util/` groups configuration, security, exceptions, and AI client code.

4. **Domain model**
   - Core entities are `Usuario`, `Solicitud`, `Asignacion`, and `Historial`.
   - Enums define controlled vocabulary for request lifecycle and classification, including `EstadoSolicitud`, `Prioridad`, `TipoSolicitud`, `CanalOrigen`, and `RolUsuario`.
   - This suggests the architecture centers on request triage, assignment, state transitions, and audit history.

5. **Request lifecycle and business constraints**
   - The main functional object is a `Solicitud` that moves through a lifecycle from creation to classification, assignment, progress, resolution, and closure.
   - The existence of separate request DTOs such as `ClasificarSolicitudRequest`, `CambiarEstadoRequest`, `AsignarResponsableRequest`, and `CerrarSolicitudRequest` indicates that each transition is modeled as a distinct operation.
   - `Historial` implies changes are tracked as audit events rather than overwriting important state blindly.

6. **Security boundary**
   - Authentication is JWT-based, implemented with `JwtUtil`, `JwtAuthenticationFilter`, and `JwtAuthenticationEntryPoint`.
   - `SecurityConfig` is the central policy boundary for protected routes and role-based access.
   - The repository’s architecture assumes authorization is enforced at the API layer before business operations proceed.

7. **AI as an optional external dependency**
   - The backend contains `util/serviceAI/GeminiClient`, which indicates an external LLM integration.
   - AI is intentionally isolated from the core flow and treated as optional, with dedicated response types like `IaNoDisponibleResponse` and `SugerirClasificacionResponse`.
   - In architecture terms, AI is a sidecar capability: it can enrich classification or summarization, but the request-management system must still function without it.

8. **Persistence and data access**
   - Spring Data JPA/Hibernate are the persistence mechanism.
   - The repositories map directly to the domain entities, likely with PostgreSQL as the recommended backing store from the README.
   - `compose.yaml` in the backend suggests local containerized infrastructure support, probably including the database for development or demo deployment.

9. **API contract and serialization**
   - DTOs in `model/dto/request` and `model/dto/response` define the public API contract.
   - `JacksonConfig` suggests custom JSON serialization/deserialization behavior, likely to keep enums, dates, or naming consistent across the API.
   - `static/openapi.yaml` and the included Postman collection show that the API is documented and intended to be consumed externally or by the frontend.

10. **Error handling and resilience**
   - The backend defines typed exceptions such as `BadRequestException`, `ForbiddenException`, `UnauthorizedException`, `ResourceNotFoundException`, and `IAServiceUnavailableException`.
   - `GlobalExceptionHandler` centralizes mapping of domain/security failures to structured error responses.
   - This keeps failure handling consistent across controllers and makes the API easier to integrate with.

11. **Startup and bootstrap**
   - `BackendApplication.java` is the Spring Boot entry point.
   - `DataSeeder` indicates the backend can preload sample users or domain data on startup, which is useful for development, demos, or testing.
   - The test suite mirrors the major boundaries: controllers, services, and JWT utilities.

12. **Frontend role in the system**
   - The frontend uses Next.js with the App Router structure (`app/layout.tsx`, `app/page.tsx`) and TypeScript.
   - In the current tree it appears minimal, so the main architecture emphasis is still the backend API rather than a complex client-side domain.
   - For an architecture diagram, the frontend should be represented as a thin presentation layer that authenticates, renders role-specific views, and calls the backend REST API.

13. **Key architectural boundaries to draw**
   - Presentation boundary: Next.js UI
   - API boundary: Spring MVC controllers
   - Business boundary: service layer
   - Persistence boundary: JPA repositories + PostgreSQL
   - Security boundary: JWT filter/configuration
   - External integration boundary: Gemini/LLM service
   - Cross-cutting boundary: exception handling, JSON config, data seeding, and OpenAPI/Postman support

14. **Operational intent**
   - The system is designed to be deployable with backend, frontend, and database as separate services, likely via Docker Compose.
   - The architecture prioritizes traceability, controlled state changes, and role enforcement over UI complexity.
   - The most important data flow is “request submitted → classified → assigned → progressed → resolved/closed → audited.”

Main entry points: [`backend/src/main/java/com/uniquindio/backend/controller/SolicitudController.java`](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/controller/SolicitudController.java) (Solicitud API), [`backend/src/main/java/com/uniquindio/backend/controller/UsuarioController.java`](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/controller/UsuarioController.java) (Usuario API), [`backend/src/main/java/com/uniquindio/backend/service/SolicitudService.java`](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/service/SolicitudService.java) (Solicitud service), [`backend/src/main/java/com/uniquindio/backend/controller/IAController.java`](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/controller/IAController.java) (IA API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Next.js UI<br/>presentation shell"]
end

subgraph group_backend["Backend"]
  node_backend_main(("Spring Boot<br/>application entrypoint"))
end

subgraph group_backend_api["API layer"]
  node_solicitud_controller["Solicitud API<br/>REST controller"]
  node_usuario_controller["Usuario API<br/>REST controller"]
  node_ia_controller["IA API<br/>REST controller<br/>[IAController.java]"]
end

subgraph group_backend_domain["Domain"]
  node_solicitud_model[("Solicitud<br/>domain entity<br/>[Solicitud.java]")]
  node_usuario_model[("Usuario<br/>domain entity<br/>[Usuario.java]")]
  node_asignacion_model[("Asignacion<br/>domain entity<br/>[Asignacion.java]")]
  node_historial_model["Historial<br/>audit entity<br/>[Historial.java]"]
  node_dto_contracts["DTO contracts<br/>api models"]
end

subgraph group_backend_app["Application"]
  node_solicitud_service["Solicitud service<br/>business service"]
  node_usuario_service["Usuario service<br/>business service"]
  node_ia_service["IA service<br/>integration service<br/>[IAService.java]"]
end

subgraph group_backend_infra["Infrastructure"]
  node_solicitud_repo["Solicitud repo<br/>JPA repository"]
  node_usuario_repo["Usuario repo<br/>JPA repository"]
  node_asignacion_repo["Asignacion repo<br/>JPA repository"]
  node_historial_repo["Historial repo<br/>JPA repository"]
  node_security_config["Security config<br/>security boundary"]
  node_jwt_filter["JWT filter<br/>auth filter"]
  node_jwt_util["JWT util<br/>token utility<br/>[JwtUtil.java]"]
  node_exception_handler["Error handler<br/>cross-cutting handler"]
  node_gemini_client["Gemini client<br/>external integration<br/>[GeminiClient.java]"]
  node_data_seeder["Data seeder<br/>bootstrap config<br/>[DataSeeder.java]"]
end

node_frontend_app -->|"REST calls"| node_solicitud_controller
node_frontend_app -->|"REST calls"| node_usuario_controller
node_frontend_app -->|"REST calls"| node_ia_controller
node_backend_main -->|"hosts"| node_solicitud_controller
node_backend_main -->|"hosts"| node_usuario_controller
node_backend_main -->|"hosts"| node_ia_controller
node_solicitud_controller -->|"delegates"| node_solicitud_service
node_usuario_controller -->|"delegates"| node_usuario_service
node_ia_controller -->|"delegates"| node_ia_service
node_solicitud_service -->|"persists via"| node_solicitud_repo
node_solicitud_service -->|"persists via"| node_asignacion_repo
node_solicitud_service -->|"persists via"| node_historial_repo
node_usuario_service -->|"persists via"| node_usuario_repo
node_ia_service -->|"uses"| node_gemini_client
node_solicitud_service -.->|"returns"| node_dto_contracts
node_usuario_service -.->|"returns"| node_dto_contracts
node_solicitud_controller -.->|"accepts/returns"| node_dto_contracts
node_usuario_controller -.->|"accepts/returns"| node_dto_contracts
node_security_config -->|"registers"| node_jwt_filter
node_jwt_filter -->|"validates tokens"| node_jwt_util
node_security_config -.->|"protects"| node_solicitud_controller
node_security_config -.->|"protects"| node_usuario_controller
node_exception_handler -.->|"handles errors from"| node_solicitud_controller
node_exception_handler -.->|"handles errors from"| node_usuario_controller
node_exception_handler -.->|"handles errors from"| node_ia_controller
node_data_seeder -->|"seeds"| node_usuario_repo
node_data_seeder -->|"seeds"| node_solicitud_repo
node_data_seeder -->|"seeds"| node_historial_repo
node_solicitud_model -->|"stored by"| node_solicitud_repo
node_usuario_model -->|"stored by"| node_usuario_repo
node_asignacion_model -->|"stored by"| node_asignacion_repo
node_historial_model -->|"stored by"| node_historial_repo
node_solicitud_model -.->|"tracked by"| node_historial_model
node_solicitud_model -.->|"assigned via"| node_asignacion_model

click node_frontend_app "https://github.com/walter1705/sac/tree/main/frontend/app"
click node_backend_main "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/BackendApplication.java"
click node_solicitud_controller "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/controller/SolicitudController.java"
click node_usuario_controller "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/controller/UsuarioController.java"
click node_ia_controller "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/controller/IAController.java"
click node_solicitud_service "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/service/SolicitudService.java"
click node_usuario_service "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/service/UsuarioService.java"
click node_ia_service "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/service/IAService.java"
click node_solicitud_model "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/model/Solicitud.java"
click node_usuario_model "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/model/Usuario.java"
click node_asignacion_model "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/model/Asignacion.java"
click node_historial_model "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/model/Historial.java"
click node_dto_contracts "https://github.com/walter1705/sac/tree/main/backend/src/main/java/com/uniquindio/backend/model/dto"
click node_solicitud_repo "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/repository/SolicitudRepository.java"
click node_usuario_repo "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/repository/UsuarioRepository.java"
click node_asignacion_repo "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/repository/AsignacionRepository.java"
click node_historial_repo "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/repository/HistorialRepository.java"
click node_security_config "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/util/config/SecurityConfig.java"
click node_jwt_filter "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/util/security/JwtAuthenticationFilter.java"
click node_jwt_util "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/util/security/JwtUtil.java"
click node_exception_handler "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/util/exception/GlobalExceptionHandler.java"
click node_gemini_client "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/util/serviceAI/GeminiClient.java"
click node_data_seeder "https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/util/config/DataSeeder.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_frontend_app toneBlue
class node_backend_main toneAmber
class node_solicitud_controller,node_usuario_controller,node_ia_controller toneMint
class node_solicitud_model,node_usuario_model,node_asignacion_model,node_historial_model,node_dto_contracts toneRose
class node_solicitud_service,node_usuario_service,node_ia_service toneIndigo
class node_solicitud_repo,node_usuario_repo,node_asignacion_repo,node_historial_repo,node_security_config,node_jwt_filter,node_jwt_util,node_exception_handler,node_gemini_client,node_data_seeder toneTeal
```

## Components

### Frontend

Next.js presentation shell

- [Next.js UI](https://github.com/walter1705/sac/tree/main/frontend/app): presentation shell · Thin client that renders views and calls the backend API · `frontend/app`

### Backend

Spring Boot API and domain

- [Spring Boot](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/BackendApplication.java): application entrypoint · Starts the backend runtime · `backend/src/main/java/com/uniquindio/backend/BackendApplication.java`

### API layer

REST controllers and public endpoints

- [Solicitud API](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/controller/SolicitudController.java): REST controller · Endpoints for request lifecycle operations · `backend/src/main/java/com/uniquindio/backend/controller/SolicitudController.java`
- [Usuario API](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/controller/UsuarioController.java): REST controller · Endpoints for user management and authentication flows · `backend/src/main/java/com/uniquindio/backend/controller/UsuarioController.java`
- [IA API](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/controller/IAController.java): REST controller · Endpoints that expose AI-assisted operations · `backend/src/main/java/com/uniquindio/backend/controller/IAController.java`

### Domain

Core entities, DTOs, and state models

- [Solicitud](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/model/Solicitud.java): domain entity · Primary request object moving through the workflow · `backend/src/main/java/com/uniquindio/backend/model/Solicitud.java`
- [Usuario](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/model/Usuario.java): domain entity · System user and role-bearing actor · `backend/src/main/java/com/uniquindio/backend/model/Usuario.java`
- [Asignacion](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/model/Asignacion.java): domain entity · Assignment record linking responsibility to a request · `backend/src/main/java/com/uniquindio/backend/model/Asignacion.java`
- [Historial](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/model/Historial.java): audit entity · Tracks state changes and request history · `backend/src/main/java/com/uniquindio/backend/model/Historial.java`
- [DTO contracts](https://github.com/walter1705/sac/tree/main/backend/src/main/java/com/uniquindio/backend/model/dto): api models · Request and response shapes for the public API · `backend/src/main/java/com/uniquindio/backend/model/dto`

### Application

Business services and orchestration

- [Solicitud service](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/service/SolicitudService.java): business service · Coordinates request lifecycle, assignment, and audit rules · `backend/src/main/java/com/uniquindio/backend/service/SolicitudService.java`
- [Usuario service](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/service/UsuarioService.java): business service · Handles user accounts, roles, and login-related logic · `backend/src/main/java/com/uniquindio/backend/service/UsuarioService.java`
- [IA service](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/service/IAService.java): integration service · Wraps optional AI-assisted classification behavior · `backend/src/main/java/com/uniquindio/backend/service/IAService.java`

### Infrastructure

Security, persistence, config, and external integrations

- [Solicitud repo](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/repository/SolicitudRepository.java): JPA repository · Persistence access for request data · `backend/src/main/java/com/uniquindio/backend/repository/SolicitudRepository.java`
- [Usuario repo](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/repository/UsuarioRepository.java): JPA repository · Persistence access for user data · `backend/src/main/java/com/uniquindio/backend/repository/UsuarioRepository.java`
- [Asignacion repo](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/repository/AsignacionRepository.java): JPA repository · Persistence access for assignment records · `backend/src/main/java/com/uniquindio/backend/repository/AsignacionRepository.java`
- [Historial repo](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/repository/HistorialRepository.java): JPA repository · Persistence access for audit history · `backend/src/main/java/com/uniquindio/backend/repository/HistorialRepository.java`
- [Security config](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/util/config/SecurityConfig.java): security boundary · Defines protected routes and authorization policy · `backend/src/main/java/com/uniquindio/backend/util/config/SecurityConfig.java`
- [JWT filter](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/util/security/JwtAuthenticationFilter.java): auth filter · Authenticates incoming requests using JWT tokens · `backend/src/main/java/com/uniquindio/backend/util/security/JwtAuthenticationFilter.java`
- [JWT util](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/util/security/JwtUtil.java): token utility · Creates and validates JWT tokens · `backend/src/main/java/com/uniquindio/backend/util/security/JwtUtil.java`
- [Error handler](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/util/exception/GlobalExceptionHandler.java): cross-cutting handler · Maps exceptions to structured API error responses · `backend/src/main/java/com/uniquindio/backend/util/exception/GlobalExceptionHandler.java`
- [Gemini client](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/util/serviceAI/GeminiClient.java): external integration · Optional LLM client used for AI-assisted suggestions · `backend/src/main/java/com/uniquindio/backend/util/serviceAI/GeminiClient.java`
- [Data seeder](https://github.com/walter1705/sac/blob/main/backend/src/main/java/com/uniquindio/backend/util/config/DataSeeder.java): bootstrap config · Loads sample data for local startup and demos · `backend/src/main/java/com/uniquindio/backend/util/config/DataSeeder.java`

## Connections

- Next.js UI → Solicitud API: REST calls · Frontend invokes request management endpoints
- Next.js UI → Usuario API: REST calls · Frontend invokes login and user endpoints
- Next.js UI → IA API: REST calls · Frontend can request AI-assisted operations
- Spring Boot → Solicitud API: hosts · Spring Boot exposes controllers
- Spring Boot → Usuario API: hosts · Spring Boot exposes controllers
- Spring Boot → IA API: hosts · Spring Boot exposes controllers
- Solicitud API → Solicitud service: delegates · Controller forwards request workflow operations
- Usuario API → Usuario service: delegates · Controller forwards user operations
- IA API → IA service: delegates · Controller forwards AI operations
- Solicitud service → Solicitud repo: persists via · Business logic stores and loads requests
- Solicitud service → Asignacion repo: persists via · Stores assignment records
- Solicitud service → Historial repo: persists via · Stores audit history
- Usuario service → Usuario repo: persists via · Business logic stores and loads users
- IA service → Gemini client: uses · AI service delegates to external LLM client
- Solicitud service → DTO contracts: returns · Service shapes API responses through DTOs
- Usuario service → DTO contracts: returns · Service shapes API responses through DTOs
- Solicitud API → DTO contracts: accepts/returns · Public contract defined by request and response DTOs
- Usuario API → DTO contracts: accepts/returns · Public contract defined by request and response DTOs
- Security config → JWT filter: registers · Security policy installs the authentication filter
- JWT filter → JWT util: validates tokens · Filter relies on JWT helper logic
- Security config → Solicitud API: protects · Routes are secured by API policy
- Security config → Usuario API: protects · Routes are secured by API policy
- Error handler → Solicitud API: handles errors from · Maps controller failures to structured responses
- Error handler → Usuario API: handles errors from · Maps controller failures to structured responses
- Error handler → IA API: handles errors from · Maps controller failures to structured responses
- Data seeder → Usuario repo: seeds · Bootstrap data is written through repositories
- Data seeder → Solicitud repo: seeds · Bootstrap data is written through repositories
- Data seeder → Historial repo: seeds · Bootstrap data is written through repositories
- Solicitud → Solicitud repo: stored by · Request entity is persisted in the database
- Usuario → Usuario repo: stored by · User entity is persisted in the database
- Asignacion → Asignacion repo: stored by · Assignment entity is persisted in the database
- Historial → Historial repo: stored by · Audit entity is persisted in the database
- Solicitud → Historial: tracked by · Workflow changes are audited over time
- Solicitud → Asignacion: assigned via · Requests can be linked to responsibility assignments
