Diagramma dei container o componenti principali

Questa lezione appartiene al Modulo 15 — Documentazione.

Il lavoro continua il progetto guida, il Registro del laboratorio scolastico. In questa lezione crei un diagramma che mostra i componenti interni del sistema — i quattro livelli con le loro dipendenze — non solo il confine esterno.

Obiettivo della lezione

Disegnare il diagramma dei componenti principali del Registro in formato ASCII o Mermaid, con i quattro livelli visibili, le dipendenze tra loro, e i componenti principali per livello.

Alla fine devi avere: un diagramma inserito nel README che permette di capire l’architettura interna del sistema a prima vista.

Differenza tra diagramma di contesto e diagramma di componenti

Un diagramma di contesto mostra il sistema come una scatola nera e le sue relazioni con l’esterno: l’utente, il browser, localStorage. Non mostra cosa c’è dentro.

Un diagramma di componenti apre la scatola e mostra le parti interne: i quattro livelli, i file principali, le dipendenze tra livelli.

Per il Registro, entrambi sono utili. Il diagramma di contesto serve per spiegare “cos’è il sistema”. Il diagramma di componenti serve per spiegare “come è costruito internamente”.

Il diagramma di contesto del Registro

┌─────────────────────────────────────────────────────┐
│                                                     │
│   [Utente] ──→ [Registro del laboratorio] ──→ [localStorage]  │
│   (tecnico,                                         │
│    studente)                                        │
│                                                     │
└─────────────────────────────────────────────────────┘
Contesto: applicazione browser-only, nessun server

Il diagramma di componenti del Registro

Il diagramma di componenti mostra cosa c’è dentro il Registro:

┌──────────────── Registro del laboratorio ───────────────────┐
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ PRESENTATION (azioni.js)                            │   │
│  │  gestori eventi, UI, messaggi utente                │   │
│  └──────────────────────┬──────────────────────────────┘   │
│                         │ chiama                            │
│  ┌──────────────────────▼──────────────────────────────┐   │
│  │ APPLICATION                                         │   │
│  │  apriPrestito, chiudiPrestito, segnalaGuasto,       │   │
│  │  cercaStrumenti, registraStrumento                  │   │
│  └──────────┬───────────────────────────────┬──────────┘   │
│             │ usa regole                     │ delega a     │
│  ┌──────────▼──────────┐  ┌─────────────────▼──────────┐   │
│  │ DOMAIN              │  │ INFRASTRUCTURE              │   │
│  │  Strumento          │  │  archivioStrumentiLS        │   │
│  │  Prestito           │  │  archivioPrestitiLS         │   │
│  └─────────────────────┘  └────────────────────────────┘   │
│                                      │ legge/scrive         │
│                               ┌──────▼──────┐               │
│                               │ localStorage │               │
│                               └─────────────┘               │
└─────────────────────────────────────────────────────────────┘
                          │
                    composto da
                          │
                      main.js

Nel Registro del laboratorio

Il diagramma di componenti è utile per verificare che le dipendenze rispettino l’architettura. Le regole da visualizzare nel diagramma sono:

• presentation dipende da application (freccia verso il basso)
• application dipende da domain (freccia verso il basso)
• infrastructure dipende da domain (freccia laterale)
• nessuna freccia verso l’alto (il domain non conosce l’application)

Se nel diagramma appare una freccia verso l’alto — o una freccia da domain a infrastructure — c’è un problema architetturale.

Procedura guidata

1. Disegna prima il diagramma di contesto (cosa vede l’utente).
2. Poi disegna il diagramma di componenti (cosa c’è dentro).
3. Per ogni livello, elenca i file principali.
4. Disegna le frecce che rappresentano le dipendenze (import nel codice).
5. Verifica che nessuna freccia vada “verso l’alto” (da domain verso application o presentation).
6. Inserisci il diagramma nel README subito dopo la sezione “Struttura del progetto”.

Attività in classe

Disegna a mano su carta il diagramma di componenti del tuo Registro, poi trasferiscilo nel README in formato ASCII o Mermaid. Confronta il tuo diagramma con quello del compagno e discuti le differenze.

Spiegazione guidata per studiare

Un diagramma di componenti è utile solo se mostra le dipendenze reali, non quelle ideali. Se scrivi il diagramma prima di controllare gli import nel codice, rischi di disegnare un’architettura che non esiste. Prima controlla il codice, poi disegna.

