ADR Process

An ADR captures one decision that had real alternatives: the context, the options weighed, the choice, and its consequences — so future maintainers (including us, later) don’t re-litigate or accidentally reverse it blind.

Process

1. Copy 0000-template.md → NNNN-short-slug.md (next free number), status proposed.
2. Discuss in the PR; land it proposed if implementation must wait for evidence (spikes), or accepted when decided.
3. Accepted ADRs are immutable. Changing course = a new ADR with Supersedes: NNNN (and the old one gains Superseded-by).
4. Small reversible choices don’t need an ADR. Anything expensive to reverse — protocol shapes, licenses, platform commitments — does.

Index

ADR	Title	Status
0001	WebRTC + GStreamer for media transport	accepted
0002	Ubuntu 24.04 / GStreamer 1.24 baseline	superseded by 0022
0003	Polyglot monorepo	accepted
0004	Rust for the signaling server	accepted
0005	TS core + React bindings + demo split	accepted
0006	Desktop backend selection	accepted
0007	webrtcbin+FrameHub vs webrtcsink	proposed (M1 spike)
0008	DataChannel topology & reliability classes	accepted
0009	Privilege separation on the robot	proposed
0010	Devcontainer + compose + Xvfb robot-sim	accepted
0011	AGPL-3.0 open core + commercial licensing	accepted
0012	Agent in C++	accepted
0013	WebSocket signaling with a transport seam	accepted
0014	Astro + Starlight for the website	accepted
0015	Backend integration: unified contract, sidecar + managed twin	accepted
0016	SWUpdate as the OTA foundation	superseded by 0035
0017	libsoup-3 for agent networking	accepted
0018	Stream channel class (lossy binary frames)	accepted
0019	Agent process model — one process, two restartable planes	accepted
0020	Vendor camera support ships as separately packaged GStreamer plugins	accepted (desktop sentence superseded by 0021)
0021	Desktop backends are in-tree runtime modules in separate packages	accepted
0022	Baseline bump to Ubuntu 26.04 LTS / GStreamer 1.28	accepted
0023	The network tunnel is a virtual interface, not forwarded sockets	accepted
0024	fjarr-connect — a native operator client, data channels only	accepted
0025	Four encoder families behind one adapter, and what each owes CI	accepted
0026	Multicast crosses the tunnel, on the strength of its source — the destination rule made ROS 2 impossible	accepted
0027	The tunnel MTU is one SCTP chunk (1184) — every full-size packet at 1280 fragmented, and that is #28	accepted
0028	The desktop is reached through a session helper that hands the agent descriptors	accepted
0029	Robot files as a drive, through a WebDAV bridge in fjarr-connect	accepted
0030	Several operators on one robot’s tunnel, from a small pool of operator addresses	accepted
0031	Distribution: apt and containers first, from one build, with a system profile	accepted
0032	Ghost screens are forced connectors on free root connectors; virtual monitors stay per session	accepted
0033	The desktop is tested on headless mutter in CI and on shared lab machines at night (fjarr-lab)	accepted
0034	An X11 kiosk’s sound reaches the agent through its session program, narrowed to the speakers as on GNOME	accepted
0035	Fjarr orchestrates releases; the OS-slot engine is a narrow adapter per recipe (supersedes 0016)	accepted
0036	A release is one signed version pinning every component; company-held keys, a Fjarr-managed easy start	accepted
0037	Release content travels as resumable HTTPS chunks under a per-robot budget, not over WebRTC	accepted
0038	The reference peripheral handlers are MIT, an exception to ADR-0011, so customers can fork them	accepted
0039	The Ubuntu A/B image on x86 writes slots with systemd-sysupdate and boots through systemd-boot’s counting; RAUC with GRUB was the comparison	superseded by 0040
0040	The Ubuntu A/B image on x86 writes slots with SWUpdate and boots through EFI Boot Guard, one engine with the Jetson recipe	accepted
0041	Module E captures physical monitors as DMA-BUF and hands them to VA without a copy, shared memory as the fallback, because SHM streams freeze behind a directly scanned-out window	accepted