🏗️ Architectural Modeling: UML & Mermaid.js

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. :::

1. Perché modellare l’architettura?

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.

2. Diagrammi Essenziali per il Software Engineer

A. Class Diagram (Struttura Statica)

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

B. Sequence Diagram (Interazione Dinamica)

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

C. State Diagram (Logica di Business)

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.

3. Il Modello C4: La Gerarchia della Documentazione

In progetti complessi, un singolo diagramma non basta. Adottiamo il C4 Model, che divide la documentazione in 4 livelli di zoom:

1. Context (Lvl 1): Il sistema e i suoi utenti/sistemi esterni.
2. Container (Lvl 2): Applicazioni, database, microservizi (es. Proxmox VM, Docker Containers).
3. Component (Lvl 3): Moduli interni a un singolo container.
4. Code (Lvl 4): Diagrammi di classe (spesso generati da Doxygen).

📉 Workflow di Modellazione (Mermaid)

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

🛠️ Best Practices per Diagrammi Professionali

1. Meno è Meglio: Non includere ogni singola variabile privata in un Class Diagram. Documenta solo le interfacce pubbliche e le relazioni chiave.
2. 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.
3. Note e Annotazioni: Usa i commenti nel codice Mermaid per spiegare decisioni progettuali non ovvie.
4. 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