docs: ADR message broker — PostgreSQL + webhook n8n, no NATS/Redis Streams

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>
This commit is contained in:
2026-03-21 11:03:18 +00:00
parent adb36c0c48
commit a6e286c9cb

View File

@@ -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 ## [2026-03-21] PostgreSQL — Database "pompeo" e schema ALPHA_PROJECT
### Overview ### Overview