# adr-decision-platform Web platform to author, version and browse ADRs and RFCs with ready-made templates. - URL: https://fernando.moretes.com/open-source/adr-decision-platform - Markdown: https://fernando.moretes.com/open-source/adr-decision-platform/guide.md?lang=en - GitHub: https://github.com/fernandofatech/adr-decision-platform - Language: TypeScript - Topics: - Stars: 0 - Forks: 0 - Updated: 2026-05-16T01:43:57Z --- ADR 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 - **MADR template** — Markdown Architectural Decision Record with status, context, decision drivers, considered options, and consequences. - **Nygard ADR** — the original short-form template (title, status, context, decision, consequences) for teams that prefer brevity. - **Y-statements** — single-sentence decision capture (`In the context of… facing… we decided… to achieve… accepting…`) for fast-moving teams. - **RFC template** — structured cross-team proposal format for changes that need broader review before a decision is locked. - **ADR browser** — filter and search decisions by status, tag, and date across all indexed records. - **GitHub integration** — sync ADRs directly from the `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 ### 💻 Browser - Next.js 16 Frontend (frontend) - ADR / RFC Editor (frontend) - ADR Browser (filter/search) (frontend) ### ☁️ Vercel - Next.js SSR API Routes (compute) ### 🔗 GitHub - GitHub API (REST) (external) - docs/adr/ (source of truth) (storage) ### 🔒 CI/CD - GitHub Actions CI + Security (ci) - Vercel Deploy (on push) (ci) ### Flows - author -> ui: opens - ui -> editor: selects template - ui -> browser: browses ADRs - editor -> ssr: save / publish - browser -> ssr: filter query - ssr -> gh_api: sync / read - gh_api -> adr_dir: reads markdown files - adr_dir -> gh_api: returns content - gh_api -> ssr: ADR payload - ci -> deploy: triggers on push - deploy -> ssr: deploys build ## 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](https://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 run `npm install`. Node 20+ is recommended to match the Vercel runtime. 3. **Configure environment variables** — Copy `.env.example` to `.env.local` and set your GitHub token and target repository. The GitHub token needs read access to the repository you want to sync ADRs from. Refer to `SETUP.md` for the full variable list. 4. **Start the development server** — Run `npm run dev` from the `frontend/` directory. The app will be available at `http://localhost:3000`. 5. **Build for production** — Run `npm run build` followed by `npm start` to verify the production build locally before deploying. See `OPERATIONS.md` for deployment notes. _Quick start — clone, install and run_ ```bash # 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 start ``` > **ADR 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. ## References - [fernandofatech/adr-decision-platform — GitHub](https://github.com/fernandofatech/adr-decision-platform) - [Live production instance — adr.moretes.com](https://adr.moretes.com) - [MADR — Markdown Architectural Decision Records](https://adr.github.io/madr/) - [Michael Nygard — Documenting Architecture Decisions (original post)](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) - [Next.js 16 documentation](https://nextjs.org/docs) - [Project architecture docs — docs/architecture.md](https://github.com/fernandofatech/adr-decision-platform/blob/main/docs/architecture.md) ## Links - [GitHub repository](https://github.com/fernandofatech/adr-decision-platform)