Tag albums service: album lookup API for Home Assistant and assignment web page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-09-25 16:56:21 +00:00
co-authored by Claude Opus 5.5
commit eaf77dd0de
20 changed files with 1358 additions and 0 deletions
+35
View File
@@ -0,0 +1,35 @@
# Tag albums
A small service that tells Home Assistant which album to play for a scanned RFID card, and a web page to assign albums to new cards.
## Language
**Tag**:
A physical RFID card, identified by the ID the reader reports (e.g. `53-13-0B-2A-34-00-01`). Nothing is ever written to it.
_Avoid_: card (in code), NFC tag
**Assignment**:
The link from one **Tag** to one album (artist + album) in the music library.
_Avoid_: encoding, mapping, tag map
**Unassigned tag**:
A **Tag** the service has seen scanned but that has no **Assignment** yet.
_Avoid_: unknown tag, new tag
**Scan**:
One report that a **Tag** was placed on a reader, as relayed by Home Assistant. A **Scan** of an **Unassigned tag** is how the service learns about it.
## Relationships
- A **Tag** has zero or one **Assignment**
- An **Assignment** points to exactly one album
- Every **Scan** is of exactly one **Tag**; the first **Scan** of an unseen **Tag** creates it as an **Unassigned tag**
## Example dialogue
> **Dev:** "Someone put a new card on the reader — do we need to encode it?"
> **Domain expert:** "It's an **Unassigned tag** now; open the page and give it an **Assignment**. Nothing gets written to the card."
## Flagged ambiguities
- "Encode the tags" meant assigning an album to a **Tag**, not writing data onto it. Resolved: **Assignment**.