Diagramma di contesto semplificato

Questa lezione appartiene al Modulo 15 — Struttura del progetto, documentazione e diagrammi.

Cos’è un diagramma di contesto

Un diagramma di contesto mostra il sistema dall’esterno: chi lo usa, da dove arrivano i dati, dove finiscono. Non mostra come il sistema funziona internamente — solo i confini e le relazioni con l’esterno.

È il diagramma più semplice e più utile per far capire un progetto a chi non lo conosce.

Il contesto del Registro del laboratorio

Il Registro ha:

• Utenti che interagiscono con esso (docente, tecnico, studente)
• Dati persistenti che vengono salvati (strumenti, prestiti)
• Un confine che separa ciò che l’utente vede da ciò che il sistema fa internamente

Diagramma testuale del contesto:

                    ┌─────────────────────────────────┐
                    │   REGISTRO DEL LABORATORIO       │
                    │                                  │
  [Docente]  ──────►│  Registra strumenti              │
  [Tecnico]  ──────►│  Segnala guasti                  │
  [Studente] ──────►│  Richiede prestiti               │
                    │                                  │
                    │  ──────────────────────────────  │
                    │                                  │
                    │         [localStorage]           │
                    │         [file JSON]              │
                    │         [API / database]         │
                    └─────────────────────────────────┘

Il diagramma di contesto non mostra:

• i quattro livelli interni (Domain, Application, Infrastructure, Presentation)
• le funzioni dei casi d’uso
• come vengono gestiti gli errori

Mostra solo: chi interagisce con il sistema e dove finiscono i dati.

Differenza tra diagramma di contesto e diagramma dei componenti

Diagramma	Mostra	Utile per
Contesto	Confini esterni, utenti, sistemi adiacenti	Far capire il progetto a chi arriva nuovo
Componenti	Moduli interni, dipendenze, livelli	Ragionare sull’architettura durante lo sviluppo

Questa lezione riguarda il diagramma di contesto — il più esterno.

Come disegnarlo per il Registro

Non serve uno strumento grafico. Un diagramma ASCII in un file .md o in un README è sufficiente.

Versione minima (solo attori e sistema):

[Docente / Tecnico / Studente]
          │
          ▼
  ┌──────────────────┐
  │   Registro del   │
  │   laboratorio    │
  └──────────────────┘
          │
          ▼
  [localStorage / JSON]

Versione con le azioni principali:

  [Docente]
    │ registra strumento
    │ vede lista strumenti
    ▼
  ┌─────────────────────────────┐
  │   REGISTRO DEL LABORATORIO  │
  │                             │
  │   Strumenti                 │
  │   Prestiti                  │
  │   Segnalazioni guasto       │
  └─────────────────────────────┘
    │ salva e legge
    ▼
  [localStorage]

Cosa includere e cosa omettere

Includi:

• gli attori che usano il sistema (chi fa cosa)
• il nome del sistema
• i sistemi esterni con cui si scambia dati (localStorage, API, database)

Ometti:

• i dettagli interni (funzioni, classi, file specifici)
• le regole di dominio
• i messaggi di errore
• i livelli architetturali

Un diagramma di contesto che mostra troppo smette di essere utile come panoramica.

Strumenti suggeriti

• ASCII/testo nel README: semplice, sempre aggiornabile, funziona ovunque
• draw.io (gratuito): utile per presentazioni
• Mermaid (syntax nel markdown): si integra con GitHub e molti editor

Esempio Mermaid:

graph TD
  Docente -->|registra, cerca| Registro
  Tecnico -->|segnala guasto| Registro
  Studente -->|richiede prestito| Registro
  Registro -->|salva e legge| localStorage

Procedura guidata

1. Elenca gli attori: chi usa il Registro? (docente, tecnico, studente)
2. Elenca le azioni principali di ogni attore (registra strumento, apre prestito, segnala guasto).
3. Elenca i sistemi esterni (localStorage, JSON, API futura).
4. Disegna il sistema come un rettangolo al centro.
5. Collega attori e sistemi esterni con frecce etichettate.
6. Rimuovi tutto ciò che riguarda l’interno del sistema.

