Mappa degli artefatti architetturali

Tipo

Pratica

Un artifact architetturale dovrebbe esistere perché riduce un'incertezza concreta. La scelta parte quindi dalla domanda da rendere esplicita, non dal nome del template. Capire il problema: problem statement, context map, scope e constraints rispondono alla domanda su cosa stiamo cercando di risolvere e quali confini non dobbiamo confondere; l'anti-pattern è partire dalla soluzione prima che problema e confini siano condivisi. Creare un modello mentale condiviso: system context, container o component view e interaction overview mostrano quali parti esistono, quali responsabilità hanno e come si relazionano; l'anti-pattern è un diagramma pieno di dettagli che non rende più chiaro il sistema. Confrontare alternative: options analysis, trade-off table e decision matrix rendono esplicite opzioni e compromessi; l'anti-pattern è presentare una sola soluzione come se non esistessero alternative. Registrare una decisione: ADR o decision record spiegano cosa è stato deciso, nel quale contesto e perché; l'anti-pattern è registrare solo l'esito senza contesto, alternative e conseguenze. Descrivere contratti e boundary: API contract, event contract, data schema e responsibility boundary chiariscono cosa una parte del sistema può assumere riguardo a un'altra; l'anti-pattern è affidare contratti critici solo a prosa o diagrammi ambigui quando possono essere espressi in forma verificabile. Rendere visibili qualità e rischi trasversali: NFR view, security view, resilience view, threat model e capacity assumptions rendono esplicite proprietà che non emergono dalla struttura dei componenti; l'anti-pattern è trattare sicurezza, resilienza e operabilità come note marginali aggiunte alla fine. Pianificare la transizione: transition architecture, migration plan e sequence of states descrivono come passare in modo controllato dallo stato attuale a quello desiderato; l'anti-pattern è documentare solo il target state ignorando il percorso necessario per raggiungerlo. Rendere il sistema operabile: deployment o runtime view, dependency map, runbook e failure scenarios mostrano dove gira il sistema, da cosa dipende e cosa succede quando qualcosa fallisce; l'anti-pattern è considerare l'architettura conclusa quando il software compila o viene deployato. Per scegliere il formato, il testo strutturato è adatto a decisioni, assunzioni, vincoli e rationale; i diagrammi a relazioni, boundary e flussi; tabelle e matrici ai confronti e all'ownership; formati machine-readable ai contratti verificabili; repository e versionamento agli artifact che devono evolvere insieme al software; workspace collaborativi all'esplorazione e ai workshop. Il formato e il luogo in cui vive l'artifact sono due decisioni diverse: un diagramma può nascere su una whiteboard, diventare un modello versionato quando stabilizza ed essere incorporato nella documentazione consumata dal team. La domanda finale non è quale documento manca, ma qual è la minima evidenza necessaria perché questa decisione possa essere capita, implementata, verificata e mantenuta da qualcun altro.