Architecture Decision Records (ADR)
Un ADR registra una decisione architetturale significativa: il contesto, la scelta e le conseguenze. Serve a ricordare perché le cose stanno così, evitando di rimettere in discussione decisioni già ponderate (o di cambiarle senza accorgersi del costo).
Quando scrivere un ADR
- Si introduce una nuova dipendenza o tecnologia.
- Si sceglie un pattern strutturale (es. modalità di idempotenza, formato di scambio).
- Si cambia una convenzione che vale per tutto il repo.
- Si abbandona/sostituisce una decisione precedente.
Come
- Copia il template qui sotto in
NNNN-titolo-breve.md(numero progressivo). - Compila contesto, decisione, conseguenze.
- Apri PR: l'ADR si discute e si approva come il codice.
- Quando una decisione viene superata, non cancellarla: imposta stato
Sostituita da [NNNN].
Indice
| N. | Titolo | Stato |
|---|---|---|
| 0001 | Registrare le decisioni architetturali | Accettata |
| 0002 | ETL code-first in TypeScript (vs Talend) | Accettata |
| 0003 | Connettore Postgres basato su pg + pg-cursor | Accettata |
| 0004 | Connettore SQL Server basato su mssql (tedious) | Accettata |
| 0005 | Distribuzione come immagine container con CLI | Accettata |
| 0006 | RunReport come prodotto; servizio stateless/agnostico | Accettata |
| 0007 | File connector: storage × codec (componibili) | Accettata |
| 0008 | Codec CSV (csv-parse / csv-stringify) | Accettata |
| 0009 | Storage S3 (AWS SDK v3 + lib-storage) | Accettata |
| 0010 | Codec Excel/XLSX (exceljs) | Accettata |
| 0011 | Storage SFTP (ssh2-sftp-client) | Accettata |
| 0012 | Codec XML (fast-xml-parser) | Accettata |
| 0013 | Codec Parquet (@dsnp/parquetjs) | Accettata |
| 0014 | Connettore dedicato per i file dei workspace Noeva | Accettata |
| 0015 | Storage FTP/FTPS basato su basic-ftp | Accettata |
| 0016 | Pipeline a grafo (DAG): nodi/edge validati a runtime | Accettata |
| 0017 | Worker daemon su processes (@my-ginkgo/noeva-shared) | Superata da 0019 |
| 0018 | Report sintetico e progress per nodo via writeReport | Accettata |
| 0019 | Worker daemon su processes: polling via noeva-server-api, non Supabase diretto | Accettata |
| 0020 | Descriptor del connettore per la visualizzazione dei nodi in UI | Accettata |
| 0021 | Worker daemon multi-workspace: un'istanza serve N workspace via N poller | Accettata |
| 0022 | Workspace registry: i connettori Noeva possono puntare solo a workspace configurati | Accettata |
| 0023 | Deploy della UI come immagine nginx su ECR, insieme al worker | Superata da 0025 |
| 0024 | Server HTTP dei grafi delle pipeline (etl serve) | Accettata |
| 0025 | noeva-etl-ui come app desktop Tauri v2 (non più web-app nginx) | Accettata |
| 0026 | Colonne dei nodi del DAG via introspezione degli schemi Zod + propagazione | Accettata |
| 0027 | Dead-letter visibile nella DAG (nodo sintetico + edge d'errore) | Accettata |
| 0028 | etl serve co-locato col worker (avvio unico) | Accettata |
| 0029 | Nodo try/catch: instradamento errori downstream su un branch di catch | Accettata (rivista da 0031) |
| 0030 | Registry istanze connettore: N istanze per tipo, via lista env + registry generico | Accettata |
| 0031 | Guard try/catch: cattura per-record di default (N record per branch) | Accettata |
| 0032 | Sink proteggibili da un guard e isolabili per-record (path di fallback) | Accettata |
| 0033 | Payload dei nodi non isolabili sul ramo catch (lastConsumed) | Accettata |
| 0034 | Corpo del record fallito nel report, dietro opt-in esplicito per guard | Accettata |
| 0035 | Identità di record e lineage derivedFrom, con snapshot al guard | Accettata |
| 0036 | Rimozione del DSL lineare: il grafo è l'unico modo di costruire un processo | Accettata |
| 0037 | Parallelismo reale e osservabile: onNodeStart e join non serializzante | Accettata |
| 0038 | Il report di una run fallita conserva topologia e conteggi parziali | Accettata |
| 0039 | Storico locale delle run: il core resta stateless, persiste il chiamante | Accettata |
| 0040 | Eventi di run live via SSE dal server locale, non via polling | Accettata |
| 0041 | Nodo lookup: query SQL in sola lettura in mezzo al grafo | Accettata |
| 0042 | Sorgente a cartella e sink multi-file su Noeva | Accettata |
| 0043 | Sito di documentazione generato da docs/ con VitePress | Accettata |
| 0044 | La documentazione vive nell'app desktop, al posto della guida in-app | Accettata |
| 0045 | La variante pubblica del sito si pubblica su Cloudflare Workers | Accettata |
Template
markdown
# NNNN. Titolo della decisione
- **Stato:** Proposta | Accettata | Sostituita da [NNNN]
- **Data:** YYYY-MM-DD
- **Decisori:** nomi
## Contesto
Qual è il problema o la forza in gioco? Quali vincoli?
## Decisione
Cosa abbiamo deciso di fare, in modo netto.
## Alternative considerate
- Opzione A — perché scartata.
- Opzione B — perché scartata.
## Conseguenze
- Positive: ...
- Negative / costi: ...
- Cosa diventa più difficile da cambiare in futuro.