feat: Add persistent device database for offline/degraded mode operation

[maxfield-allison]

Summary

This PR implements the persistent device database foundation we discussed in #76 and #537. It enables govee2mqtt to gracefully degrade to LAN-only mode when Govee APIs are unavailable, rather than crashing.

Problem

When all Govee APIs fail (authentication error, rate limiting, abnormal activity detection, or network issues) and the SQLite cache is empty or cleared, govee2mqtt crashes with the ISSUE_76_EXPLANATION error. This prevents LAN control even though LAN devices are reachable on the local network.

Solution

A persistent JSON device database that:

• Stores device metadata (id, sku, name, room) learned from Platform and Undoc APIs
• Survives cache clears and container restarts (separate from SQLite cache)
• Enables graceful degradation to LAN-only mode
• Preserves device names for Home Assistant entity stability
• Human-editable JSON format as you requested

Implementation Details

Following the architecture you outlined in #537:

Storage (src/device_database.rs)

#[derive(Serialize, Deserialize)]
pub struct DeviceDatabase {
    pub version: u32,
    pub devices: BTreeMap<String, PersistedDevice>,
}

• Location: /data/devices.json (HA addon) or ~/.cache/govee2mqtt/devices.json
• Atomic writes: temp file + rename pattern for crash safety
• User override fields: user_name and user_room for future editing capability

Startup Flow (src/commands/serve.rs)

1. Detect startup mode: Fresh, Upgrade, or Normal
2. Load existing device database
3. Attempt API discovery
4. On API failure with cached data → continue with warnings
5. Populate in-memory state from database in degraded mode
6. Start LAN discovery

Fallback Logic

• API succeeds → database updated with latest metadata
• API fails + database exists → use cached data, log warnings
• API fails + no database → fail with ISSUE_76 (unchanged behavior for fresh installs)

Changes

File	Changes
src/device_database.rs	New - Device database implementation
src/commands/serve.rs	Startup integration, fallback logic
src/service/device.rs	cached_name/cached_room fields
src/service/state.rs	Device database handle in state
src/main.rs	Module declaration
Cargo.toml	Dependencies (chrono, dirs, tempfile)

Testing

Tested on a Docker Swarm deployment with 7 Govee devices:

Scenario	Result
Valid credentials	✅ Database populated, all devices work
Invalid API key + SQLite cache exists	✅ Cache returns stale data, service runs
Invalid credentials + NO SQLite cache	✅ Loads from devices.json, LAN control works
Fresh install + no credentials	✅ Fails as expected (no data to use)

Key Test Output (Scenario 3)

Platform API discovery failed: status 401 Unauthorized
Continuing with 7 cached devices from persistent database
Undoc API discovery failed: Incorrect user name or password
Continuing with 7 cached devices from persistent database
Populating device state from persistent database...
Loaded 7 devices into memory from persistent database
Running in degraded mode - device metadata may be stale
LAN-capable devices should still be controllable
Starting LAN discovery
...
Using LAN API to set Frame Front Accent power state

Non-Breaking

• ✅ All existing tests pass (cargo test)
• ✅ Existing SQLite cache behavior unchanged
• ✅ Database is purely an additive resilience layer
• ✅ Fresh installs without API access still fail appropriately

Future Work (Not in this PR)

This is intentionally a focused foundational PR. Future enhancements could include:

1. Entity ID stability - Lock entity names on first registration
2. Web UI management - View/edit device database from the web interface
3. Per-device API preferences - Override which API to use per device
4. Explicit LAN IP configuration - Manual IP entry for VLAN/discovery issues

Related

• Resolves foundational work for addon cannot start when there is a network outage if configured to use Platform and/or IoT APIs #76
• Supersedes feat: Add graceful degradation to LAN-only mode on API failures (fixes #76) #537 (which was rejected due to scope issues)

---

Happy to address any feedback or make adjustments to the approach!

[inventor7777]

Whoa that was fast!! Looking forward to per-device LAN API only mode :)

[maxfield-allison]

Whoa that was fast!! Looking forward to per-device LAN API only mode :)

I really just want to not worry about getting locked out for abnormal activity ever again if i have connectivity issues or bounce my services multiple times while messing around lol

[maxfield-allison]

@inventor7777 not to say i don't also want enhanced features, lol, im sure I'll contribute more as time permits. (mister thumbs down... XD)

[inventor7777]

OOOPS I'm sorry i didn't mean to do that 😂😂
(GitHub sometimes behaves weirdly on mobile)

[wez]

Thank you again for this! Sorry for the delay in responding; it's a busy time of year!

[maxfield-allison]

Thank you again for this! Sorry for the delay in responding; it's a busy time of year!

I completely understand. We hope for side project time but life always seems to find a way to make it difficult!

[maxfield-allison]

one more commit incoming shortly to address the remaining items from review. or i can close and push one clean if you prefer, apologies.

[maxfield-allison]

need to correct database saves on LAN status query

[AlgoClaw]

Not sure if this helps, but there is similar functionality in my fork (AlgoClaw/govee2mqtt) after creating a feature request in this issue (which I closed shortly after).

You can map the internal directory /JSONs as a persistent volume which can store saved scene commands for LAN control.

For example, if you save H61A8_final.json in /JSONs, the Govee2MQTT bridge will use the scenes defined in the the JSON file.

What's is cool too is that you can keep old/deleted scenes Govee removed.

I am a total noob when it comes to PRs and git stuff. So, I do not know how to help there.

[inventor7777]

Nice thinking.

that's another pain point I have with the current implementation - it doesn't pull everything (I have hundreds of DIYs and it only pulls half or less)

[mercertom]

When can we get this? I can't use adaptive lighting until this is fixed. My service just insta-pings over the daily or minute or second or hour limit, and then my lights are stuck at some arbitrary brightness.