Architecture Decisions

ADRs record project-wide choices that are difficult to reverse or that intentionally constrain future work. Routine implementation details, provider-specific behaviour and bug fixes do not need one.

Use 0000-template.md. Keep an ADR to the context that explains why the choice exists, one clear decision, and the consequences that matter later. Do not transcribe implementation code, protocol schemas, issue discussions or exhaustive option lists.

Host and platform

• 0001 - Profiles are JSON files, written durably and recovered on read
• 0002 - Data roots and build channels
• 0006 - A Tauri bootstrapper is the installed entry point
• 0015 - Installation and update delivery are bounded by each platform's ownership model
• 0024 - The log files are the log viewer's source of truth, and their format is a contract
• 0078 - The macOS host pumps a CoreFoundation run loop on the main thread

Networking, trust and secrets

• 0003 - Loopback trust, token scopes, and device identity
• 0030 - Android USB connections terminate on the public listener
• 0040 - Public listeners are a resolved endpoint set, secured by a per-installation local CA
• 0047 - Secrets at rest, encrypted backups, and a staged boot-time restore
• 0054 - The Macro Deck Connect session is a host-owned refresh credential
• 0062 - UI realtime is a ticketed JSON WebSocket, and it never blocks on a provider
• 0085 - The connect link is a binary record written as decimal digits
• 0086 - The host proves its identity to the companion app
• 0087 - The Companion license is a signed bearer token the host keeps and hands out

Decks, flows and content

• 0004 - Capabilities are optional interfaces, discovered by registry
• 0009 - Portable archives, and migration from other applications
• 0010 - One flow engine behind widget triggers, events and automations
• 0012 - Scripts are reusable flows with declared inputs and an owning widget
• 0022 - Icon identity is a locally computed hash, and a widget icon is a typed provider reference
• 0056 - Widget state is addressed by stable state id
• 0081 - Variables come from one provider catalog and carry attributes and a write capability

Plugins

• 0026 - The plugin boundary is a versioned JSON protocol with a DI-first .NET SDK over it
• 0028 - Plugin credentials are launch tokens, and development plugins pair interactively
• 0029 - Plugins are ZIP artifacts, installed atomically and supervised by the host
• 0037 - SDK deprecation is declared metadata, confirmed by a build-time usage manifest
• 0042 - Signing is one shared library anchored to a pinned root, and the Portal signs Store artifacts
• 0044 - The host enforces trust as a verdict, and the Store adds the signed registry chain
• 0088 - Plugins run on the .NET runtime bundled with the host
• 0089 - A development build can temporarily take over an installed plugin
• 0090 - Invited testers install unreviewed test builds

Macro Deck UI

• 0038 - The UI model is a surface-agnostic versioned package, authored through a reactive DSL
• 0041 - The web client's service worker caches the app shell and nothing else
• 0050 - UI sessions are host-brokered, and a configuration tree renders a transaction it does not own
• 0057 - Localized text is a reference resolved by whoever renders it
• 0064 - Components are a registry over two namespaces
• 0065 - The component profile's authoring contracts
• 0068 - Device sessions push full surface snapshots, and layouts are provider-registered descriptors
• 0075 - Widget types, folder views and modals are provider-registered and served through one provider