adr-decision-platform

ADR Decision Platform is where an architecture decision stops being a chat message and becomes a record with an owner, a date, a status and consequences. It is a web application — Next.js 16, React 19, TypeScript 5 and Tailwind CSS 4 — deployed on Vercel with DNS on Cloudflare; the production instance runs at adr.moretes.com.

The scope is deliberately narrow. It does four things: offers templates for writing the decision (MADR, Nygard, Y-statement and an RFC model for cross-team proposals); lists decisions in a browsable index; versions each record so the status change from proposed to accepted or superseded stays traceable; and syncs ADRs that already live in docs/adr/ of any repository, so the platform never forces anyone to abandon Markdown in Git.

What it is not: it is not a wiki, not a replacement for the repository, and not an approval system with a complex state workflow. The repository remains the source of truth — the platform exists so the decision can be found by whoever joins the team two years later.

After 16 years operating financial platforms on AWS, the problem I saw repeat most often was not the wrong decision — it was the lost one. The reason a system used SQS instead of Kinesis lived in an archived Slack thread; the rationale for the multi-account layout was in a slide only the architect who left still had. When someone questions the decision three years later, nobody knows whether it still holds or whether the context that motivated it has already changed.

ADRs have solved this for a long time — the Nygard format dates from 2011 — but the format does not solve the access problem. ADRs in docs/adr/ across twenty different repositories are ADRs nobody reads outside the team that owns the repository. Whoever needs the decision does not know where it is, and whoever knows where it is does not know another team already decided the opposite.

The platform exists to close that gap: keep the Markdown in Git, where it already lives, and provide an index that crosses repositories. The cost it attacks is not the cost of writing the ADR — it is the cost of keeping it findable and reviewable over years, after the team has changed.

All application code lives in frontend/, a Next.js 16 project with React 19 in TypeScript 5. The presentation layer is Tailwind CSS 4. There is no separate backend in the repository: whatever needs a server runs in the Next.js routes themselves on Vercel.

Templates: each format is a field model the authoring form fills in. MADR asks for considered options and pros and cons per option; Nygard asks only for context, decision and consequences; the Y-statement reduces everything to one sentence shaped as "in the context of X, facing Y, we decided Z to achieve W, accepting V". The RFC template is the same mechanism with fields for proposal and discussion.

Index: the browser lists decisions and filters by status, tag and date. This is what makes the platform useful to someone who did not write the ADR — the status filter answers "what is still proposed?", and the tag filter answers "what have we already decided about messaging?".

GitHub sync: the platform reads docs/adr/ from a repository and pulls the files into the index. It is the path for teams that already write ADRs in Markdown and do not want to migrate anything — Git stays the owner of the text.

Pipeline: three GitHub Actions workflows — CI, Frontend and Security — plus the Vercel deploy. DNS for adr.moretes.com is on Cloudflare. Architecture details in docs/architecture.md; operations in OPERATIONS.md and SETUP.md.

Having four formats does not mean all four fit everything. The choice is conditional, and erring toward the heavy format is as bad as erring toward the light one: a two-page ADR for a one-sentence decision gets neither written nor read.

Use MADR when: the decision has three or more real options, the cost of being wrong is high — changing database, multi-account strategy, identity provider — and someone will need the per-option pros and cons to challenge the decision later.

Use Nygard when: there are two options and one is clearly better in your context; what matters is recording context and consequence, not the comparison matrix.

Use Y-statements when: the decision is local, reversible within a sprint, and the team makes several a week. One sentence with context, decision, goal and accepted trade-off beats nothing — and nothing is what happens when the format is too heavy.

Use RFC when: the decision is not yet yours to make. The proposal crosses teams and needs comment before becoming an ADR. When the RFC closes, the resulting ADR should point back to it.

The rule I use: if you cannot write the Y-statement, you are not ready to write the MADR. The long format does not replace clarity — it only exposes its absence over more lines.