La scelta tra ASCII e Mermaid dipende dall’uso. Il formato ASCII funziona ovunque — anche in un README su GitHub senza rendering speciale. Il formato Mermaid viene renderizzato graficamente da GitHub e da molti tool moderni, ma richiede la sintassi specifica.

Passo per passo nel progetto

1. Versione Mermaid (viene renderizzata graficamente su GitHub):

Nel README, inserisci questa sezione (il blocco mermaid viene renderizzato graficamente da GitHub):

graph TD
  subgraph Presentation
    UI["azioni.js (gestori eventi, messaggi)"]
  end
  subgraph Application
    AP["apriPrestito.js"]
    CP["chiudiPrestito.js"]
    SG["segnalaGuasto.js"]
    CS["cercaStrumenti.js"]
    RS["registraStrumento.js"]
  end
  subgraph Domain
    STR["strumento.js (modello, stati validi)"]
    PRE["prestito.js (apertura, chiusura)"]
  end
  subgraph Infrastructure
    ASL["archivioStrumentiLocalStorage.js"]
    APL["archivioPrestitiLocalStorage.js"]
    LS[("localStorage")]
  end
  UI --> AP
  UI --> CP
  UI --> SG
  UI --> CS
  AP --> STR
  AP --> ASL
  AP --> APL
  CP --> APL
  CP --> ASL
  SG --> ASL
  CS --> ASL
  ASL --> LS
  APL --> LS
  ASL --> STR
  APL --> PRE
  MAIN["main.js (composizione)"] --> UI
  MAIN --> ASL
  MAIN --> APL

1. Versione ASCII (funziona ovunque):

## Architettura interna

PRESENTATION
  azioni.js — gestori click, messaggi utente
      |
      | chiama
      v
APPLICATION
  apriPrestito.js   chiudiPrestito.js   segnalaGuasto.js
  cercaStrumenti.js   registraStrumento.js
      |                         |
      | usa regole              | delega persistenza
      v                         v
  DOMAIN                  INFRASTRUCTURE
  strumento.js            archivioStrumentiLocalStorage.js
  prestito.js             archivioPrestitiLocalStorage.js
                                |
                                | legge/scrive
                                v
                          localStorage

main.js — punto di composizione (importa da tutti i livelli)

1. Scegli il formato che preferisci e inseriscilo nel README nella sezione “Struttura del progetto” o in una sezione “Architettura” dedicata.

Esempio — come verificare che il diagramma rifletta il codice

# controlla gli import in ogni livello — devono corrispondere alle frecce nel diagramma

# cosa importa application/?
grep -r "^import" src/application/ --include="*.js"

# cosa importa domain/?
grep -r "^import" src/domain/ --include="*.js"
# deve essere vuoto — domain non importa nulla

# cosa importa infrastructure/?
grep -r "^import" src/infrastructure/ --include="*.js"
# deve importare solo da domain/

# cosa importa presentation/?
grep -r "^import" src/presentation/ --include="*.js"
# deve importare solo da application/

Prova di comprensione

Rispondi per iscritto:

• Qual è la differenza tra il diagramma di contesto e il diagramma di componenti?
• Se nel tuo diagramma trovi una freccia da presentation/ direttamente a infrastructure/, cosa significa?
• Perché main.js ha frecce verso tutti i livelli ma non è “sopra” di essi?
• Quale formato (ASCII o Mermaid) hai scelto e perché?

Errori da evitare

• disegnare il diagramma senza verificare gli import reali nel codice;
• usare nomi nel diagramma che non corrispondono ai file effettivi;
• dimenticare main.js come punto di composizione;
• non includere localStorage come componente esterno all’architettura interna.

Prodotto da consegnare

Il diagramma di componenti nel README (ASCII o Mermaid). Come verifica: mostralo al docente e indica verbalmente quale blocco corrisponde a quale file, seguendo le frecce delle dipendenze.

Checklist di chiusura

• il diagramma mostra i quattro livelli con i file principali;
• le frecce delle dipendenze corrispondono agli import nel codice;
• main.js è presente come punto di composizione;
• localStorage è mostrato come componente esterno;
• il diagramma è nel README e leggibile senza spiegazioni aggiuntive.

Risultato atteso

Ho disegnato il diagramma di componenti del Registro.
Formato scelto: Mermaid / ASCII — motivo: [descrizione].
Il diagramma è nel README nella sezione "Architettura interna".
Ho verificato che le frecce corrispondono agli import nel codice.
Nessuna freccia va verso l'alto — le dipendenze rispettano l'architettura.