Log4brains

Log4brains is a docs-as-code knowledge base for your development and infrastructure projects. It enables you to log Architecture Decision Records (ADR) right from your IDE and to publish them automatically as a static website.

By logging your decisions chronologically, you will be able to:

Understand past technical decisions and their context
Take new decisions with confidence
Always have a up-to-date technical documentation and training material available
Onboard new developers quicker
Set up a collaborative decision process thanks to pull requests

<details> <summary>Features</summary>

Docs-as-code: ADRs are written in markdown, stored in your git repository, close to your code
Local preview with Hot Reload
Interactive ADR creation from the CLI
Static site generation to publish to GitHub/GitLab Pages or S3
Timeline menu
Searchable
ADR metadata automatically guessed from its raw text and git logs
No enforced markdown structure: you are free to write however you want
No required file numbering schema (i.e., adr-0001.md, adr-0002.md...): avoids git merge issues
Customizable template (default: MADR)
Multi-package projects support (mono or multi repo): notion of global and package-specific ADRs

Coming soon:

Local images and diagrams support
RSS feed to be notified of new ADRs
Decision backlog
@adr annotation to include code references in ADRs
ADR creation/edition from the UI
Create a new GitHub/GitLab issue from the UI
... let's suggest a new feature if you have other needs!

</details> <a href="https://www.youtube.com/watch?v=HDEwOCn9T0w" title="Click to watch the full screencast"> <img src="https://github.com/thomvaill/log4brains/raw/develop/docs/demo.gif" alt="Log4brains demo" width="838" /> </a> <a href="https://www.youtube.com/watch?v=HDEwOCn9T0w">🎞️ Watch the full screencast</a> - <a href="https://thomvaill.github.io/log4brains/adr/">⚡ See an example (Log4brains' own ADRs)</a>

Table of contents

🚀 Getting started
🤔 What is an ADR and why should you use them
📨 CI/CD configuration examples
❓ FAQ
📣 Your feedback is welcome!
Contributing
Acknowledgments
License

🚀 Getting started

We recommend storing your Architecture Decision Records (ADR) next to the source code of your project, in the same git repository, to keep them in sync.

To get started, run these commands inside your project root folder:

npm install -g log4brains # if you want to install the latest beta version, run `npm install -g log4brains@beta` instead
log4brains init

It will ask you several questions to get Log4brains properly configured. It will also create the required template files and your first ADR as well. Then, you can start the web UI to preview your knowledge base locally:

log4brains preview

In this mode, the Hot Reload feature is enabled: any change you make to a markdown file from your IDE is applied live.

To create a new ADR from your template, run this command:

log4brains adr new

Get all the available commands and options by running log4brains --help.

Finally, do not forget to set up your CI/CD pipeline to automatically publish your knowledge base on a static website service like GitHub/GitLab Pages or S3.

🤔 What is an ADR and why should you use them

The term ADR became popular in 2011 with Michael Nygard's article: documenting architecture decisions. He aimed to reconcile Agile methods with software documentation by creating a very concise template to record functional or non-functional "architecturally significant" decisions in a lightweight format like markdown. The original template had only a few parts:

Title: Which sums up the solved problem and its solution
Context: Probably the essential part, which describes "the forces at play, including technological, political, social, and project local"
Decision
Status: Proposed, accepted, deprecated, superseded...
Consequences: The positive and negative ones for the future of the project

There are other ADR templates like Y-Statements or MADR, which is the default one that is shipped with Log4brains.

As you can guess from the template above, an ADR is immutable. Only its status can change. Thanks to this, your documentation is never out-of-date! Yes, an ADR can be deprecated or superseded by another one, but it was at least true one day! And even if it's not the case anymore, it is still a precious piece of information.

This leads us to the main goals of this methodology:

Avoid blind acceptance and blind reversal when you face past decisions
Speed up the onboarding of new developers on a project
Formalize a collaborative decision-making process

To learn more on this topic, I recommend you to read these great resources:

Documenting architecture decisions, by Michael Nygard
ADR GitHub organization, home of the MADR template, by Oliver Kopp and Olaf Zimmermann
Collection of ADR templates and examples by Joel Parker Henderson

📨 CI/CD configuration examples

Log4brains lets you publish automatically your knowledge base on the static hosting service of your choice, thanks to the log4brains-web build command. Here are some configuration examples for the most common hosting services / CI runners.

<details> <summary>Publish to GitHub Pages with GitHub Actions</summary>

First, create .github/workflows/publish-log4brains.yml and adapt it to your case:

name: Publish Log4brains
on:
  push:
    branches:
      - main
jobs:
  build-and-publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false # required by JamesIves/github-pages-deploy-action
          fetch-depth: 0 # required by Log4brains to work correctly (needs the whole Git history)
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - name: Install and Build Log4brains
        run: |
          npm install -g log4brains
          log4brains build --basePath /${GITHUB_REPOSITORY#*/}/log4brains
      - name: Deploy
        uses: JamesIves/github-pages-deploy-action@3.7.1
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages
          FOLDER: .log4brains/out
          TARGET_FOLDER: log4brains

After the first run, this workflow will create a gh-pages branch in your repository containing the generated static files to serve. Then, we have to tell GitHub that we don't want to use Jekyll, otherwise, you will get a 404 error:

git checkout gh-pages
touch .nojekyll
git add .nojekyll
git commit -m "Add .nojekyll for Log4brains"
git push

Finally, you can enable your GitHub page:

On GitHub, go to Settings > GitHub Pages
Select the gh-pages branch as the "Source"
Then, select the / (root) folder

You should now be able to see your knowledge base at https://<username>.github.io/<repository>/log4brains/. It will be re-built and published every time you push on main.

</details> <details> <summary>Publish to GitLab Pages with GitLab CI</summary>

Create your .gitlab-ci.yml and adapt it to your case:

image: node:lts-alpine
pages:
  stage: deploy
  variables:
    GIT_DEPTH: 0 # required by Log4brains to work correctly (needs the whole Git history)
  script:
    - mkdir -p public
    - npm install -g --unsafe-perm log4brains
    - log4brains build --basePath /$CI_PROJECT_NAME/log4brains --out public/log4brains

Log4brains

Install / Use

README

Log4brains

Table of contents

🚀 Getting started

🤔 What is an ADR and why should you use them

📨 CI/CD configuration examples