# 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**.