> For the complete documentation index, see [llms.txt](https://sponta.gitbook.io/orario/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sponta.gitbook.io/orario/comprendere-orario/architettura.md).

# Mappa dell'architettura

Orario è un'applicazione web con un server Node.js/Express, un'interfaccia JavaScript nel browser e persistenza SQLite. Il server compone moduli per accessi, dati scolastici, vincoli, orario, workbook e diagnosi AI. La ricerca dell'orario viene eseguita anche in un worker dedicato; le fasi di risoluzione esatta usano un processo Python con OR-Tools.

## La mappa di esecuzione

```mermaid
flowchart TD
    UI[Browser: area di lavoro] --> HTTP[Server Express e route]
    HTTP --> S[Servizi di dominio]
    HTTP --> M[Gestore delle generazioni]
    S --> DB[(SQLite)]
    HTTP --> DB
    M --> W[Worker di generazione]
    W --> SOL[Pipeline e solver]
    W -->|lettura| DB
    SOL --> PY[Processo Python e OR-Tools]
    W -->|progressi e risultati| M
    M -->|applicazione verificata| HTTP
    PUB[Browser: consultazione] --> PS[Route pubbliche e servizio di consultazione]
    PS -->|snapshot approvato| DB
```

Le frecce descrivono le principali interazioni. Il diagramma non implica servizi distribuiti: i moduli Express fanno parte della stessa applicazione.

## Dove cercare nel repository

| Area                                          | Responsabilità e punto di ingresso                                                               |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `server.js` e `src/server.js`                 | Avvio, configurazione, apertura database, middleware e registrazione delle route                 |
| `public/js/app.js`, `api.js`, `views/`        | Navigazione dell'area di lavoro, richieste HTTP e viste per argomento                            |
| `src/routes/`                                 | Endpoint, autorizzazioni e coordinamento delle operazioni applicative                            |
| `src/services/`                               | Calcoli e controlli riutilizzabili: calendari, curricoli, compatibilità, approvazione e snapshot |
| `src/timetable/generationOperationManager.js` | Ciclo di vita della ricerca, progressi, decisioni sui risultati e protezione della bozza         |
| `src/timetable/solver/`                       | Dati di ricerca, task, stato dell'orario, regole, costruzione e miglioramento                    |
| `src/db/`                                     | Connessione SQLite, schema di base e migrazioni                                                  |
| `src/workbook/`                               | Formato Excel, esportazione, importazione e guida del workbook                                   |
| `src/ai/`                                     | Configurazione e operazioni della diagnosi AI                                                    |
| `scripts/solver/`                             | Risolutore Python e strumenti di benchmark                                                       |

Questa separazione è utile per orientarsi, ma non costituisce una barriera assoluta: alcune route contengono ancora SQL e transazioni applicative. Per esempio, `src/routes/timetable.js` coordina la scrittura della bozza, le versioni e la pubblicazione. Non tutta la logica è già estratta nei servizi.

## Il confine tra ricerca e scrittura

Il gestore prepara una copia temporanea del database. Il worker apre questa copia in sola lettura e restituisce progressi, checkpoint e risultati al gestore. Lo stato esplorato dal solver non diventa automaticamente la bozza persistente a ogni tentativo.

Il gestore controlla le impronte dei dati e della bozza prima di applicare un risultato. Un'impronta è un riepilogo calcolato del contenuto: se cambia, la ricerca potrebbe riferirsi a una situazione ormai superata. Questo controllo evita che il risultato sovrascriva interventi avvenuti nel frattempo.

L'applicazione alla bozza passa attraverso una funzione fornita dalle route, con backup e transazione. Il worker computa; il livello applicativo decide quando e come conservare il risultato. Per i dettagli dei casi di arresto, vedi [Come nasce un orario](/orario/comprendere-orario/flusso-orario.md).

## Dentro il motore

`DataRepository` carica i dati e costruisce lo stato; `TaskGenerator` trasforma il curricolo in attività da collocare. `TimetableState` rappresenta lezioni e occupazioni durante la ricerca. `RulesEngine` applica il catalogo delle regole e le istanze configurate.

`GenerationPipeline` coordina costruzione e miglioramento. La `QualityPipeline` seleziona i percorsi di ottimizzazione, mentre profili e policy di qualità misurano e confrontano le soluzioni. Nella policy generale verificata, il confronto usa prima la penalità flessibile pesata e poi il numero di casi residui. Le metriche descrittive possono essere più numerose dei criteri effettivamente usati per scegliere un candidato.

Nel repository convivono percorsi adattivi, GRASP e risolutori esatti: la presenza di una classe non significa che sia eseguita in ogni generazione. Il percorso effettivo dipende dalle opzioni e dalla pipeline richiesta.

## Persistenza e pubblicazione

Il database usa `node:sqlite`. Per ricostruire il modello completo occorre leggere sia `schema.sql` sia le migrazioni in `database.js` e gli eventuali servizi che assicurano le proprie tabelle. Il solo schema iniziale non descrive tutte le evoluzioni.

La bozza si basa sulle lezioni di lavoro; le versioni conservano fotografie. La pubblicazione attiva associa una versione a un contesto congelato, inclusi i dati necessari alla consultazione. `publicScheduleService` legge quella fotografia: le modifiche successive alle anagrafiche o alla bozza non devono alterare retroattivamente l'orario approvato.

## Come orientare una modifica

Per cambiare una regola scolastica, individua prima il servizio o la regola che ne definisce il significato, poi controlla gli utilizzatori: generazione, editing, verifica, approvazione ed eventualmente workbook. Una modifica limitata alla vista potrebbe cambiare il messaggio senza cambiare il comportamento del server.

Per cambiare la navigazione del browser, parti dalle viste e da `app.js`. Per una regressione nella ricerca, parti dalle opzioni della richiesta e dal gestore prima di scegliere quale solver approfondire.

## Riscontri nel repository

* [Server](https://github.com/lsponta/orario/blob/3bf5b58/src/server.js), [frontend](https://github.com/lsponta/orario/blob/3bf5b58/public/js/app.js), [database](https://github.com/lsponta/orario/blob/3bf5b58/src/db/database.js).
* [Gestore](https://github.com/lsponta/orario/blob/3bf5b58/src/timetable/generationOperationManager.js), [worker](https://github.com/lsponta/orario/blob/3bf5b58/src/timetable/generationWorker.js), [pipeline](https://github.com/lsponta/orario/blob/3bf5b58/src/timetable/solver/GenerationPipeline.js).
* [Policy generale di qualità](https://github.com/lsponta/orario/blob/3bf5b58/src/timetable/solver/GeneralQualityScorePolicy.js), [processo esatto](https://github.com/lsponta/orario/blob/3bf5b58/src/timetable/solver/ExactQualitySearch.js), [modello Python](https://github.com/lsponta/orario/blob/3bf5b58/scripts/solver/exact_quality.py).

Continua con [Come nasce un orario](/orario/comprendere-orario/flusso-orario.md).