Log4Brains ADR — Generate an Architecture Decision Record Website from Your Codebase

What Log4Brains does — and what it doesn't

Log4Brains (github.com/thomvaill/log4brains, author Thomas Vaillant) is an open-source Node.js CLI with two functional modes:

• Creation mode (log4brains adr new): Creates a new numbered ADR file in your configured directory — similar to what adr-tools' adr new does, but using Node.js rather than shell scripts. The created file follows the NNNN-slug.md naming convention.
• Publishing mode (log4brains build / log4brains preview): Reads all ADR files in your configured directory and generates a static website showing every ADR, its status, its full content, and its supersession relationships. This is Log4Brains' primary value proposition — the part that adr-tools doesn't provide at all.

What Log4Brains does NOT do:

• It doesn't automatically write ADRs — decisions still need to be written by humans (or extracted from AI chat history via a tool like WhyChose). Log4Brains is purely a read-and-publish layer.
• It doesn't validate ADR quality — for CI enforcement of structure, numbering, and supersession integrity, pair it with the ADR GitHub Action.
• It doesn't replace your git history — every ADR's git blame and commit log remain the canonical history. Log4Brains is a view, not a source of truth.
• It doesn't provide edit access — the generated site is read-only. Edits happen in the repository, and a new build re-deploys the changes.

Install and first run

Log4Brains requires Node.js ≥ 14. Install globally:

npm install --global log4brains

Then initialize Log4Brains in your repository root. The interactive setup asks for your project name and the directory where your ADRs live:

cd my-project
log4brains init

The init command creates a log4brains.yml file at the project root and scaffolds an initial ADR template in your decisions directory. If you already have ADR files in doc/decisions/, they'll be detected automatically — no migration needed.

Preview the generated site locally (runs a Next.js dev server at localhost:4004 by default):

log4brains preview

Create a new ADR (creates a numbered Markdown file using your template):

log4brains adr new "Use PostgreSQL for user data"
# Creates: doc/decisions/0003-use-postgresql-for-user-data.md

Build the static site (output goes to _log4brains/):

log4brains build

The log4brains.yml configuration file

The config file lives at your project root. A minimal single-package config:

project:
  name: my-project
  decisions:
    location: doc/decisions
    titleFormat: "[{deciders}] {title}"   # optional: controls the site's list view title

Key fields:

