# Architecture

The protocol module has no Bluetooth or GUI dependencies. Tk exists only in
`controller/gui.py`, which `cli.py` imports after parsing arguments. Importing
the package or running `--help` does not load Tk or Bleak.

| Module | Responsibility |
| --- | --- |
| `protocol.py` | Packet encoding, stream framing, observed checksum variants |
| `commands.py` | Semantic command builders; no packet layout in Tk callbacks |
| `session.py` | Handshake, outgoing sequence numbers, connection readiness |
| `messages.py` | English command/reply descriptions and bounded activity history |
| `worker.py` | Thread lifecycle and event/command queues |
| `ble_link.py` | Bleak connection, notifications, characteristic writes |
| `link.py`, `transport.py` | Experimental RFCOMM and serial adapters |
| `gui.py` | Tk controls and event rendering |
| `discovery.py` | Read-only BLE discovery, unnamed model matching, and selectable labels |
| `cli.py`, `__main__.py` | Installed command and backwards-compatible module entry |
| `ble_probe.py`, `probe.py` | Endpoint diagnostics |
| `windows_bluetooth.py` | Experimental RFCOMM initialization |

## Session interface

Create one `Session` per connection. Write `session.start()` to begin. Pass
received chunks to `session.receive(chunk)` and write every returned `outgoing`
packet. `Update.frames` carries decoded packets; `became_ready` is emitted once
when the speaker acknowledges the link-complete request. Use
`session.command(payload)` for subsequent outgoing packets.

Both transports cross this same seam. The session owns framing and the state
machine, so fixes do not need to be repeated in separate Bluetooth loops.

A transport connection, a GATT write response, a Samsung packet acknowledgment,
and a speaker state report are distinct events. Only the link-complete ACK
makes the session ready. Speaker notifications have an independent sequence
counter and cannot substitute for that ACK.

## Threads and ownership

Tk runs on the main thread. Each connection worker owns its transport. BLE's
async event loop lives entirely within the worker thread. The GUI submits
payloads through a bounded command queue and consumes events through another
queue; workers never call Tk methods.

Discovery uses a separate bounded-duration worker and the same event queue.
It returns plain speaker records without opening a GATT connection. Tk maps a
selected label to its address; manual addresses remain supported. Scanning is
disabled while a connection is active so scans do not compete with BLE traffic.

BLE notifications enter a bounded async queue and can contain partial or
combined packets. The decoder retains framing state between notifications.
Queue overflow terminates the connection rather than silently losing framing.

Writes are spaced and never automatically retried. Retrying a volume or mute
key could perform the action twice. The GUI enables controls only after the
protocol handshake and disables them on connection closure.

## Testing

Protocol tests use captured byte fixtures independently of the outgoing
encoder. Session tests cover split replies, duplicate replies, and ACK matching.
Transport tests verify subscription order, write mode, disconnects, resource
cleanup, and readable error phases. Presentation tests verify the difference
between acknowledgment and a reported state. No test opens physical Bluetooth.