first

docs/adr/ADR-0003-rabbitmq-event-backbone.md

@@ -0,0 +1,61 @@
+# ADR-0003 — RabbitMQ as Event and Job Backbone
+
+- **Status:** Accepted
+- **Date:** 2026-09-07
+- **Deciders:** ASF Architecture Team
+
+## Context
+
+ASF has two asynchronous messaging needs:
+1. **Domain events** (facts that happened — `artifact.created`,
+   `deployment.completed`, …) used for decoupled side effects.
+2. **Asynchronous jobs** (AI inference, indexing, code analysis, testing)
+   that need separate queues with priorities and horizontal workers.
+
+A single backbone that handles both patterns is preferred to reduce
+infrastructure surface.
+
+## Decision
+
+Adopt **RabbitMQ 3.13+** as the sole event/job backbone.
+
+### Logical queues
+
+| Queue                  | Purpose                                | Priority |
+|------------------------|----------------------------------------|----------|
+| `asf.ai.interactive`   | Latency-sensitive user-facing AI work  | High     |
+| `asf.ai.background`    | Batch / low-priority AI work           | Normal   |
+| `asf.indexing`         | Repository / document indexing         | Low      |
+| `asf.code_analysis`    | Static analysis tasks                  | Normal   |
+| `asf.testing`          | Test execution requests                | Normal   |
+| `asf.devops`           | Deployment / CI orchestration          | Normal   |
+| `asf.notifications`    | Emails / webhooks / in-app notif.      | Normal   |
+
+### Source of truth
+RabbitMQ delivers work. **Persistent job state** (status, timestamps,
+usage, error, correlation) lives in MongoDB `jobs` collection. Workers
+update Mongo as they progress through `queued → running → completed|failed`.
+
+RabbitMQ is **never** the permanent system of record for job state.
+
+### Event format
+Every event message contains:
+```
+event_id, event_type, timestamp, tenant_id, project_id?,
+correlation_id, causation_id?, payload
+```
+
+Large payloads / binaries go to MinIO; the message carries only a
+reference.
+
+## Consequences
+
+### Positive
+- One broker, well-understood routing / priority / TTL / DLX semantics.
+- Workers are stateless, horizontally scalable processes.
+- At-least-once delivery matches domain; idempotency keys on workers
+  prevent duplicate side-effects.
+
+### Negative
+- Exactly-once is not provided — consumers must be idempotent.
+- Operational complexity of a broker (mitigated by managed services in prod).