# adr-decision-platform Plataforma web para criar, versionar e navegar ADRs e RFCs com templates prontos. - URL: https://fernando.moretes.com/open-source/adr-decision-platform - Markdown: https://fernando.moretes.com/open-source/adr-decision-platform/guide.md?lang=pt - GitHub: https://github.com/fernandofatech/adr-decision-platform - Language: TypeScript - Topics: - Stars: 0 - Forks: 0 - Updated: 2026-05-16T01:43:57Z --- ADR Decision Platform é uma aplicação web em Next.js 16 que construí para dar aos arquitetos de solução um lugar estruturado e navegável para Architecture Decision Records e RFCs leves — substituindo o cemitério habitual de páginas no Confluence, threads no Slack e apresentações esquecidas. ## Por que construí isso Cada time com que trabalhei tinha o mesmo problema: decisões arquiteturais eram tomadas com cuidado e depois espalhadas por ferramentas que ninguém revisitava. Seis meses depois, um novo engenheiro reabria o mesmo debate sem saber que o trade-off já havia sido avaliado e documentado em algum lugar que ninguém conseguia encontrar. A resposta padrão é 'coloque os ADRs no repositório.' Isso funciona até você ter múltiplos repositórios, múltiplos times e decisões que abrangem ambos. Uma pasta `docs/adr/` simples não oferece filtragem por status, busca entre repositórios ou um índice legível para stakeholders que não vivem no terminal. Esta plataforma é minha resposta a essa lacuna. Ela não tenta ser o Backstage nem uma base de conhecimento completa. É uma ferramenta focada: escreva uma decisão usando um template conhecido, publique-a e deixe qualquer pessoa do time encontrá-la por status, tag ou data — sem precisar de acesso ao Git ou fluência em Markdown. A integração com o GitHub garante que a fonte da verdade permaneça no repositório, e a plataforma é apenas uma superfície melhor de leitura e escrita sobre ele. ## O que a plataforma inclui - **Template MADR** — Markdown Architectural Decision Record com status, contexto, drivers de decisão, opções consideradas e consequências. - **ADR Nygard** — o template curto original (título, status, contexto, decisão, consequências) para times que preferem brevidade. - **Y-statements** — captura de decisão em uma frase (`No contexto de… enfrentando… decidimos… para alcançar… aceitando…`) para times ágeis. - **Template RFC** — formato estruturado de proposta entre times para mudanças que precisam de revisão mais ampla antes de uma decisão ser consolidada. - **Browser de ADRs** — filtre e pesquise decisões por status, tag e data em todos os registros indexados. - **Integração com GitHub** — sincronize ADRs diretamente do diretório `docs/adr/` de qualquer repositório conectado, mantendo o repo como fonte da verdade. ## Como a plataforma funciona Fluxo de requisição e dados do autor até o ADR publicado ### 💻 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) ### Fluxos - author -> ui: acessa - ui -> editor: seleciona template - ui -> browser: navega ADRs - editor -> ssr: salva / publica - browser -> ssr: consulta filtro - ssr -> gh_api: sincroniza / lê - gh_api -> adr_dir: lê arquivos markdown - adr_dir -> gh_api: retorna conteúdo - gh_api -> ssr: payload do ADR - ci -> deploy: dispara no push - deploy -> ssr: implanta build ## Stack tecnológica e escolhas de design O frontend é Next.js 16 com React 19 e TypeScript 5. Escolhi Next.js porque o browser de ADRs se beneficia de server-side rendering — a indexação por mecanismos de busca das decisões é um caso de uso real para times que querem que seu trabalho arquitetural seja descoberto — e as API routes me dão um lugar limpo para fazer proxy das chamadas à API do GitHub sem expor tokens ao cliente. A estilização é Tailwind CSS 4, que mantém o footprint dos componentes pequeno e evita uma dependência de design system separada para o que é essencialmente uma interface rica em conteúdo. O deploy é na Vercel com DNS gerenciado pelo Cloudflare. A instância de produção está em [adr.moretes.com](https://adr.moretes.com). Três workflows do GitHub Actions rodam a cada push: uma verificação geral de CI, um pipeline de build e lint específico do frontend, e um scan de segurança. O workflow de segurança é o que mais me importa em um repositório público — ele detecta vulnerabilidades de dependências e segredos mal configurados antes que cheguem à produção. A integração com o GitHub é intencionalmente simples: a plataforma lê de `docs/adr/` em um repositório configurado usando a API REST do GitHub. Não há banco de dados. Os arquivos Markdown no repositório são o registro canônico; a plataforma é uma camada de renderização e descoberta. Isso mantém a superfície operacional pequena e garante que os ADRs sobrevivam mesmo que a plataforma deixe de existir. ## Executando localmente 1. **Clone o repositório** — Clone do GitHub. A raiz do projeto contém o diretório `frontend/` e documentação de suporte. 2. **Instale as dependências** — Navegue até `frontend/` e execute `npm install`. Node 20+ é recomendado para corresponder ao runtime da Vercel. 3. **Configure as variáveis de ambiente** — Copie `.env.example` para `.env.local` e defina seu token do GitHub e o repositório alvo. O token do GitHub precisa de acesso de leitura ao repositório do qual você quer sincronizar ADRs. Consulte `SETUP.md` para a lista completa de variáveis. 4. **Inicie o servidor de desenvolvimento** — Execute `npm run dev` dentro do diretório `frontend/`. A aplicação estará disponível em `http://localhost:3000`. 5. **Build para produção** — Execute `npm run build` seguido de `npm start` para verificar o build de produção localmente antes do deploy. Consulte `OPERATIONS.md` para notas de implantação. _Início rápido — clone, instale e execute_ ```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 ``` > **Convenção de localização dos ADRs:** A integração com o GitHub espera arquivos ADR em `docs/adr/` do repositório alvo, seguindo o padrão de nomenclatura `NNNN-titulo-curto.md` (ex: `0012-use-event-sourcing.md`). Esta é a mesma convenção usada pelo CLI `adr-tools`, então diretórios ADR existentes devem sincronizar sem necessidade de renomeação. ## Perguntas frequentes ### Isso substitui armazenar ADRs no repositório? Não, e intencionalmente assim. Os arquivos Markdown em `docs/adr/` continuam sendo a fonte da verdade. A plataforma lê deles; não os possui. Você pode parar de usar a plataforma a qualquer momento e seus ADRs ainda estarão lá, em texto simples, no controle de versão. ### Qual template devo usar? MADR é o mais completo e funciona bem para decisões com múltiplas opções a comparar. Nygard é mais rápido de preencher e adequado para decisões diretas. Y-statements são melhores para capturar uma decisão em uma única frase durante uma reunião ou design review. RFCs são para propostas que precisam de revisão assíncrona antes de uma decisão ser tomada. ### Posso conectar múltiplos repositórios? O README descreve a sincronização a partir de um único diretório `docs/adr/`. Suporte a múltiplos repositórios não está documentado no README atual, portanto não assumiria que está disponível sem verificar o código-fonte ou o `SETUP.md` diretamente. ### Existe uma versão hospedada que posso experimentar sem executar localmente? Sim. A instância de produção está disponível em adr.moretes.com. É um deploy de portfólio, então trate-o como uma demonstração em vez de um serviço de produção com garantias de SLA. > **Os badges de CI são sinais reais:** O repositório executa três workflows separados do GitHub Actions — CI, Frontend e Security — visíveis nos badges do README. Para um projeto de portfólio, ter um scan de segurança no pipeline é um sinal deliberado: reflete a mesma postura que aplico a sistemas de produção, onde auditoria de dependências e detecção de segredos são inegociáveis desde o primeiro dia. ## Para quem é isso Esta plataforma é útil se seu time já sabe que ADRs são importantes, mas continua falhando em mantê-los porque o atrito com as ferramentas é muito alto. É voltada para arquitetos de solução e tech leads que querem uma interface leve e auto-hospedável sobre ADRs em Markdown que já vivem no GitHub — sem adotar um portal completo de desenvolvedores como o Backstage. Não é a escolha certa se você precisa de uma trilha de auditoria com banco de dados, controle de acesso granular por decisão ou integração com ferramentas fora do ecossistema GitHub. Para esses requisitos, uma plataforma mais completa é necessária. Como peça de portfólio, o repositório demonstra como abordo um projeto TypeScript do zero: Next.js com SSR onde agrega valor, Tailwind para estilização enxuta, CI desde o primeiro dia, um workflow de segurança que não é uma reflexão tardia, e um pipeline de deploy que espelha práticas de produção mesmo em pequena escala. O código e os documentos de arquitetura em `docs/architecture.md` são o artefato real aqui. ## Referências - [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)