Hoe je architectuurbeslissingen in code niet meer kwijtraakt met Log4brains

Heb je ooit naar een module gekeken die anderhalf jaar oud is, een vreemde architectuurbeslissing zag, en werkelijk niet begreep waarom deze gemaakt was? Je handen jeuken om het te herschrijven. Maar dan kom je erachter dat deze eigenaardigheid specifiek ontworpen was om een bug in een third-party API of een bepaalde beveiligingsvereiste te omzeilen. De persoon die het bedacht heeft is allang naar een ander team verhuisd, Confluence is leeg, en alles wat er in git achterblijft is een commit met de lakonieke fix: refactor storage.

Het Architecture Decision Records (ADR) concept lost dit probleem al dertien jaar op. Maar handmatig markdown-bestanden onderhouden en georganiseerd houden is meestal iets waar iedereen te lui voor is. Franse ontwikkelaar Thomas Vaillant creëerde Log4brains, een tool die architectuurbeslissingen vastleggen omzet in een handige docs-as-code workflow.

Wat is deze tool

Log4brains neemt je ADR's, opgeslagen in de repository naast je broncode, parseert ze, en bouwt een snelle statische site met handige zoekfunctie en een tijdlijn.

De utility is geschreven in TypeScript en draait via de command line. Het project is echter niet gebonden aan het JS-ecosysteem. Je kunt het uitvoeren in Python, Go, Java, of Rust repositories via een wereldwijd npm-pakket of Docker-image.

Het punt van ADR's is dat deze documenten onveranderlijk zijn. Je legt het probleem vast, de context, de gekozen optie, en de gevolgen. Als een beslissing een jaar later achterhaald is, bewerk je het oude bestand niet achteraf. Je maakt een nieuw ADR met een supersedes status die verwijst naar de vorige. De gedachtegeschiedenis blijft intact.

Wat Log4brains kan doen

Onder de motorkap verbergt de utility verschillende praktische functies die tijd besparen bij het werken met documentatie.

Lokale preview met hot reload

Wanneer je documentatie schrijft in je IDE, is er geen noodzaak om de statische site constant handmatig te herbouwen. Het log4brains preview commando start een lokale server op basis van Next.js met Hot Reload. Je hebt het .md bestand opgeslagen — de browser werkt direct bij.

Interactieve CLI zonder starre beperkingen

Veel ADR-utilities vereisen strikte bestandsnummering zoals adr-0001.md, adr-0002.md. Dit wordt een nachtmerrie tijdens parallelle pull requests wanneer twee ontwikkelaars documenten met hetzelfde nummer maken.

Log4brains vertrouwt niet op starre nummering. Metadata (auteur, aanmaakdatum, status) wordt gelezen uit de tekst en git log. Templates kunnen worden aangepast aan je behoeften, hoewel het bewezen MADR-formaat standaard wordt gebruikt.

Een nieuw record maken ziet er eenvoudig uit:

log4brains adr new

Het commando zal interactief vragen naar de titel, een markdown-bestand maken van de template, en het in de projectstructuur plaatsen.

Monorepo-ondersteuning

Als het project is opgesplitst over meerdere packages, wordt documentatie vaak gescheiden gewenst. Log4brains kan globale top-level beslissingen en package-afhankelijke records aan binnen packages/service-name/docs/adr.

Hoe te beginnen

Alles begint met een paar commando's in de terminal. Je hebt Node.js LTS en Git nodig:

npm install -g log4brains
log4brains init

De setup-wizard stelt een paar basisvragen, maakt het .log4brains.yml configuratiebestand, voegt een template toe aan het project, en genereert je eerste welkomst-ADR.

De config blijkt compact te zijn:

project:
  name: My Service
  tz: Europe/Moscow
  adrFolder: ./docs/adr

Als je een monorepo hebt, kun je de structuur uitbreiden:

project:
  name: Core Platform
  tz: Europe/Moscow
  adrFolder: ./docs/adr
  packages:
    - name: auth-service
      path: ./packages/auth
      adrFolder: ./packages/auth/docs/adr
    - name: billing-service
      path: ./packages/billing
      adrFolder: ./packages/billing/docs/adr

Publiceren naar CI/CD

Het meest waardevolle deel is het extern deployen van de kennisbank zodat het team via een webinterface kan zoeken naar oplossingen. Omdat de build schone statische bestanden uitvoert, is het eenvoudig om naar GitHub Pages, GitLab Pages, of S3 te pushen.

Voorbeeld voor GitHub Actions:

name: Publish Log4brains
on:
  push:
    branches:
      - main
jobs:
  build-and-publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
          fetch-depth: 0 # обязательно, утилите нужна история git
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - name: Build
        run: |
          npm install -g log4brains
          log4brains build --basePath /${GITHUB_REPOSITORY#*/}/log4brains
      - name: Deploy
        uses: JamesIves/[email protected]
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages
          FOLDER: .log4brains/out
          TARGET_FOLDER: log4brains

Een belangrijk detail: let op fetch-depth: 0. De utility heeft absoluut de volledige commit-geschiedenis nodig om de werkelijke aanmaakdatums en auteurs van elk document te extraheren.

Wie heeft baat bij dit project

Log4brains is een goede match voor teams van 3-4 engineers of meer, waar mensen periodiek vragen stellen als "waarom kozen we voor deze bibliotheek/database/patroon".

De tool past goed in het code review proces. Je bespreekt architectuur in een pull request, voegt de code samen samen met het .md bestand in dezelfde commit. Documentatie leidt geen apart bestaan op vergeten wiki-pagina's — het wordt automatisch bijgewerkt tijdens deployment.

Als het project klein is en je werkt solo, kan de overhead van beslissingen documenteren onnodig lijken. Maar voor langlopende producten is dit een van de meest pijnloze manieren om beslissingscontext te behouden.