lucky-cat/docs/adr/0003-lan-user-configuration.md

ADR 0003: LAN User Configuration Transport and Lifecycle

Status

Accepted

Context

The browser-based birth-profile workflow previously depended on Web Bluetooth and an externally hosted page. It must instead run from the ESP32 and be reachable by devices on the same local network.

Decision

• Remove the BLE provisioning transport and Web Bluetooth utility.
• Retain the existing TQ-EYE SoftAP portal only for initial Wi-Fi setup.
• platform owns a bounded raw HTTP server contract, socket worker lifecycle, mDNS publication, request limits, and deterministic stop fallback.
• domain owns the embedded page, /api/profile and /api/fortune semantics, validation, persistence calls, and mapping to platform HTTP types.
• control_plane starts the domain web service while STA is connected, stops it on disconnect or runtime shutdown, and retries start after reconnect.
• The service is plain HTTP without authentication and is intended only for a trusted LAN. It is advertised as tq-cat.local and logs the DHCP address.

Consequences

• Browsers no longer need Web Bluetooth support or a separately hosted page.
• User information is readable and writable by any client on the same LAN.
• SoftAP and LAN pages remain separate, so the vendored Wi-Fi portal does not need project-specific user-profile semantics.
• A future authentication or HTTPS requirement needs a separate decision and credential lifecycle design.