Attività in classe

Disegna il diagramma di contesto del tuo Registro. Usa testo o ASCII — non serve grafica.

Poi rispondi:

## Diagramma di contesto — verifica

Chi sono gli attori del mio Registro:

Quali azioni fa ogni attore:

Quali sistemi esterni usa il Registro:

Cosa ho omesso deliberatamente dal diagramma:

Spiegazione guidata per studiare

Il diagramma di contesto è il punto di partenza per documentare un progetto. Non mostra come funziona il sistema internamente — mostra chi lo usa e con cosa comunica.

Per il Registro del laboratorio, gli attori sono docente, tecnico e studente. Il sistema esterno principale è localStorage (o l’API nella variante avanzata). Il sistema stesso è una scatola: il diagramma non entra nei dettagli.

Il punto centrale è questo: un buon diagramma di contesto fa capire il progetto in 30 secondi. Se il tuo diagramma richiede spiegazioni, contiene troppi dettagli.

Il rischio tipico è disegnare un diagramma dei componenti credendo sia un diagramma di contesto. La differenza: il diagramma di componenti mostra i quattro livelli interni (Domain, Application, Infrastructure, Presentation); il diagramma di contesto non entra dentro il sistema.

Passo per passo nel progetto

1. Apri il README del tuo progetto.
2. Aggiungi una sezione “Contesto” o “Chi usa il Registro”.
3. Disegna il diagramma testuale con attori, sistema e dati persistenti.
4. Chiedi a un compagno di leggerlo senza spiegazioni: capisce subito chi fa cosa?
5. Se non capisce, rimuovi dettagli invece di aggiungerne.

Esempio da leggere lentamente

## Contesto del sistema

Il Registro del laboratorio scolastico è usato da tre tipi di utenti:

- il docente o il tecnico: registra strumenti, segnala guasti
- lo studente (tramite il docente): apre e chiude prestiti

I dati vengono salvati nel browser tramite localStorage.
Non ci sono account, autenticazione o server nella versione base.

[Docente/Tecnico] → [Registro] → [localStorage]
[Studente]        ↗

Questo basta per orientarsi. È il diagramma di contesto nella sua forma più semplice.

Prova di comprensione

• Qual è la differenza tra diagramma di contesto e diagramma dei componenti?
• Il tuo diagramma mostra dettagli interni? Se sì, quali puoi rimuovere?
• Un compagno che non ha mai visto il progetto riesce a capire chi lo usa e dove finiscono i dati?

Errori da evitare

• mostrare i quattro livelli interni nel diagramma di contesto (è un errore di livello);
• disegnare funzioni, file o classi specifiche;
• non includere i sistemi esterni (localStorage, API);
• creare un diagramma così dettagliato da richiedere una leggenda.

Prodotto da consegnare

Può essere:

• un diagramma ASCII aggiunto al README del progetto;
• un diagramma Mermaid in un file .md;
• uno schizzo su carta fotografato, se il formato è accettato.

Deve essere leggibile senza spiegazioni aggiuntive.

Checklist di chiusura

• Il diagramma mostra gli attori (docente, tecnico, studente)
• Il diagramma mostra il sistema come una scatola
• Il diagramma mostra i sistemi esterni (localStorage, API)
• Il diagramma non mostra i livelli interni o le funzioni
• Un compagno capisce il diagramma senza spiegazioni

Domande per la revisione

• Quali attori hai incluso? Ne manca qualcuno?
• Il diagramma ti ha aiutato a capire i confini del sistema?
• Cosa aggiungeresti se il progetto crescesse (es. autenticazione, API pubblica)?

Risultato atteso

Alla fine lo studente deve poter mostrare:

Questo è il diagramma di contesto del mio Registro.
Gli attori sono: [lista].
I sistemi esterni sono: [lista].
Il diagramma non mostra i dettagli interni perché [motivo].

Se questa spiegazione non è possibile, la lezione non è ancora davvero conclusa.