From a6e286c9cb3236c7cac6be6b9f51f89e19f4fd7a Mon Sep 17 00:00:00 2001 From: Martin Date: Sat, 21 Mar 2026 11:03:18 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20ADR=20message=20broker=20=E2=80=94=20Po?= =?UTF-8?q?stgreSQL=20+=20webhook=20n8n,=20no=20NATS/Redis=20Streams?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documenta la decisione architetturale di non deployare un broker dedicato. agent_messages su Postgres copre il flow normale; webhook n8n diretto gestisce il bypass high-priority. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 541b788..cf9aeea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,38 @@ Tutte le modifiche significative al progetto ALPHA_PROJECT sono documentate qui. --- +## [2026-03-21] ADR — Message Broker: nessun broker dedicato + +### Decisione + +**Non verrà deployato un message broker dedicato** (né NATS JetStream né Redis Streams). Il blackboard pattern viene implementato interamente su PostgreSQL + webhook n8n. + +### Ragionamento + +Al momento della progettazione iniziale, il broker era necessario per disaccoppiare gli agenti dall'Arbiter. Con l'introduzione della tabella `agent_messages` nel database `pompeo`, questo obiettivo è già raggiunto: + +``` +Agente n8n → INSERT agent_messages (arbiter_decision = NULL) +Arbiter → SELECT WHERE arbiter_decision IS NULL (polling a cron) + → UPDATE arbiter_decision = 'notify' | 'defer' | 'discard' +``` + +Il flusso high-priority (bypass immediato dell'Arbiter) viene gestito con una chiamata diretta al **webhook n8n dell'Arbiter** da parte dell'agente — zero infrastruttura aggiuntiva. + +### Alternative valutate + +| Opzione | Esito | Motivazione | +|---|---|---| +| `agent_messages` su PostgreSQL | ✅ **Adottata** | Già deployata, persistente, queryabile, audit log gratuito | +| Redis Streams | ⏸ Rimandato | Già in cluster, valutabile se volume cresce | +| NATS JetStream | ❌ Scartato | Nuovo componente da operare, overkill per il volume attuale (pochi msg/ora) e per il caso d'uso single-household | + +### Impatto su README.md + +La sezione "Message Broker (Blackboard Pattern)" rimane valida concettualmente. Il campo `agent` e il message schema definiti nel README vengono rispettati nella tabella `agent_messages` — cambia solo il mezzo di trasporto (Postgres invece di NATS/Redis). + +--- + ## [2026-03-21] PostgreSQL — Database "pompeo" e schema ALPHA_PROJECT ### Overview