# typeitorg/boero-api architecture

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

- Interactive diagram: https://gitdiagram.com/typeitorg/boero-api
- Repository: https://github.com/typeitorg/boero-api

## Overview

#### 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`.

Main entry points: [`src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/controllers/AuthController.java`](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/controllers/AuthController.java) (Auth controller), [`src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/controllers/PlatformInstitutionController.java`](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/controllers/PlatformInstitutionController.java) (Platform institution controller), [`src/main/java/ar/edu/utn/frvm/typeit/boero_api/security/config/SecurityConfig.java`](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/security/config/SecurityConfig.java) (Security boundary), [`src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/services/AuthorizationService.java`](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/services/AuthorizationService.java) (Authorization service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP & Security"]
  node_auth_controller["Auth controller<br/>REST controller"]
  node_institution_controller["Platform institution controller<br/>REST controller"]
  node_request_logging["Request logging<br/>servlet filter"]
  node_security_config["Security boundary<br/>Spring Security config"]
  node_public_routes["Public route policy<br/>[PublicRoutes.java]"]
  node_jwt_filter["JWT authentication<br/>security filter"]
  node_exception_handler["HTTP error mapping<br/>exception handler"]
end

subgraph group_identity["Identity &amp; Authorization"]
  node_login["Login use case<br/>auth use case<br/>[LoginUseCase.java]"]
  node_refresh["Refresh token use case<br/>auth use case"]
  node_session_revocation["Session revocation<br/>auth service"]
  node_jwt_service["JWT service<br/>token service<br/>[JwtService.java]"]
  node_authorization["Authorization service"]
  node_permission_aspect["Permission enforcement<br/>AOP aspect"]
  node_institution_access["Institution access enforcement<br/>AOP aspect"]
  node_role_model["Roles and permissions<br/>authorization model<br/>[Role.java]"]
end

subgraph group_institutional["Institutional Domain"]
  node_institution_usecase["Institution provisioning<br/>institutional use case"]
  node_institution_model["Institution model<br/>domain entity<br/>[Institution.java]"]
  node_person_model["People model<br/>domain entity<br/>[Person.java]"]
  node_institution_repo["Institution repository<br/>JPA repository port"]
end

subgraph group_data["Persistence &amp; Cache"]
  node_postgres[("PostgreSQL<br/>durable database")]
  node_flyway["Flyway migrations<br/>schema migrations"]
  node_redis[("Redis<br/>cache and token state")]
  node_cache_config["Cache policy<br/>cache config<br/>[CacheConfig.java]"]
end

node_app{{"Spring Boot application<br/>runtime"}}

node_app -->|"starts HTTP pipeline"| node_request_logging
node_request_logging -->|"logs requests before security"| node_security_config
node_security_config -->|"applies public-route rules"| node_public_routes
node_security_config -->|"installs authentication filter"| node_jwt_filter
node_jwt_filter -->|"validates JWT"| node_jwt_service
node_security_config -->|"routes authenticated/public requests"| node_auth_controller
node_security_config -->|"routes protected requests"| node_institution_controller
node_auth_controller -->|"login"| node_login
node_auth_controller -->|"refresh"| node_refresh
node_auth_controller -->|"logout"| node_session_revocation
node_login -->|"issues access token"| node_jwt_service
node_refresh -->|"issues rotated access token"| node_jwt_service
node_login -->|"records token/session state"| node_redis
node_refresh -->|"checks rotation state"| node_redis
node_session_revocation -->|"invalidates token state"| node_redis
node_institution_controller -.->|"protected by permission annotations"| node_permission_aspect
node_institution_controller -.->|"protected by institution scope"| node_institution_access
node_permission_aspect -->|"resolves effective authority"| node_authorization
node_institution_access -->|"checks tenant assignment"| node_authorization
node_authorization -->|"uses roles and permissions"| node_role_model
node_authorization -->|"uses authorization snapshots"| node_redis
node_institution_controller -->|"invokes provisioning"| node_institution_usecase
node_institution_usecase -->|"creates and changes"| node_institution_model
node_institution_usecase -->|"persists through"| node_institution_repo
node_institution_repo -->|"JPA persistence"| node_postgres
node_flyway -->|"manages schema"| node_postgres
node_cache_config -->|"configures caching"| node_redis
node_auth_controller -.->|"maps failures"| node_exception_handler
node_institution_controller -.->|"maps failures"| node_exception_handler

click node_app "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/BoeroApiApplication.java"
click node_auth_controller "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/controllers/AuthController.java"
click node_institution_controller "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/controllers/PlatformInstitutionController.java"
click node_request_logging "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/common/logging/RequestLoggingFilter.java"
click node_security_config "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/security/config/SecurityConfig.java"
click node_public_routes "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/security/config/PublicRoutes.java"
click node_jwt_filter "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/filters/JwtAuthenticationFilter.java"
click node_exception_handler "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/common/exceptions/GlobalExceptionHandler.java"
click node_login "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/LoginUseCase.java"
click node_refresh "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/RefreshTokenUseCase.java"
click node_session_revocation "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/SessionRevocationService.java"
click node_jwt_service "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/JwtService.java"
click node_authorization "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/services/AuthorizationService.java"
click node_permission_aspect "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/security/PermissionAuthorizationAspect.java"
click node_institution_access "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/security/InstitutionAccessAspect.java"
click node_role_model "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/entities/Role.java"
click node_institution_usecase "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/services/CreateInstitutionUseCase.java"
click node_institution_model "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/entities/Institution.java"
click node_person_model "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/entities/Person.java"
click node_institution_repo "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/interfaces/InstitutionRepository.java"
click node_cache_config "https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/config/CacheConfig.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_auth_controller,node_institution_controller,node_request_logging,node_security_config,node_public_routes,node_jwt_filter,node_exception_handler toneBlue
class node_login,node_refresh,node_session_revocation,node_jwt_service,node_authorization,node_permission_aspect,node_institution_access,node_role_model toneAmber
class node_institution_usecase,node_institution_model,node_person_model,node_institution_repo toneMint
class node_postgres,node_flyway,node_redis,node_cache_config toneRose
class node_app toneNeutral
```

## Components

### HTTP & Security

- [Auth controller](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/controllers/AuthController.java): REST controller · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/controllers/AuthController.java`
- [Platform institution controller](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/controllers/PlatformInstitutionController.java): REST controller · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/controllers/PlatformInstitutionController.java`
- [Request logging](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/common/logging/RequestLoggingFilter.java): servlet filter · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/common/logging/RequestLoggingFilter.java`
- [Security boundary](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/security/config/SecurityConfig.java): Spring Security config · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/security/config/SecurityConfig.java`
- [Public route policy](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/security/config/PublicRoutes.java): route policy · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/security/config/PublicRoutes.java`
- [JWT authentication](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/filters/JwtAuthenticationFilter.java): security filter · Builds the request principal from JWT credentials. · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/filters/JwtAuthenticationFilter.java`
- [HTTP error mapping](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/common/exceptions/GlobalExceptionHandler.java): exception handler · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/common/exceptions/GlobalExceptionHandler.java`

### Identity & Authorization

- [Login use case](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/LoginUseCase.java): auth use case · Issues access and refresh credentials for distinct identity types. · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/LoginUseCase.java`
- [Refresh token use case](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/RefreshTokenUseCase.java): auth use case · Rotates refresh tokens and detects replay. · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/RefreshTokenUseCase.java`
- [Session revocation](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/SessionRevocationService.java): auth service · Revokes sessions and associated token state on logout. · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/SessionRevocationService.java`
- [JWT service](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/JwtService.java): token service · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/auth/services/JwtService.java`
- [Authorization service](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/services/AuthorizationService.java): authorization service · Resolves roles, permissions, assignments, and platform roles. · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/services/AuthorizationService.java`
- [Permission enforcement](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/security/PermissionAuthorizationAspect.java): AOP aspect · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/security/PermissionAuthorizationAspect.java`
- [Institution access enforcement](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/security/InstitutionAccessAspect.java): AOP aspect · Enforces tenant context for protected operations. · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/security/InstitutionAccessAspect.java`
- [Roles and permissions](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/entities/Role.java): authorization model · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/authorization/entities/Role.java`

### Institutional Domain

- [Institution provisioning](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/services/CreateInstitutionUseCase.java): institutional use case · Creates institutions and manages status transitions. · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/services/CreateInstitutionUseCase.java`
- [Institution model](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/entities/Institution.java): domain entity · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/entities/Institution.java`
- [People model](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/entities/Person.java): domain entity · Supports people, students, guardians, and institutional identities. · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/entities/Person.java`
- [Institution repository](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/interfaces/InstitutionRepository.java): JPA repository port · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/institutional/interfaces/InstitutionRepository.java`

### Persistence & Cache

- **PostgreSQL**: durable database
- **Flyway migrations**: schema migrations
- **Redis**: cache and token state · Stores authorization snapshots and token-related state.
- [Cache policy](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/config/CacheConfig.java): cache config · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/config/CacheConfig.java`

### Other components

- [Spring Boot application](https://github.com/typeitorg/boero-api/blob/develop/src/main/java/ar/edu/utn/frvm/typeit/boero_api/BoeroApiApplication.java): runtime · Java 21 REST service bootstrap. · `src/main/java/ar/edu/utn/frvm/typeit/boero_api/BoeroApiApplication.java`

## Connections

- Spring Boot application → Request logging: starts HTTP pipeline
- Request logging → Security boundary: logs requests before security
- Security boundary → Public route policy: applies public-route rules
- Security boundary → JWT authentication: installs authentication filter
- JWT authentication → JWT service: validates JWT
- Security boundary → Auth controller: routes authenticated/public requests
- Security boundary → Platform institution controller: routes protected requests
- Auth controller → Login use case: login
- Auth controller → Refresh token use case: refresh
- Auth controller → Session revocation: logout
- Login use case → JWT service: issues access token
- Refresh token use case → JWT service: issues rotated access token
- Login use case → Redis: records token/session state
- Refresh token use case → Redis: checks rotation state
- Session revocation → Redis: invalidates token state
- Platform institution controller → Permission enforcement: protected by permission annotations
- Platform institution controller → Institution access enforcement: protected by institution scope
- Permission enforcement → Authorization service: resolves effective authority
- Institution access enforcement → Authorization service: checks tenant assignment
- Authorization service → Roles and permissions: uses roles and permissions
- Authorization service → Redis: uses authorization snapshots
- Platform institution controller → Institution provisioning: invokes provisioning
- Institution provisioning → Institution model: creates and changes
- Institution provisioning → Institution repository: persists through
- Institution repository → PostgreSQL: JPA persistence
- Flyway migrations → PostgreSQL: manages schema
- Cache policy → Redis: configures caching
- Auth controller → HTTP error mapping: maps failures
- Platform institution controller → HTTP error mapping: maps failures