Emily Chen·
Honest ADR that talked me out of Kafka for a low-volume feature and into Postgres NOTIFY
Generates well-structured Architecture Decision Records capturing context, decision, consequences, and compliance tracking for engineering governance.
Architecture Decision Record (ADR) Generator
You are a Staff Engineer responsible for architecture governance at a scale-up company. Write a comprehensive Architecture Decision Record.
**Decision Title**: {{decision_title}}
**Context/Background**: {{context_background}} (what situation led to this decision being needed?)
**Options Under Consideration**: {{options_considered}} (list the specific technologies or approaches being compared)
**Decision Drivers**: {{decision_drivers}} (what factors are most important: performance, cost, team expertise, time to market, etc.)
Generate a complete ADR following this structure:
1. **ADR Metadata** - Number (e.g., ADR-042), Title, Status (proposed/accepted/deprecated/superseded), Date, Deciders
2. **Context and Problem Statement** - 2-3 paragraphs describing the forces at play (technical, political, social, project-local)
3. **Decision Drivers** - Prioritized list of factors with weightings (e.g., Performance: 30%, Cost: 25%, Team Expertise: 20%, Time to Market: 15%, Ecosystem: 10%)
4. **Considered Options** - Detailed description of each option with:
- Description
- Pros (numbered list)
- Cons (numbered list)
- Mitigations for each con
5. **Decision Outcome** - The chosen option with clear justification referencing decision drivers
6. **Consequences** - Separate lists for:
- Positive consequences (becomes requirements)
- Negative consequences (becomes risks to monitor)
- Neutral consequences (things that change but aren't good or bad)
7. **Validation** - How we'll know this decision was correct (metrics, review date, success criteria)
8. **Prospects of Reversal** - Under what conditions this ADR would be revisited or superseded
9. **Related Decisions** - Links to related ADRs, dependencies on other decisions, decisions this enables
10. **Notes** - Meeting notes, discussion points, dissenting opinions and why they were considered but overruled
11. **Compliance Check** - How to verify this decision is being followed (automated linting, code review checklist, architecture review)
12. **Appendix** - Benchmarks, proof-of-concept results, references, vendor documentation links
Use the Nygard ADR format with Michael Keeling extensions. Be honest about trade-offs and negative consequences.
Ergebnisse
# ADR-051: Adopt Postgres LISTEN/NOTIFY over Kafka for in-app notifications
**Status:** Accepted · **Deciders:** Backend lead, SRE
## Context
We need to push in-app notifications (comment replies, mentions) to connected clients. Volume is modest — low thousands per minute — but the team reflexively reached for Kafka. Standing up and operating a Kafka cluster for this single feature is disproportionate to the load.
## Decision drivers
- Operational simplicity: **35%**
- Team expertise: **25%**
- Latency: **20%**
- Future scale headroom: **20%**
## Considered options
**Option A — Kafka topic + consumer**
- Pros: 1) battle-tested at scale; 2) replayable.
- Cons: 1) a whole cluster to operate for one low-volume feature *(mitigation: managed MSK — but the cost/ops still dwarf the need)*; 2) no existing Kafka expertise on the team.
**Option B — Postgres LISTEN/NOTIFY**
- Pros: 1) zero new infrastructure, Postgres is already the system of record; 2) sub-50ms delivery; 3) the whole team already knows Postgres.
- Cons: 1) doesn't replay missed events *(mitigation: clients reconcile against a `notifications` table on reconnect)*; 2) won't scale past a single primary *(mitigation: documented trigger to revisit at higher volume)*.
## Decision
**Option B.** It scores highest on the two heaviest drivers (operational simplicity, team expertise) and meets the latency target. We accept the scale ceiling deliberately.
## Consequences
- **Positive:** no new system to run, monitor, or secure.
- **Negative (monitor):** a single-primary bottleneck — track notification fan-out latency.
- **Reversal condition:** if sustained throughput exceeds a few thousand/sec, supersede this ADR with a Kafka-backed design.
**Compliance check:** a lint rule flags any new direct Kafka client import in this module.
Modell: Claude Opus 4
32 Likes12 SavesScore: 29
2 Kommentare
Luca Brunner·
Been looking for a solid system design prompt for ages, this is it.
Jonas Weber·
The fact that it flagged the latent bug instead of just rewriting is the real win.