Skip to content

Architecture decision records

Why the Kokeb Labs standard is what it is. Each record is one decision in the Context / Decision / Consequences form, numbered in the order it was accepted. A record is never edited to change its decision; a new record supersedes it, and the old one gets a Superseded by ADR-NNNN status.

ADR Decision Status
0001 Drivers keep <chip>::Error and Result<T>; handlers map to kb::Status Accepted
0002 One lifecycle: I/O-free constructor, Initialize(), EnsureInitialized() Accepted, amended by 0021
0003 Drivers are templates on a CRTP port constrained by a concept Accepted
0004 No heap in drivers; none after start-up anywhere Accepted
0005 A shared kb-hal-common repository; board HALs live with their products Accepted
0006 FreeRTOS at 1 kHz everywhere; a delay waits at least the requested time Accepted
0007 Drivers pinned in kb-core to release tags; driver.yml, catalog/compat.yml and release trains Accepted
0008 One naming scheme, enforced by clang-tidy Accepted
0009 MIT for firmware and tooling; CERN-OHL-P-2.0 for hardware designs Accepted
0010 C++20 in every repository Accepted
0011 The root holds only required and first-read files; tool configuration in _config/; platform code only in examples/<platform>/ Accepted
0012 Drivers carry no brand: driver-<chip>, namespace <chip>, <chip>::<chip> Accepted
0013 kb-core is one monorepo with four targets and one version Accepted
0014 Chip-, MCU- and product-specific code each have one place Accepted
0015 Governance for one maintainer, open to contributors Accepted
0016 Virtual functions only at the three run-time boundaries Accepted
0017 Target code uses a named subset of the standard library Accepted
0018 Commit sdkconfig.defaults, never the generated sdkconfig Accepted
0019 Datasheets are referenced by exact revision, never committed Accepted
0020 Complexity limits and coverage floors per assurance level Accepted
0021 EnsureInitialized() is the one start-up entry point Accepted

Format

# ADR-NNNN: <decision as a short sentence>

- Status: Proposed | Accepted | Superseded by ADR-NNNN
- Date: YYYY-MM-DD

## Context

What forced a decision: the problem, the constraints, the options considered.

## Decision

What we do, stated as rules.

## Consequences

What gets better, what gets worse, and what has to change in which repositories.

A new record is added in the same PR as the change to the standard it explains. It is proposed in a PR to kokeb-labs/.github and stays open for comment for at least seven days unless it fixes a defect.

Where the decisions came from

Records 0001 to 0011 were accepted on 3 November 2026, after a read-only review of the code the standard grew from (drivers, libraries, HALs and products) against one checklist: API shape, port, errors, start-up, config, memory and threading, naming, build, tests and docs. The review found the repository shell, docs and CI already uniform, and the C++ contracts not: 5 error models, 6 start-up styles, about 8 spellings of the same port hooks, two handler families, drifting HALs and about 45 error types.

When the standard was set up for Kokeb Labs on 5 November 2026, those records were rewritten for the new org (names, licence, the kb-core layout), and records 0012 to 0015 were added. From then on, the rule at the top of this page applies.

The order of work:

  1. Write it down: this standard, the org clang configs, kokeb-labs/driver-template and ci-tools.
  2. kb-core skeleton: utils with kb::Status, rtos, interfaces with ToStatus(), each its own target, with the MCU gate and catalog/compat.yml.
  3. Drivers, in parallel, each released as driver-<chip> with its driver.yml, and each landing with its kb-core handler.
  4. kb-core handlers on one family, with shared adapter bases.
  5. kb-hal-common: the shared managers, facade base, bind interface, lints and an example board HAL; board-hal-template after it.
  6. The first release train, then the STM32 compile job and bind.