Skip to content

Architecture Decision Records

Decisions that shaped this module and are expensive to re-litigate. An ADR is written when a choice is architectural, contested, or would otherwise look like an oversight to the next reader — including choices to not do something.

ADR Decision Status
0001 Matter wire-protocol design rules from chip-tool bring-up accepted
0002 A testable gate + per-opcode seam in handleIMOpcode accepted
0003 Sigma resumption extraction: already satisfied (finding corrected) accepted, no code change
0004 Groups stays a stub — a deliberate, matter.js-conformant divergence superseded by 0009
0005 Defer the Bridge CommissioningSession / IMEngine facade split accepted, deferred with a plan
0006 Cohesive sub-helpers out of handleSubscribeRequest accepted
0007 Hermetic per-type send/receive suite against chip-tool accepted
0008 Persist server subscriptions and re-establish them after restart, with a CASE initiator scoped to that alone accepted
0009 A real Groups server and group message reception, with membership as stack state; Groupcast deferred to 0010 accepted
0010 Groupcast (Listener, PerGroup) and the AccessControl Auxiliary ACL on the root, on the ADR 0009 group state; no Sender accepted
0011 Certifiability is a goal, certification is not pursued; certification families are the yardstick, every exclusion is classified, PICS are honest, tests replace manual device testing accepted
0012 A real ScenesManagement server on the bridged lights, as matter.js builds it; RemainingCapacity bounded by the shared table as chip does accepted
0013 Cluster definitions generated from the matter.js model (one package per cluster under cluster/spec/), a small runtime that derives lists, privileges, write checks and codecs from them; servers keep only the host port and the rules accepted
0014 Attribute transitions run in the module (cluster/transition, matter.js Transitions.ts), optional per endpoint; a host whose device ramps natively keeps the hand-off path accepted
0015 The CHIP data model cross-check reads connectedhomeip's data_model/<version> from a checkout at test time and commits nothing derived from it (the CSA notice forbids publishing or deriving); CI provides the checkout accepted
0016 Assembled topologies are validated against their device types — a port of matter.js's DeviceTypeConformance and its service's modes (warn by default, strict, off) — on every bridge assembly, with a structured verdict for the host accepted
0017 A generated default cluster server in cluster/spec, so a cluster without matter.js logic costs its definition and a host port; the hand-written schema tables are generated too accepted, implemented in #40
0018 A device layer device/ generated from the device-type model and a node/ facade — the port of matter.js devices/, endpoints/ and ServerNode; the existing contract/ level stays beneath it, foreign-source projection stays outside proposed (concept phase 4)
0019 TCP (full large-payload path), BDX and the complete OTA Software Update Requestor enter the scope in wave 5; DiagnosticLogs stays without BDX (matter.js has none); the OTA Provider stays out — both exclusions superseded by 0021. Accepted
0020 The commissioner and controller role enters the scope as controller/, a sibling of bridge/, ported from matter.js in six stages; on-network only; the responder side and contract/ are unchanged; supersedes the no-controller non-goal (CLAUDE.md, comparison §Non-goals 1, ADR 0008's exception, concept v1 §F.1) accepted 2026-10-13 (concept v2 phase 7)
0021 The OTA Software Update Provider (own OtaProvider endpoint, host ports for image source, consent and apply policy, the BDX sender roles) and DiagnosticLogs over BDX (chip as the reference: matter.js has no DiagnosticLogs server) enter the scope; supersedes ADR 0019's two exclusions; in-repo device-to-device proofs; the harness image pin stays accepted 2026-10-14 (concept v2 phase 8)
0022 The fifteen media and content clusters (fourteen through the standard server behind typed host ports in cluster/media, Messages core-held for its fabric-scoped list) and the three media device types enter the scope; the reference daemon's player and content-app endpoints carry chip's media families; CastingVideoClient stays out; the ecosystem proof waits for phase 5 accepted 2026-10-14 (concept v2 phase 9)
0023 Apache License 2.0 from the next release (matter.js's and connectedhomeip's licence, with the patent grant); the released MIT versions stay MIT; a contributor licence agreement (CLA.md) so the module can be licensed as a whole later; dependencies stay permissive accepted 2026-10-15
0024 The commissioner commissions over BLE (BTP in transport/btp, the controller/ble seam, BlueZ over D-Bus in the separate module ble/bluez, Linux only, no cgo) and provisions Wi-Fi or Thread credentials; the device side stays without Bluetooth accepted 2026-10-16 (concept v3)

Provenance

ADRs 0001–0007 were recorded in OpenCCU-Loom while the Matter stack still lived there as internal/north/matter/, and moved here with the stack. They were renumbered into this module's own sequence; each file names the OpenCCU-Loom number it carried. ADR 0008 onwards were written here. Decisions that are about projecting a device model onto Matter — which HomeMatic device becomes which device type, how many endpoints a physical device gets — stayed there, because that is the host's decision, not this module's.