# fatec-ams-pi-2026/backend-spring-gini architecture

> Architecture diagram of the GitHub repository fatec-ams-pi-2026/backend-spring-gini, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fatec-ams-pi-2026/backend-spring-gini
- Repository: https://github.com/fatec-ams-pi-2026/backend-spring-gini

## Overview

GINI is a Spring backend for academic timetable planning at Fatec Itu. Coordinators and administrators maintain academic and facility data, define teaching periods and schedules, allocate classes, validate availability and conflicts, and review or copy timetable versions. The main allocation path is exposed through REST controllers and coordinated by domain services/use cases before persistence. README capabilities are represented, but several subsystem links use package-level paths because their implementations were not sampled.

Main entry points: [`src/main/java/com/fatec/gini/infrastructure/repositories`](https://github.com/fatec-ams-pi-2026/backend-spring-gini/tree/dev/src/main/java/com/fatec/gini/infrastructure/repositories) (JPA repositories), [`src/main/java/com/fatec/gini/domain/services/AlocacaoService.java`](https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/AlocacaoService.java) (Allocation service), [`src/main/java/com/fatec/gini/web/controller/AlocacaoController.java`](https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/web/controller/AlocacaoController.java) (Allocation API), [`src/main/java/com/fatec/gini/web/controller/AutenticacaoController.java`](https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/web/controller/AutenticacaoController.java) (Authentication API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["API and access"]
  node_allocation_api["Allocation API"]
  node_timetable_api["Timetable API"]
  node_auth_api["Authentication API"]
  node_security["Security filters"]
  node_auth_services["Token services<br/>[TokenService.java]"]
  node_exception_handler["Error mapping"]
end

subgraph group_catalog["Academic setup"]
  node_catalog_api["Catalog APIs"]
  node_catalog_services["Catalog services"]
  node_availability["Teacher availability"]
end

subgraph group_scheduling["Timetable workflow"]
  node_allocation_service["Allocation service"]
  node_allocation_creation["Create allocation"]
  node_allocation_update["Update allocation"]
  node_allocation_validation["Schedule validation"]
  node_version_service["Timetable versions"]
  node_history_service["Change history"]
end

subgraph group_storage["Domain and persistence"]
  node_domain["Academic entities"]
  node_repositories["JPA repositories"]
  node_database[("Relational database")]
end

node_client(("API client"))

node_client -->|"sends requests"| node_allocation_api
node_client -->|"sends requests"| node_timetable_api
node_client -->|"sends credentials"| node_auth_api
node_allocation_api -->|"calls"| node_allocation_service
node_timetable_api -->|"calls"| node_version_service
node_auth_api -->|"authenticates"| node_security
node_auth_api -->|"issues tokens"| node_auth_services
node_security -->|"checks tokens"| node_auth_services
node_catalog_api -->|"calls"| node_catalog_services
node_catalog_services -->|"reads and writes"| node_repositories
node_availability -->|"reads and writes"| node_repositories
node_allocation_service -->|"creates allocations"| node_allocation_creation
node_allocation_service -->|"updates allocations"| node_allocation_update
node_allocation_service -->|"validates schedules"| node_allocation_validation
node_allocation_service -->|"queries allocations"| node_repositories
node_version_service -->|"loads versions"| node_repositories
node_version_service -->|"validates copies"| node_allocation_validation
node_history_service -->|"stores history"| node_repositories
node_allocation_creation -->|"persists allocations"| node_repositories
node_allocation_update -->|"persists changes"| node_repositories
node_repositories -->|"maps entities"| node_domain
node_repositories -->|"reads and writes"| node_database
node_allocation_api -->|"maps errors"| node_exception_handler

click node_allocation_api "https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/web/controller/AlocacaoController.java"
click node_timetable_api "https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/web/controller/QuadroHorarioController.java"
click node_auth_api "https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/web/controller/AutenticacaoController.java"
click node_security "https://github.com/fatec-ams-pi-2026/backend-spring-gini/tree/dev/src/main/java/com/fatec/gini/web/config"
click node_auth_services "https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/TokenService.java"
click node_catalog_api "https://github.com/fatec-ams-pi-2026/backend-spring-gini/tree/dev/src/main/java/com/fatec/gini/web/controller"
click node_catalog_services "https://github.com/fatec-ams-pi-2026/backend-spring-gini/tree/dev/src/main/java/com/fatec/gini/domain/services"
click node_availability "https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/DisponibilidadeProfessorService.java"
click node_allocation_service "https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/AlocacaoService.java"
click node_allocation_creation "https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/usecase/write/CriarAlocacaoUseCase.java"
click node_allocation_update "https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/usecase/write/AtualizarAlocacaoUseCase.java"
click node_allocation_validation "https://github.com/fatec-ams-pi-2026/backend-spring-gini/tree/dev/src/main/java/com/fatec/gini/domain/services/usecase/read"
click node_version_service "https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/QuadroHorarioService.java"
click node_history_service "https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/HistoricoVersaoAlocacaoService.java"
click node_domain "https://github.com/fatec-ams-pi-2026/backend-spring-gini/tree/dev/src/main/java/com/fatec/gini/domain/entities"
click node_repositories "https://github.com/fatec-ams-pi-2026/backend-spring-gini/tree/dev/src/main/java/com/fatec/gini/infrastructure/repositories"
click node_exception_handler "https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/web/exception/ResourceExceptionHandler.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_allocation_api,node_timetable_api,node_auth_api,node_security,node_auth_services,node_exception_handler,node_client toneBlue
class node_catalog_api,node_catalog_services,node_availability toneAmber
class node_allocation_service,node_allocation_creation,node_allocation_update,node_allocation_validation,node_version_service,node_history_service toneMint
class node_domain,node_repositories,node_database toneRose
```

## Components

### API and access

- [Allocation API](https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/web/controller/AlocacaoController.java): `src/main/java/com/fatec/gini/web/controller/AlocacaoController.java`
- [Timetable API](https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/web/controller/QuadroHorarioController.java): `src/main/java/com/fatec/gini/web/controller/QuadroHorarioController.java`
- [Authentication API](https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/web/controller/AutenticacaoController.java): `src/main/java/com/fatec/gini/web/controller/AutenticacaoController.java`
- [Security filters](https://github.com/fatec-ams-pi-2026/backend-spring-gini/tree/dev/src/main/java/com/fatec/gini/web/config): `src/main/java/com/fatec/gini/web/config`
- [Token services](https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/TokenService.java): `src/main/java/com/fatec/gini/domain/services/TokenService.java`
- [Error mapping](https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/web/exception/ResourceExceptionHandler.java): `src/main/java/com/fatec/gini/web/exception/ResourceExceptionHandler.java`

### Academic setup

- [Catalog APIs](https://github.com/fatec-ams-pi-2026/backend-spring-gini/tree/dev/src/main/java/com/fatec/gini/web/controller): `src/main/java/com/fatec/gini/web/controller`
- [Catalog services](https://github.com/fatec-ams-pi-2026/backend-spring-gini/tree/dev/src/main/java/com/fatec/gini/domain/services): `src/main/java/com/fatec/gini/domain/services`
- [Teacher availability](https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/DisponibilidadeProfessorService.java): `src/main/java/com/fatec/gini/domain/services/DisponibilidadeProfessorService.java`

### Timetable workflow

- [Allocation service](https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/AlocacaoService.java): `src/main/java/com/fatec/gini/domain/services/AlocacaoService.java`
- [Create allocation](https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/usecase/write/CriarAlocacaoUseCase.java): `src/main/java/com/fatec/gini/domain/services/usecase/write/CriarAlocacaoUseCase.java`
- [Update allocation](https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/usecase/write/AtualizarAlocacaoUseCase.java): `src/main/java/com/fatec/gini/domain/services/usecase/write/AtualizarAlocacaoUseCase.java`
- [Schedule validation](https://github.com/fatec-ams-pi-2026/backend-spring-gini/tree/dev/src/main/java/com/fatec/gini/domain/services/usecase/read): `src/main/java/com/fatec/gini/domain/services/usecase/read`
- [Timetable versions](https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/QuadroHorarioService.java): `src/main/java/com/fatec/gini/domain/services/QuadroHorarioService.java`
- [Change history](https://github.com/fatec-ams-pi-2026/backend-spring-gini/blob/dev/src/main/java/com/fatec/gini/domain/services/HistoricoVersaoAlocacaoService.java): `src/main/java/com/fatec/gini/domain/services/HistoricoVersaoAlocacaoService.java`

### Domain and persistence

- [Academic entities](https://github.com/fatec-ams-pi-2026/backend-spring-gini/tree/dev/src/main/java/com/fatec/gini/domain/entities): `src/main/java/com/fatec/gini/domain/entities`
- [JPA repositories](https://github.com/fatec-ams-pi-2026/backend-spring-gini/tree/dev/src/main/java/com/fatec/gini/infrastructure/repositories): `src/main/java/com/fatec/gini/infrastructure/repositories`
- **Relational database**

### Other components

- **API client**

## Connections

- API client → Allocation API: sends requests
- API client → Timetable API: sends requests
- API client → Authentication API: sends credentials
- Allocation API → Allocation service: calls
- Timetable API → Timetable versions: calls
- Authentication API → Security filters: authenticates
- Authentication API → Token services: issues tokens
- Security filters → Token services: checks tokens
- Catalog APIs → Catalog services: calls
- Catalog services → JPA repositories: reads and writes
- Teacher availability → JPA repositories: reads and writes
- Allocation service → Create allocation: creates allocations
- Allocation service → Update allocation: updates allocations
- Allocation service → Schedule validation: validates schedules
- Allocation service → JPA repositories: queries allocations
- Timetable versions → JPA repositories: loads versions
- Timetable versions → Schedule validation: validates copies
- Change history → JPA repositories: stores history
- Create allocation → JPA repositories: persists allocations
- Update allocation → JPA repositories: persists changes
- JPA repositories → Academic entities: maps entities
- JPA repositories → Relational database: reads and writes
- Allocation API → Error mapping: maps errors