Decisions
Architecture decisions
ADRs recording calls that had real alternatives, with reasoning.
These records are binding alongside Architecture unless a conversation explicitly relaxes one. Canonical sources also live under docs/decisions/.
| ADR | Decision |
|---|---|
| 0001 | Postgres is the source of truth |
| 0002 | Not event sourcing, not CQRS |
| 0003 | HTTP/JSON between services, no broker for sync calls |
| 0004 | |
| 0005 | PII is a property of the event type; PII and non-PII events go to separate topics |
| 0006 | No runtime schema registry |
| 0007 | Cedar for authorization, evaluated in process |
| 0008 | Synchronous calls by default; local copies need a reason |
| 0009 | Withdrawn — two regional stacks were never validated |
| 0010 | Identifier strategy |
| 0011 | One entity spec per entity, everything else generated |
| 0012 | One Postgres server, one database per service |
| 0013 | JWT authorization at the service with a trust chain |
| 0014 | Pagination for list endpoints |
| 0015 | Domain-scoped outbox and table prefixes |
| 0016 | Azure Service Bus fanout topology per domain |
| 0017 | Structured logging and request correlation |
| 0018 | Shared platform code in common/ |
| 0019 | The handler layer: shared, generated, or hand-written |
| 0020 | Frontend layering: where a file goes in a Next.js app |
| 0021 | Datadog log search in the DevOps console |
| 0022 | pgvector in services/intelligence, a single-service carve-out |
| 0023 | One sqlc package per domain, and no joins between domains |
| 0024 | Evidence stays in workspace; intelligence stores pointers |
| 0025 | Knowledge is company-wide; projects control access to evidence |
| 0026 | Scheduled work is a scheduler calling an endpoint |
| 0027 | How trusted a claim is, kept separate from where it is in the workflow |
| 0028 | Evidence does not need a project |
| 0041 | Azure Service Bus in all environments; RabbitMQ removed |
| 0043 | The workspace audit log is a workspace domain |
| 0044 | Broker owns usage, prices, and budgets |
| 0045 | Communications is the shared send-and-thread pipe |
| 0046 | Foundry agents are lifetime × run type |
| 0070 | HTTP tracing with OpenTelemetry and durable trace context |
| 0098 | Broker picks a cheaper model in the same family when a person is opted in |
| 0100 | Broker routing is on by default, graded by a Go check, Jev, then a chat model; an API credential is personal or service |
When proposing a change that contradicts an ADR, update the ADR or add a new one — do not treat undocumented choices as settled.