Architecture Decision Records¶
This directory captures the why behind non-obvious technical decisions. Each ADR is a short, self-contained document that prevents re-litigation of settled questions.
Format¶
Every ADR follows this template:
# ADR-NNNN — Title
**Status:** Accepted | Superseded by ADR-XXXX | Deprecated
**Date:** YYYY-MM-DD
**Author(s):** name(s)
## Context
What problem or question prompted this decision?
## Decision
What was decided?
## Alternatives considered
What else was on the table, and why was it rejected?
## Consequences
What are the tradeoffs? What new constraints does this create?
## References
- File:line citations, links to docs, memory pointers
Adding a new ADR¶
- Use the next available number:
ADR-NNNN. - Create
docs/adr/NNNN-short-title.md. - Fill in all sections — especially Alternatives considered. The point of an ADR is not just recording what we chose, but why we rejected the alternatives.
- Set status to
Accepted. - If a new ADR supersedes an old one, update the old one's status to
Superseded by ADR-NNNN.
Index¶
| ADR | Title | Status |
|---|---|---|
| 0001 | Pino (framework) + Winston/EvoLogger (app-code) coexistence | Accepted |
| 0002 | Spanmetrics connector over Prisma native /metrics | Accepted |
| 0003 | BullMQ for production async; RabbitMQ kept but stubbed | Accepted |
| 0004 | @vercel/otel pinned to 1.x on Next.js | Accepted |
| 0005 | OTel traceparent not propagated on Redis pub/sub RPC | Accepted |
| 0006 | Prisma schema split across 3 files | Accepted |
| 0007 | EvoLogger facade kept instead of migrating to pino | Accepted |
| 0008 | fakeUserOnline inflates the online counter | Accepted |
| 0009 | Jaeger v2 + Badger over Tempo / managed OpenSearch | Accepted |
| 0010 | Doppler over HashiCorp Vault and AWS SSM Parameter Store | Accepted |
| 0011 | NestJS monorepo with 5 apps + 11 libs (over polyrepo) | Accepted |
| 0012 | Tail-sampling policy: 100 % errors + 100 % slow + 10 % OK | Accepted |