Architecture Decision Records
The design forks: where more than one option was viable, the reasoning that picked one, and what was accepted in doing so. Each record is the durable answer to “why is it built this way, and what did we turn down?”
Read this index before reopening a question. If a record already answers it, the answer stands until a new record changes it. That is the point of the section: a decision argued once should not have to be argued again from memory.
Records are point-in-time. They say what was decided and why on the day it was decided, and they are not rewritten afterward. The architecture and reference pages are kept current; the decision log is kept honest.
When a decision changes
Two different things happen to an old record, and they are not the same:
- Extended. The record was right but incomplete: building the thing
exposed a question it never asked. A new record answers that question, the
old one stays
Accepted, and each links to the other. - Superseded. Acting on the record would now be a mistake. A new record
replaces it, the old one is marked
Supersededand links forward.
The test is whether the earlier record is still safe to act on. If yes, extend it. If not, supersede it.
Format
| Field | Purpose |
|---|---|
| Status | Proposed, Accepted, Superseded or Deprecated |
| Date | The day the decision was made, not the day it was written up |
| Context | The situation and the goals that forced a choice |
| Options considered | The viable alternatives, each with what it would cost |
| Decision | What was chosen |
| Consequences | What it commits us to, good and bad |
- Records are numbered in the order they are opened and never renumbered. The number is claimed when the question is written down, not when it is answered.
- A record sits at
Proposedwhile it rests on something not yet proven: a protocol not yet tried against the real player, a limit not yet measured. The evidence is added to the record when it arrives, and the status moves with it. - Some early records are backfilled: the decision was made and argued in a README before this section existed. They carry the date of the decision and say that they are backfilled.
EdS records and Deevnet records
EdS runs on Deevnet IoTaaS, which keeps its own ADRs, change records and incidents under the same names. To keep the two apart:
- A bare ADR-0006, CHG-0001 or INC-0001 anywhere in this repository means an EdS record, on this site.
- A Deevnet IoTaaS record is always written Deevnet ADR-0012, and links to deevnet-docs.
Records
| ADR | Date | Decision | Status |
|---|---|---|---|
| 0001 | 2026-09-07 | The stand renders effects locally and never receives frames | Accepted |
| 0002 | 2026-09-07 | Gamma belongs to the firmware, not the wire | Accepted |
| 0003 | 2026-09-07 | The MQTT broker is Deevnet IoTaaS’s, not a tenant VM | Accepted |
| 0004 | 2026-10-10 | Firmware secrets are NVS-only, and the broker’s CA is provisioned | Accepted |
| 0005 | 2026-10-10 | A device reports key events over MQTT, not its serial log | Accepted |
| 0006 | 2026-10-10 | Now playing is a bus of small drivers behind one contract | Accepted |
| 0007 | 2026-10-10 | Drivers are portable Go, in one agent binary | Accepted |
| 0008 | 2026-10-10 | nowplayd picks the current track and guarantees title, album and art | Accepted |
| 0009 | 2026-10-10 | lightd takes covers from a topic as a second input | Accepted |
| 0010 | 2026-10-10 | Home-LAN drivers reach the broker through a dual-homed mobile Pi | Accepted |
| 0011 | 2026-10-10 | iTunes is read by remote pairing, the way the phone remote does it | Accepted |
| 0012 | 2026-10-10 | Spotify is read from the account, through the Web API | Accepted |
| 0013 | 2026-10-10 | MusicBee is read through the MusicBee Remote plugin’s protocol | Proposed |
| 0014 | 2026-10-10 | TIDAL is read through Last.fm, because nothing better is offered | Proposed |
| 0015 | 2026-10-10 | EdS builds its own Pi images, on Deevnet IoTaaS’s base; a relay is an agent Pi with a second leg | Accepted |
| 0016 | 2026-10-11 | A source can be reported without its cover, and Spotify is: known, and not lit | Accepted |
| 0017 | 2026-10-11 | An agent Pi is a registered device, and reports its events like one | Accepted |
| 0018 | 2026-10-11 | EdS has a console of its own, fed from the bus, and it only looks | Accepted |
| 0019 | 2026-10-11 | An album can have a look of its own, named on the music side and drawn on the light side | Proposed |
| 0020 | 2026-10-11 | A touch screen shows the cover and can change what plays, by asking nowplayd | Proposed |
| 0021 | 2026-10-11 | The turntable is identified by listening, with a recognizer that can be replaced | Proposed |
| 0022 | 2026-10-12 | For a source that plays the owner’s records, the owner’s collection names the record | Proposed |
| 0023 | 2026-10-12 | A source’s equipment can say it is on, and a source that is on holds the stand | Proposed |
| 0024 | 2026-10-12 | A track left paused is not playing for ever, and a room with nothing playing is dim | Proposed |
| 0025 | 2026-10-12 | The current track says when there is nothing a controller could do | Proposed |
| 0026 | 2026-10-12 | A gap between tracks is listened for, and a silent turntable is idle in twenty seconds | Proposed |
| 0027 | 2026-10-12 | What EdS asks of other people’s services is counted, a minute at a time, and nowplayd writes its counts to the log store itself | Proposed |
| 0028 | 2026-10-13 | The stand is lit for records only, and is dim only while the turntable is on | Proposed |
| 0029 | 2026-10-13 | The stand starts dark, and says in red blinks how far it got | Proposed |
| 0030 | 2026-10-13 | One piece of music can have a look of its own, shown whatever plays it, and the stand learns to scan | Proposed |
| 0031 | 2026-10-13 | Spotify is reported with its cover, and treated as iTunes is | Proposed |
| 0032 | 2026-10-13 | The Spotify driver carries out commands, with a wider authorization, for what is playing here | Proposed |
| 0033 | 2026-10-13 | The whole back end can run on one Pi, as an image built on Deevnet’s take-home one | Proposed |
| 0034 | 2026-10-16 | Presence is heard, not remembered: everything says it is there every thirty seconds | Proposed |
| 0035 | 2026-10-16 | Firmware is updated through the broker, and a build that cannot reach it is undone | Accepted |
| 0036 | 2026-10-17 | The cover screen sleeps when nothing has played for five minutes, and wakes for music | Accepted |
| 0037 | 2026-10-18 | The secrets nothing else can issue are kept encrypted in the repository, with sops and age | Proposed |
| 0038 | 2026-10-19 | The turntable’s album is the one the track is on, and the original one, not a time since the last | Proposed |
| 0039 | 2026-10-19 | The console can light the stand for every source, a retained setting that stays until switched back | Proposed |
| 0040 | 2026-10-23 | A request can name an album to play, and iTunes plays it from its own library | Proposed |
| 0041 | 2026-10-24 | An artist’s first album is their first studio album, counted in MusicBrainz | Proposed |
| 0042 | 2026-10-24 | A spoken request is sent whole to the workload, written down there, and made a command | Proposed |
| 0043 | 2026-10-24 | The reSpeaker runs firmware of EdS’s own, and sends a request when its button is held, then when it hears its name | Proposed |
| 0044 | 2026-10-24 | The music is turned down while a request is heard, and comes back by itself | Proposed |
| 0045 | 2026-10-24 | An artist’s Nth album, when the library does not have it, is the next of theirs it does | Proposed |
| 0046 | 2026-10-24 | Requests are matched against the owner’s library, as its XML lists it | Proposed |
| 0047 | 2026-10-24 | voiced asks eds-inventory for the owner’s albums, in place of its own index | Accepted |
| 0048 | 2026-10-25 | The turntable is heard on both channels, and one gone silent is said on the console | Proposed |
| 0049 | 2026-10-26 | A device holds two sites’ settings, and is told which to use by a message | Proposed |
| 0050 | 2026-10-27 | How each track’s album and cover were found is written down, one line a track, and sent to the log store | Proposed |
| 0051 | 2026-10-28 | Spotify is switched on and off from the console, a retained setting the agent obeys; off asks Spotify nothing | Accepted |
| 0052 | 2026-10-28 | Each Pi’s iTunes pairing is kept, encrypted with sops, and a card written again starts paired | Accepted |
| 0053 | 2026-10-28 | A home Pi opens a Wi-Fi leg onto the home LAN for the van, for a while, when asked from inside; SSH only | Proposed |