log4brains

An Architectural Decision (AD) is a software design choice addressing significant functional or non-functional requirements. An Architectural Decision Record (ADR) captures a single AD. A collection of these records forms a project's decision log.

Key characteristics and benefits of ADRs:

• Immutability: ADRs are immutable; only their status (e.g., becoming deprecated or superseded) should change. This allows teams to read the decision log chronologically to understand project history.
• Onboarding: Speeds up the onboarding process for new team members.
• Context Preservation: Prevents the blind acceptance or reversal of past decisions by providing the original rationale.
• Formalization: Formalizes the team's decision-making process.

Log4brains supports different project structures for managing Architecture Decision Records (ADRs):

Mono-repository (Multi-package)

Install Log4brains in the root folder. It can manage both "global ADRs" (located in the root docs/adr) and "package-specific ADRs" (located within individual package directories like packages/<package name>/docs/adr).

One repository per package

Currently, all ADRs must be stored in a central repository. You can organize them by creating subdirectories within the central ADR folder for each package (e.g., adr/package1/, adr/package2/).

When writing new React components in the Log4brains codebase, avoid using the React.FC (or React.SFC) type. These types are considered unnecessary and introduce downsides, such as implicitly adding children props and failing to support generic types on children.

Instead, define your component as a standard function and explicitly include children in your props type definition if needed.

/* Avoid this: */
type BadProps = { text: string };
const BadComponent: FC<BadProps> = ({ text, children }) => (
  <div>
    <div>{text}</div>
    {children}
  </div>
);

/* Do this instead: */
type GoodProps = { text: string; children?: React.ReactNode };
const GoodComponent = ({ text, children }: GoodProps) => (
  <div>
    <div>{text}</div>
    {children}
  </div>
);

Log4brains identifies Architecture Decision Records (ADRs) by their filename slug (the filename without the extension) rather than an incremental number. To ensure uniqueness and prevent git merge conflicts, use the following filename format:

YYYYMMDD-adr-title.md

Where YYYYMMDD is the date of creation. This format allows files to remain correctly sorted in IDEs while avoiding the collisions common with incremental numbering.

In Log4brains, Markdown parsing is treated as part of the core domain logic rather than a technical infrastructure detail. This design choice allows the system to perform 'smart' parsing of ADRs (Architecture Decision Records) without requiring a rigid, predefined structure.

Because parsing is part of the domain, the logic used to interpret Markdown content is central to the application's business rules and is subject to comprehensive testing. Note that this means the core logic is tightly coupled to the Markdown format, making it difficult to switch to a different document format (like JSON or AsciiDoc) in the future.

The Log4brains core library handles the sorting of ADRs. When displaying or processing records, they are sorted according to the following priority rules:

1. Date field: The date specified within the markdown file's frontmatter (if present).
2. Git creation date: The date the file was created in Git (this does not follow renames).
3. File creation date: The filesystem creation date if no versioning information is available.
4. Slug: The filename slug (alphabetical/chronological based on the date prefix).

Log4brains operates in two distinct modes to support the lifecycle of Architecture Decision Records (ADRs):

1. Edit Mode: Used by developers to edit ADRs via a web UI or directly in an IDE. This mode is served locally and supports live-reloading when markdown files are modified. It is typically started with npm run log4brains.
2. Build Mode: Used to generate a static site from the ADRs, ready for deployment to hosting services like GitHub Pages. This mode is typically executed by a CI/CD pipeline using npm run log4brains-build.

The project uses Next.js as the underlying framework to ensure code reusability between these two modes and to provide high extensibility via TypeScript.

To start using Log4brains in your project, install the CLI globally and run the initialization command in your project's root directory. The init command will guide you through configuration, create necessary template files, and generate your first ADR.

Note: If you want to use the latest beta version, use log4brains@beta during installation.

npm install -g log4brains
log4brains init

Before installing Log4brains, ensure your environment meets the following requirements:

• Node.js: An active or maintenance LTS version. Versions outside this range are not guaranteed to work; the 'current' version is supported on a best-effort basis.
• Package Manager: NPM or Yarn.
• Git: Required for version control integration.

Log4brains is designed to work with any project type, not just JavaScript/TypeScript projects, though it requires Node and NPM to be installed globally to run.