How walter1705/sac works
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: SolicitudController.java Solicitud API · UsuarioController.java Usuario API · SolicitudService.java Solicitud service · IAController.java IA API
Components 23
Frontend
Next.js presentation shell
- Next.js UI · Thin client that renders views and calls the backend API
frontend/app
Backend
Spring Boot API and domain
- Spring Boot · Starts the backend runtime
backend/src/main/java/com/uniquindio/backend/BackendApplication.java
API layer
REST controllers and public endpoints
- Solicitud API · Endpoints for request lifecycle operations
backend/src/main/java/com/uniquindio/backend/controller/SolicitudController.java - Usuario API · Endpoints for user management and authentication flows
backend/src/main/java/com/uniquindio/backend/controller/UsuarioController.java - IA API · Endpoints that expose AI-assisted operations
backend/src/main/java/com/uniquindio/backend/controller/IAController.java
Domain
Core entities, DTOs, and state models
- Solicitud · Primary request object moving through the workflow
backend/src/main/java/com/uniquindio/backend/model/Solicitud.java - Usuario · System user and role-bearing actor
backend/src/main/java/com/uniquindio/backend/model/Usuario.java - Asignacion · Assignment record linking responsibility to a request
backend/src/main/java/com/uniquindio/backend/model/Asignacion.java - Historial · Tracks state changes and request history
backend/src/main/java/com/uniquindio/backend/model/Historial.java - DTO contracts · Request and response shapes for the public API
backend/src/main/java/com/uniquindio/backend/model/dto
Application
Business services and orchestration
- Solicitud service · Coordinates request lifecycle, assignment, and audit rules
backend/src/main/java/com/uniquindio/backend/service/SolicitudService.java - Usuario service · Handles user accounts, roles, and login-related logic
backend/src/main/java/com/uniquindio/backend/service/UsuarioService.java - IA 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 · Persistence access for request data
backend/src/main/java/com/uniquindio/backend/repository/SolicitudRepository.java - Usuario repo · Persistence access for user data
backend/src/main/java/com/uniquindio/backend/repository/UsuarioRepository.java - Asignacion repo · Persistence access for assignment records
backend/src/main/java/com/uniquindio/backend/repository/AsignacionRepository.java - Historial repo · Persistence access for audit history
backend/src/main/java/com/uniquindio/backend/repository/HistorialRepository.java - Security config · Defines protected routes and authorization policy
backend/src/main/java/com/uniquindio/backend/util/config/SecurityConfig.java - JWT filter · Authenticates incoming requests using JWT tokens
backend/src/main/java/com/uniquindio/backend/util/security/JwtAuthenticationFilter.java - JWT util · Creates and validates JWT tokens
backend/src/main/java/com/uniquindio/backend/util/security/JwtUtil.java - Error handler · Maps exceptions to structured API error responses
backend/src/main/java/com/uniquindio/backend/util/exception/GlobalExceptionHandler.java - Gemini client · Optional LLM client used for AI-assisted suggestions
backend/src/main/java/com/uniquindio/backend/util/serviceAI/GeminiClient.java - Data seeder · Loads sample data for local startup and demos
backend/src/main/java/com/uniquindio/backend/util/config/DataSeeder.java
Connections 34
- 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