docs: add architecture documentation

.claude-context/01-architecture.md

@@ -0,0 +1,59 @@
+# Architecture
+
+## Module Structure
+
+```
+lego-dimensions-reader/
+├── lego_dimensions_reader.py   # Core portal communication
+├── moonlight_integration.py    # Video player integration
+├── character_database.json     # Character/vehicle ID mappings
+├── requirements.txt            # Python dependencies
+└── .claude-context/            # Session history
+```
+
+## Core Classes
+
+### `LegoDimensionsReader`
+Event-driven portal interface with callbacks:
+- `on_tag_insert(TagInfo)` — fired when disc placed
+- `on_tag_remove(TagInfo)` — fired when disc removed
+- `on_connect()` / `on_disconnect()` — portal connection state
+- `on_error(Exception)` — error handling
+
+### `TagInfo` (dataclass)
+- `uid: bytes` — 7-byte NFC tag UID
+- `pad: Pad` — CENTER, LEFT, or RIGHT
+- `event: TagEvent` — INSERTED or REMOVED
+- `character_id: Optional[int]` — decrypted ID (if available)
+- `character_name: Optional[str]` — looked up from database
+
+## USB Protocol
+
+**Endpoints:**
+- OUT: 0x01 — commands to portal
+- IN: 0x81 — events from portal (32-byte interrupt packets)
+
+**Command structure:**
+```
+[0x55, length, cmd_type, cmd_id, ...payload, checksum, ...padding]
+```
+
+**Tag event packet (0x56):**
+```
+[0x56, ??, pad_num, ??, ??, action, uid[0:7], ...]
+```
+
+## Platform Support
+
+| Platform | Backend | Driver Setup |
+|----------|---------|--------------|
+| Linux | libusb (native) | udev rules for non-root access |
+| Windows | libusb-win32 via WinUSB | Zadig to replace HID driver |
+| macOS | libusb (homebrew) | Should work, untested |
+
+## Dependencies
+- `pyusb` — USB device communication
+- `libusb` (on Windows) — provides backend DLL
+
+---
+*Last updated: 2026-09-23*