typeitorg/boero-api

Purpose and runtime

Boero is a secure, multi-institution backend for academic and administrative management. It is a Java 21 / Spring Boot 4 REST service, started by src/main/java/ar/edu/utn/frvm/typeit/boero_api/BoeroApiApplication.java. HTTP controllers are the application entry points; there is no frontend in this repository.

Domain boundaries

Three bounded areas organize the system:

• Institutional management: institutions, people, students/guardians, addresses, and geographic reference data. Core model: src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/entities/Institution.java, src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/entities/Person.java.

• Authentication: separate institutional-user and platform-account identities, sessions, JWTs, refresh tokens, login/logout, and account administration. src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/controllers/AuthController.java, src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/JwtService.java.

• Authorization: roles, permissions, institution-scoped person assignments, and platform roles. src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/entities/Role.java, src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/services/AuthorizationService.java.

Request and security flow

Requests enter controllers, cross request logging and Spring Security, then invoke use-case services and JPA repositories. src/main/java/ar/edu/utn/frvm/typeit/boero_api/security/config/SecurityConfig.java establishes the security boundary; src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/filters/JwtAuthenticationFilter.java parses JWT credentials into a principal. Public-route policy is centralized in src/main/java/ar/edu/utn/frvm/typeit/boero_api/security/config/PublicRoutes.java.

Authenticated operations are guarded declaratively by permission, platform-role, and institution-access annotations. AOP aspects resolve effective authority and enforce tenant context before protected service/controller execution: src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/security/PermissionAuthorizationAspect.java, src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/security/InstitutionAccessAspect.java.

Identity and session lifecycle

Institutional and platform authentication use distinct user-details services and token/session entities. Login creates access and refresh credentials; refresh-token rotation/replay protection and session revocation limit token reuse; logout revokes sessions/tokens. Key stages are src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/LoginUseCase.java, src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/RefreshTokenUseCase.java, and src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/SessionRevocationService.java.

Tenant-aware institutional operations

Platform controllers administer institutions and cross-platform people; institutional controllers operate within the caller’s institution. Use cases contain business transitions such as institution provisioning/status changes and person CRUD, while repository interfaces isolate persistence. src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/controllers/PlatformInstitutionController.java, src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/services/CreateInstitutionUseCase.java, src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/interfaces/InstitutionRepository.java.

Persistence, cache, and infrastructure

PostgreSQL is the durable store, schema-managed with Flyway migrations in src/main/resources/db/migration/. JPA auditing and UUIDv7 identity support are configured under src/main/java/ar/edu/utn/frvm/typeit/boero_api/config/JpaAuditingConfig.java. Redis supports caching, including authorization snapshots and token-related state; cache policy is rooted in src/main/java/ar/edu/utn/frvm/typeit/boero_api/config/CacheConfig.java.

Docker Compose supplies local service infrastructure via compose.yaml; the image build entry is Dockerfile. Environment-specific Spring configuration lives in src/main/resources/application-dev.properties, src/main/resources/application-staging.properties, and src/main/resources/application-prod.properties.

Cross-cutting API behavior

Controllers exchange request/response payloads rather than entities. Validation occurs at the API boundary; application/domain exceptions are converted to consistent HTTP error payloads by src/main/java/ar/edu/utn/frvm/typeit/boero_api/common/exceptions/GlobalExceptionHandler.java. Request logging is implemented by src/main/java/ar/edu/utn/frvm/typeit/boero_api/common/logging/RequestLoggingFilter.java.