Principio: "A diagram is worth a thousand lines of code."
::: info
La modellazione architettonica serve a comunicare la struttura del sistema a diversi livelli di astrazione. Utilizziamo lo standard UML (Unified Modeling Language) per la semantica e Mermaid.js come motore di rendering "Diagram-as-Code" integrato nel Markdown.
:::
Modellare prima (o durante) lo sviluppo permette di:
- Identificare colli di bottiglia: Visualizzare i flussi di dati aiuta a scoprire inefficienze.
- Separazione delle Responsabilità: Verificare graficamente se una classe/modulo sta facendo troppo (violazione del principio SRP).
- Onboarding rapido: Permette a un nuovo sviluppatore di capire il sistema in 5 minuti invece di leggere migliaia di righe di codice.
Descrive le classi, i loro attributi, metodi e le relazioni (ereditarietà, associazione).
- Uso: Documentare la gerarchia degli oggetti in C++ o i modelli di dati in Python.
classDiagram
class BaseProcessor {
+int id
+process_data(data)
}
class ImageProcessor {
+float resolution
+apply_filter()
}
BaseProcessor <|-- ImageProcessor : Inheritance
Mostra come gli oggetti interagiscono tra loro nel tempo.
- Uso: Documentare chiamate API, protocolli di handshake o flussi di autenticazione.
sequenceDiagram
participant User
participant API as FastAPI Server
participant DB as PostgreSQL
User->>API: GET /user/profile
API->>DB: Query User Data
DB-->>API: User Record
API-->>User: JSON Response
Descrive i diversi stati di un sistema e le transizioni tra di essi.
- Uso: Documentare macchine a stati (FSM) in sistemi embedded C++ o cicli di vita di un ordine in un e-commerce.
In progetti complessi, un singolo diagramma non basta. Adottiamo il C4 Model, che divide la documentazione in 4 livelli di zoom:
- Context (Lvl 1): Il sistema e i suoi utenti/sistemi esterni.
- Container (Lvl 2): Applicazioni, database, microservizi (es. Proxmox VM, Docker Containers).
- Component (Lvl 3): Moduli interni a un singolo container.
- Code (Lvl 4): Diagrammi di classe (spesso generati da Doxygen).
graph TD
REQ[Analisi Requisiti] --> DESIGN[Architectural Design]
DESIGN -->|Mermaid Script| DOC[Markdown Documentation]
DOC -->|Review| DEV[Implementation]
DEV -->|Doxygen/Sphinx| AUTO_DOC[Low-Level Diagrams]
style DESIGN fill:#f9f,stroke:#333,stroke-width:2px
- Meno è Meglio: Non includere ogni singola variabile privata in un Class Diagram. Documenta solo le interfacce pubbliche e le relazioni chiave.
- Naming Consistente: Usa gli stessi nomi che appaiono nel codice sorgente. Se nel diagramma la classe si chiama
UserFactory, deve chiamarsi così anche nel file .py o .cpp.
- Note e Annotazioni: Usa i commenti nel codice Mermaid per spiegare decisioni progettuali non ovvie.
- Sincronizzazione: Quando cambi l'architettura nel codice, aggiorna immediatamente il file
.md. La documentazione asincrona è debito tecnico.
Ultimo aggiornamento: {{UPDATE_DATE}} | Tags: #UML #MermaidJS #C4Model #SoftwareArchitecture #Design