- ADR

// Titolo e descrizione della MOC
dv.header(2, "Architectural Decision Log");
dv.paragraph("Questo documento funge da indice e sommario per tutte le decisioni architetturali significative prese nel progetto FIRE. Le decisioni più recenti sono in cima.");
 
// 1. Cerca in TUTTO il vault i file che si identificano come 'adr' tramite YAML.
const pages = dv.pages("").where(p => p.doc_type === "adr");
 
if (pages.length === 0) {
    dv.paragraph("⚠️ **Nessun Architectural Decision Record (ADR) trovato.** Assicurati che i file contengano `doc_type: adr` nel loro frontmatter YAML.");
} else {
    // 2. Filtra solo gli ADR che sono stati Accettati
    const acceptedADRs = pages.where(p => p.status === "Accettato");
 
    // 3. Ordina per data, dal più recente al più vecchio
    const sortedADRs = acceptedADRs.sort(p => p.date, 'desc');
    
    // --- 4. LOGICA DI VISUALIZZAZIONE LINEARE ---
    
    for (let page of sortedADRs) {
        // Usa h3 per il titolo per una migliore gerarchia
        dv.paragraph(`### ADR ${page.id}: ${page.file.link}`);
        
        // Aggiungi la data, che è un'informazione cruciale per gli ADR
        if (page.date) {
            dv.paragraph(`**Data:** ${page.date.toFormat("yyyy-MM-dd")}`);
        }
 
        // Aggiungi il riepilogo
        if (page.summary) {
            dv.paragraph(`**Decisione:** ${page.summary}`);
        }
        
        // Controlla se i tag esistono prima di stamparli
        if (page.tags && page.tags.length > 0) {
            dv.paragraph(`**Tag:** ${page.tags.join(', ')}`);
        }
        
        // Aggiungi un separatore per leggibilità
        dv.paragraph("---");
    }
}

Che cos’è un ADR (Architectural Decision Record)?

Un Architectural Decision Record (ADR) è un breve documento di testo che cattura una decisione architetturale significativa presa durante lo sviluppo di un progetto software, insieme al suo contesto e alle sue conseguenze.

Pensa a un ADR come a una “pagina di diario” del tuo progetto, scritta da un architetto. Non documenta come funziona il codice (quello è compito della documentazione normale e dei commenti), ma perché il codice è strutturato in un certo modo.

Un ADR risponde a domande come:

• “Perché abbiamo scelto la libreria X invece della libreria Y?”

• “Perché abbiamo deciso di usare il pattern A invece del pattern B per risolvere questo problema?”

• “Quale problema stavamo cercando di risolvere quando abbiamo introdotto questo nuovo servizio?”

Componenti Chiave di un ADR (La Struttura)

Un buon ADR è breve e focalizzato. Di solito include queste sezioni:

1. Titolo: Una frase concisa che riassume la decisione (es. “Uso di PostgreSQL come database principale”).

2. Stato: Lo stato attuale della decisione (es. Proposto, Accettato, Obsoleto). Questo è utile in team dove le decisioni vengono discusse.

3. Contesto (Il “Problema”): Qual è il problema che stiamo cercando di risolvere? Quali sono le forze in gioco (requisiti tecnici, di business, limiti di tempo, etc.)? Questa sezione descrive il “perché” abbiamo dovuto prendere una decisione.

4. Decisione (La “Soluzione”): Qual è la soluzione che abbiamo scelto? Descrive il “cosa” abbiamo deciso di fare, in modo chiaro e inequivocabile.

5. Conseguenze (I “Risultati”): Quali sono gli impatti di questa decisione? Questa è la parte più importante. Dovrebbe elencare sia i risultati positivi (es. “maggiore performance”, “codice più semplice”) sia quelli negativi (es. “nuova dipendenza da mantenere”, “curva di apprendimento per il team”). Questo crea una visione bilanciata.

6. Alternative Considerate: Quali altre opzioni abbiamo scartato? E, soprattutto, perché le abbiamo scartate? Questa sezione è cruciale per prevenire che il team rimetta in discussione la stessa decisione mesi dopo, dimenticando le ragioni per cui le alternative erano state escluse.

Struttura del frontmatter

---
id: ADR-*
title: 
version: *
status: Accettato
date: yyyy-mm-dd
doc_type: adr
project: FIRE
framework: quantum-core
parent: 
summary:
tags:
  - adr
    *
---