Skip to content

Architecture Decision Records

Architecture Decision Records (ADRs) capture the consequential design choices behind OpenCCU-Loom — the decision, its context, and its consequences — so future readers can understand why the code looks the way it does.

Who this page is for

Contributors and developers who need the rationale behind a design choice. ADRs are immutable once landed: a superseded decision gets a new ADR rather than an edit to the old one.

The table below catalogues every ADR. Each links to the record on GitHub.

# Title Summary
0001 License: MIT The source is licensed MIT.
0002 Multi-CCU as a first-class feature One daemon serves many CCUs, scoped by central_name, from 0.1.0.
0003 Embed openccu-data metadata artifacts Translations, easymodes, and profiles are embedded from openccu-data.
0004 Python decorators ↔ Go cross-cutting How decorator-based concerns from the Python reference map to Go.
0005 Visibility as outbound filter Visibility is applied as an outbound filter on REST and MQTT.
0006 Naming conventions for REST + MQTT Shared naming rules across the REST and MQTT surfaces.
0007 Strong model: Source interface A single Source interface backs both reads and writes.
0008 AggregatedState default-flip Flips the AggregatedState default and removes the legacy path.
0009 Service-method command topics Service-method command topics in HA Discovery.
0010 Discovery payload from the model HA-Discovery payload construction moves into the model.
0011 MQTT topic & payload architecture The topic and payload structure for the MQTT plane.
0012 Matter bridge: pure-Go The Matter bridge is implemented in pure Go, no CGo SDK.
0013 Matter wire-protocol design rules Wire-protocol rules learned from chip-tool commissioning bring-up.
0014 Parameter ignore / un-ignore mechanics How parameters are ignored and un-ignored.
0015 Split Ignored from NoCreate Separates Ignored from NoCreate in DataPointUsage.
0016 Custom-DP-aware UI rendering UI rendering is aware of custom data points.
0017 Logging and diagnostics The logging and diagnostics model.
0018 Health tracker parity The health tracker mirrors aiohomematic.
0019 Persistent VALUES cache A persistent VALUES cache with a wire-DP lifecycle.
0020 External-client wire contract The wire contract external clients depend on.
0021 mDNS self-advertisement mDNS self-advertisement for LAN auto-discovery.
0022 WebSocket resume cursor + kind The WebSocket resume cursor and envelope kind discriminator.
0023 HmIP-Wired is a ProductGroup HmIP-Wired is modeled as a ProductGroup, not an interface.
0024 Instance vs CCU identity Daemon-instance vs CCU identity, and the two interface ids.
0025 MCP server as a north-bound adapter The MCP server is a north-bound adapter.
0026 MCP dev-mode A build-tag-gated MCP introspection surface.
0027 Encrypt config secrets at rest Config secrets are encrypted at rest.