adr-decision-platform
Web platform to author, version and browse ADRs and RFCs with ready-made templates.
git clone https://github.com/fernandofatech/adr-decision-platform.gitADR Decision Platform is a Next.js 16 web application I built to give solution architects a structured, browsable home for Architecture Decision Records and lightweight RFCs — replacing the usual graveyard of Confluence pages, Slack threads, and forgotten slide decks.
Why I built this
Every team I have worked with had the same problem: architectural decisions were made carefully, then scattered across tools that nobody revisited. Six months later, a new engineer would re-open the same debate, unaware that the trade-off had already been evaluated and documented somewhere no one could find.
The standard answer is "just put ADRs in the repo." That works until you have multiple repos, multiple teams, and decisions that span both. A plain docs/adr/ folder does not give you filtering by status, cross-repo search, or a readable index for stakeholders who do not live in the terminal.
This platform is my answer to that gap. It is not trying to be Backstage or a full-blown knowledge base. It is a focused tool: author a decision using a well-known template, publish it, and let anyone on the team find it by status, tag, or date — without needing Git access or Markdown fluency. The GitHub integration means the source of truth stays in the repository, and the platform is just a better reading and writing surface on top of it.
What the platform includes
In the context of… facing… we decided… to achieve… accepting…) for fast-moving teams.docs/adr/ directory of any connected repository, keeping the repo as the source of truth.How the platform works
Request and data flow from author to published ADR
- Next.js 16 · Frontend
- ADR / RFC · Editor
- ADR Browser · (filter/search)
- Next.js SSR · API Routes
- GitHub API · (REST)
- docs/adr/ · (source of truth)
- GitHub Actions · CI + Security
- Vercel Deploy · (on push)
Tech stack and design choices
The frontend is Next.js 16 with React 19 and TypeScript 5. I chose Next.js because the ADR browser benefits from server-side rendering — search-engine indexing of decisions is a real use case for teams that want their architecture work discoverable — and the API routes give me a clean place to proxy GitHub API calls without exposing tokens to the client.
Styling is Tailwind CSS 4, which keeps the component footprint small and avoids a separate design-system dependency for what is essentially a content-heavy interface.
Deployment is on Vercel with DNS managed through Cloudflare. The production instance lives at adr.moretes.com. Three GitHub Actions workflows run on every push: a general CI check, a frontend-specific build and lint pipeline, and a security scan. The security workflow is the one I care most about in a public repo — it catches dependency vulnerabilities and misconfigured secrets before they reach production.
The GitHub integration is intentionally simple: the platform reads from docs/adr/ in a configured repository using the GitHub REST API. There is no database. The Markdown files in the repo are the canonical record; the platform is a rendering and discovery layer. This keeps the operational surface small and means the ADRs survive even if the platform goes away.
Running locally
- 1
Clone the repository
Clone from GitHub. The project root contains the
frontend/directory and supporting docs. - 2
Install dependencies
Navigate into
frontend/and runnpm install. Node 20+ is recommended to match the Vercel runtime. - 3
Configure environment variables
Copy
.env.exampleto.env.localand set your GitHub token and target repository. The GitHub token needs read access to the repository you want to sync ADRs from. Refer toSETUP.mdfor the full variable list. - 4
Start the development server
Run
npm run devfrom thefrontend/directory. The app will be available athttp://localhost:3000. - 5
Build for production
Run
npm run buildfollowed bynpm startto verify the production build locally before deploying. SeeOPERATIONS.mdfor deployment notes.
# Clone
git clone https://github.com/fernandofatech/adr-decision-platform.git
cd adr-decision-platform/frontend
# Install
npm install
# Configure (edit values before running)
cp .env.example .env.local
# Develop
npm run dev
# → http://localhost:3000
# Production build (optional local check)
npm run build && npm startADR placement convention
The GitHub integration expects ADR files in docs/adr/ of the target repository, following the naming pattern NNNN-short-title.md (e.g. 0012-use-event-sourcing.md). This is the same convention used by the adr-tools CLI, so existing ADR directories should sync without renaming.
Common questions
Does this replace storing ADRs in the repository?
No, and intentionally so. The Markdown files in docs/adr/ remain the source of truth. The platform reads from them; it does not own them. You can stop using the platform at any time and your ADRs are still there, in plain text, in version control.
Which template should I use?
MADR is the most complete and works well for decisions with multiple options to compare. Nygard is faster to fill in and appropriate for straightforward decisions. Y-statements are best for capturing a decision in a single sentence during a meeting or design review. RFCs are for proposals that need async review before a decision is made.
Can I connect multiple repositories?
The README describes syncing from a single docs/adr/ directory. Multi-repo support is not documented in the current README, so I would not assume it is available without checking the source or SETUP.md directly.
Is there a hosted version I can try without running it locally?
Yes. The production instance is live at adr.moretes.com. It is a portfolio deployment, so treat it as a demo rather than a production service with SLA guarantees.
CI badges are real signals
The repository runs three separate GitHub Actions workflows — CI, Frontend, and Security — visible in the README badges. For a portfolio project, having a security scan in the pipeline is a deliberate signal: it reflects the same posture I apply to production systems, where dependency auditing and secret detection are non-negotiable from day one.
Who this is for
This platform is useful if your team already knows ADRs matter but keeps failing to maintain them because the tooling friction is too high. It is aimed at solution architects and tech leads who want a lightweight, self-hostable interface on top of Markdown ADRs already living in GitHub — without adopting a full developer portal like Backstage.
It is not the right fit if you need a database-backed audit trail, fine-grained access control per decision, or integration with tools outside the GitHub ecosystem. For those requirements, a more complete platform is warranted.
As a portfolio piece, the repository demonstrates how I approach a greenfield TypeScript project: Next.js with SSR where it adds value, Tailwind for lean styling, CI from day one, a security workflow that is not an afterthought, and a deployment pipeline that mirrors production practices even at small scale. The code and the architecture docs at docs/architecture.md are the real artefact here.