ADR generator
Generate a Michael-Nygard-style Architecture Decision Record in markdown. Fill in context, decision, alternatives, and consequences — copy the output or download as a .md file.
How it works
Edit any field on the left. The markdown preview on the right updates instantly. Copy to clipboard or download as a.md file. Commit it alongside the architecture change it covers.
No signup. No tracking. Pure client-side; the ADR never leaves your browser.
ADR fields
Markdown preview
# ADR-20260528-001: Use Postgres as the primary application database **Status:** Proposed **Date:** 2026-05-28 ## Context The application needs a primary datastore for relational entities (users, projects, stories). We need ACID guarantees for the financial-adjacent flows, broad ecosystem support, and a managed-hosting story that lets us focus on the application rather than database operations. ## Decision Adopt PostgreSQL (managed via Neon for development, RDS Postgres for production) as the primary application database. All entity persistence goes through Prisma against this Postgres instance. ## Alternatives considered - MongoDB — rejected: most of our data is relational; the schema flexibility is not worth the loss of ACID on multi-document transactions. - DynamoDB — rejected: access patterns aren't fully known at modelling time; the partition-key discipline would be expensive to retrofit later. - PlanetScale (MySQL) — close second; rejected because Postgres has better JSON support and our team has deeper Postgres operational experience. ## Consequences - All schema changes go through Prisma migrations; raw SQL is reserved for features Prisma can't express (extensions, GIN indexes, partial-index WHERE clauses). - We accept the operational cost of running Postgres in production — backups, point-in-time recovery, connection pooling, vacuum tuning. - When read-traffic exceeds what a single Postgres instance can serve, we add read replicas before considering sharding or migrating to a different database.
About ADRs
An Architecture Decision Record captures a single architecture choice — what was decided, why, what alternatives were rejected, and what consequences the team accepts. ADRs are immutable: a new decision creates a new ADR that supersedes the old one. They live in the codebase or design tool so the rationale travels with the architecture.
The format was popularised by Michael Nygard's 2011 blog post and has become canonical for medium-to-large engineering organisations. A team's ADR log is its institutional memory; without it, every architecture question gets re-litigated when a new engineer joins.
For the deeper framework — when to write an ADR, how to handle superseded decisions, and how to keep the log healthy — read the ADR glossary entry.
Want ADRs as first-class artefacts?
Stride's Design module stores ADRs as typed nodes in the delivery graph — linked to the stories, code changes, and architecture diagrams they affect. No more orphan markdown files in docs/adr/ that nobody finds.