Log4Brains parses Status from the ADR Markdown body (## Status\nAccepted in Nygard format) and from YAML frontmatter (status: Accepted). It recognizes the standard values: Proposed, Accepted, Deprecated, and Superseded. Supersession relationships are parsed from body text — it looks for "Supersedes [ADR-NNNN]" and "Superseded by [ADR-NNNN]" patterns in the Status or Consequences sections.

Workspace mode for monorepos

If your repository contains multiple packages (a monorepo), each with their own ADR directory, Log4Brains can aggregate them into a single site with per-package filtering. Add a packages array to log4brains.yml:

project:
  name: my-platform
  decisions:
    location: docs/decisions           # shared / cross-cutting decisions

packages:
  - name: api
    decisions:
      location: packages/api/docs/decisions
  - name: frontend
    decisions:
      location: packages/frontend/docs/decisions
  - name: infra
    decisions:
      location: packages/infra/docs/decisions

The generated site shows all ADRs across all packages in a unified timeline, with a per-package filter in the sidebar. The ADR number namespace is scoped per package — package api can have ADR-0001 without colliding with the shared decisions' ADR-0001.

When to use workspace mode vs a flat directory:

• Flat (doc/decisions/ at repo root): For single-product repositories or teams where all engineers share one ADR namespace. Simpler to maintain. Works with the merge-base numbering allocator without modification.
• Workspace mode: For platform teams managing multiple services or a monorepo where each service has its own ADR cadence and ownership. The cross-cutting decisions directory captures the decisions that affect all packages; per-package decisions stay scoped.

Deploy to GitHub Pages

The most common deployment target for Log4Brains sites is GitHub Pages. The workflow deploys on every push to main that touches the ADR directory:

name: Deploy Log4Brains ADR site

on:
  push:
    branches: [main]
    paths:
      - 'doc/decisions/**'
      - 'log4brains.yml'

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # Log4Brains uses git history for dates

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Build Log4Brains site
        run: npx log4brains build

      - name: Add .nojekyll
        run: touch _log4brains/.nojekyll

      - uses: actions/upload-pages-artifact@v3
        with:
          path: _log4brains/

      - id: deployment
        uses: actions/deploy-pages@v4

Two non-obvious requirements in this workflow:

• fetch-depth: 0: Log4Brains uses git commit dates to show when each ADR was created and last modified. A shallow clone (the default) breaks this — you get the wrong dates or blank dates. Full history (fetch-depth: 0) is required.
• .nojekyll: GitHub Pages runs Jekyll by default, which ignores directories and files starting with underscore. Since Log4Brains generates its output into _log4brains/ with Next.js-internal directories like _next/, Jekyll would strip them. The .nojekyll file disables Jekyll and lets GitHub Pages serve the files as-is.

For Netlify or Vercel, the setup is simpler: configure the build command as npx log4brains build and the publish directory as _log4brains. No .nojekyll file needed on those platforms.

Log4Brains vs adr-tools: a comparison

The two tools aren't mutually exclusive. Some teams use adr-tools for local ADR creation (because the shell scripts are fast and have no runtime dependency) and Log4Brains for the published view (because the web UI is what stakeholders actually use). The files are compatible — adr-tools produces Nygard-format files that Log4Brains reads without modification.

Three limitations teams hit most often

1. Build time grows with ADR count and git history size

Log4Brains' build command runs git log on every ADR file to extract authorship dates. For repositories with long histories (thousands of commits) and large ADR directories (100+ files), this can make the build slow — sometimes 2-5 minutes. The mitigation is to scope the GitHub Actions workflow with a paths filter (so the deploy only runs when ADRs actually change) and to use a self-hosted runner with the repo already warm-cloned so the full fetch-depth: 0 checkout doesn't repeat the full clone on every run.

2. Custom templates require forking or upstream contribution

Log4Brains uses a built-in ADR template for log4brains adr new. Teams that want a custom template (to add TOGAF fields, require specific frontmatter, or use a lightweight three-field format) can't configure the template in log4brains.yml — they need to either patch the installed package or submit a PR to upstream. The workaround most teams use: skip log4brains adr new for file creation (use adr-tools or a custom cp template.md script instead) and use Log4Brains only for the build step. The build step reads any valid ADR file regardless of which tool created it.

3. The generated site requires JavaScript

The Log4Brains static site is a Next.js application. It uses client-side JavaScript for search, filtering, and navigation. If your stakeholders need to browse ADRs on a network with a strict content security policy that blocks JavaScript, or if you need to serve the site in a fully offline environment (such as a secure enclave), the Log4Brains output won't work. In those environments, generate Markdown documentation with adr generate toc (adr-tools) and serve the Markdown files via a simple static server or a Docusaurus / Hugo deployment instead.

Pairing Log4Brains with CI quality gates

Log4Brains handles the publishing layer. For the creation and quality-gate layer, pair it with:

• The ADR GitHub Action — CI jobs for structure linting, collision-safe numbering, and bidirectional supersession integrity checks. These run on every PR that touches doc/decisions/, before the merge that triggers Log4Brains to rebuild.
• ADR review checklist — the 12-item human-review gate. Log4Brains makes ADRs visible to a wider audience; the review checklist is what ensures they're worth reading when someone finds them via the site.
• ADR numbering scheme — the merge-base allocator prevents collision on parallel PRs. Log4Brains renders the numbers in the site's navigation and timeline; conflicting numbers break the site's sort order.

The full lifecycle: decide a decision warrants an ADR → create the file (adr-tools or log4brains adr new) → review against the checklist → CI validates structure and numbering → PR merges → Log4Brains GitHub Action rebuilds the site → stakeholders find the decision via search.

How WhyChose fits in

Log4Brains solves the discoverability problem for ADRs that already exist in your repository. It doesn't solve the upstream problem: most architecture decisions never become ADRs at all. They're made in ChatGPT or Claude conversations, recorded nowhere, and discovered only retrospectively when a new engineer asks why the stack looks the way it does.

The WhyChose extractor is the feed for Log4Brains' input directory. It reads your ChatGPT or Claude export, surfaces every decision-shaped conversation with the original reasoning intact, and outputs structured records in Nygard-format Markdown — ready to drop into doc/decisions/. From there, the GitHub Action assigns a number, Log4Brains adds the decision to the site, and the decision becomes searchable by any stakeholder. The full pipeline: AI chat → WhyChose extractor → doc/decisions/ → Log4Brains site → stakeholders.

Get early access

Related questions

Further reading

• The ADR GitHub Action — CI pipeline for architecture decision records — the quality-gate layer that pairs with Log4Brains: structure linting, collision-safe numbering via merge-base allocation, and bidirectional supersession integrity. Run these gates before the merge that triggers Log4Brains to rebuild its site, so the published ADRs meet the review bar before they're publicly visible.
• ADR numbering scheme — padding, gaps, and collision recovery — the merge-base allocator prevents numbering collisions on parallel PRs, which matters more when Log4Brains is publishing the numbers prominently in a web UI. The guide covers the 4-digit zero-padding default, why gaps are correct, and how to recover from collisions that have already happened.
• ADR review checklist — what to look for before merging — the 12-item human quality gate. Log4Brains makes ADRs visible to a wider audience (including non-engineers). The review checklist ensures they're worth reading when someone finds them via the site: decision statement title, real alternatives with rejection rationale, bounded Consequences section, and correct supersession when applicable.
• ADR status template — format, fields, and the lifecycle beyond Accepted — Status is one of the two fields Log4Brains reads to render its badges and filter options. The status template guide covers where Status lives (YAML frontmatter vs body, with tooling implications for each), the five values Log4Brains recognizes, and the optional Trial-Period sixth state for teams above ~20 engineers.
• ADR storage format comparison — Markdown vs AsciiDoc vs Notion vs Confluence vs SharePoint — Log4Brains reads Markdown ADRs from your repo; if your organization stores ADRs in Notion or Confluence instead, Log4Brains doesn't apply directly. The comparison guide covers the trade-offs between storage layers and the migration paths between them (including Markdown → Notion and Notion → Markdown).
• The Nygard ADR template (2026 edition) — Log4Brains is designed around Nygard-format files. The template guide covers the five sections (Title, Status, Context, Decision, Consequences) with exact wording guidance, two common extensions (Alternatives, Stakeholders), and the formatting choices that affect how Log4Brains renders the ADR in its web view.
• When to write an ADR (and when you shouldn't) — Log4Brains' value scales with ADR quality. Filling it with low-value ADRs (implementation details, tactical choices that don't warrant a record) creates noise that makes the real decisions harder to find. The threshold guide covers the four-question test (durable, cross-team, contested, costly-to-reverse) that keeps the directory — and the Log4Brains site — signal-dense.
• ADR adoption guide — how to introduce architecture decision records to a resistant team — teams adopting ADRs often find that a visible Log4Brains site is what converts skeptics: seeing the ADR practice produce a real web product makes the habit feel worth maintaining. The adoption guide's retrospective-first approach produces three or four ADRs that immediately populate the site, demonstrating the end state before asking for ongoing commitment.
• ADR tooling comparison — adr-tools vs Log4Brains vs adr-log vs hand-rolled — the evaluation guide for teams choosing their ADR tooling stack. Covers Log4Brains in context alongside the creation tools it pairs with (adr-tools, adr-log, hand-rolled), the decision tree for picking, and the two jobs (creation vs publication) that the different tools do independently.
• The open-source extractor — outputs Nygard-format Markdown records from ChatGPT and Claude exports; ready to drop into the doc/decisions/ directory that Log4Brains reads. The extractor fills the upstream gap (decisions that never became ADRs); Log4Brains publishes the result.
• ADR directory structure in a monorepo — per-service vs central, numbering, and CI — Log4Brains workspace mode is the practical solution for monorepos with per-service ADR directories: each package entry in log4brains.yml maps to one service directory, and Log4Brains generates a unified site with ADRs grouped by package. The build-time scaling limitation (no parallel builds per package) and custom-template constraint are covered in the monorepo guide.