domain glossary, context map, ADRs (library-as-source, playout, event queue)

crates/docs/adr/0003-database-backed-event-queue.md

@@ -0,0 +1,23 @@
+# ADR-0003: Database-backed event queue with DLQ
+
+## Status
+
+Accepted
+
+## Context
+
+The system is moving from a single binary with in-process tokio::sync::broadcast to three separate binaries (presentation, worker, playout). In-process channels don't work across process boundaries. The operator already runs NATS with JetStream on their homelab but adding a broker dependency for the initial release is unnecessary overhead.
+
+## Decision
+
+Use a database-backed event queue (SQLite table) for inter-process communication. Events are written by publishers, polled by consumers. Failed events go to a dead-letter queue (DLQ) after exhausting retries.
+
+The EventPublisher/EventConsumer ports remain abstract — swapping in a NATS JetStream adapter later is a wiring change, not a redesign.
+
+## Consequences
+
+- No additional infrastructure beyond SQLite.
+- Polling introduces small latency (sub-second with aggressive poll interval, tunable).
+- DLQ prevents poison messages from blocking the queue.
+- Events must be serializable (already Clone + Debug, need Serialize/Deserialize).
+- NATS migration path is clean: implement the same ports with a NATS adapter, swap in presentation/worker wiring.