From c13de0b3c26a20b8ea4e2638b62e7e9a83a15148 Mon Sep 17 00:00:00 2001
From: nick <coachward0742@gmail.com>
Date: Thu, 4 Jun 2026 04:21:07 -0600
Subject: [PATCH] Update architecture decision records

---
 docs/decisions.md | 201 +++++++++++++++++++++++++++++++++++++---------
 1 file changed, 161 insertions(+), 40 deletions(-)

diff --git a/docs/decisions.md b/docs/decisions.md
index 39ab7b8..b6e3fce 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -1,58 +1,179 @@
-# Project Decisions
+# Decisions
 
-## Communications
+This document records important design and architecture decisions for Overland Controller.
 
-Primary:
-- UART over CAT5 initially
+The goal is to preserve why choices were made, not just what was implemented.
 
-Backup/Future:
-- RS-485 over CAT5 if UART proves unreliable
-- WiFi HTTP API
+## Decision: ESP32 Owns System State
 
-## Dashboard
+The ESP32 controller is the source of truth.
 
-- Touchscreen only
-- No physical buttons required
-- Screen sleeps when ignition is off
-- Touch wakes display
+It owns:
 
-## Relay Design
+- Sensor readings
+- Relay states
+- BMS state
+- Configuration
+- Alarm state
 
-- ESP32 relay board does NOT switch loads directly
-- Bosch-style automotive relays switch all major loads
+Reason:
 
-## Power Loads
+The ESP32 is installed near the electrical system and should continue operating even if the dashboard is disconnected.
 
-Current:
-- Starlink
-- Fridge
+## Decision: Pico Is a Dashboard, Not the Controller
 
-Future:
-- Inverter
-- Camp Lights
+The Pico dashboard is responsible for user interaction.
 
-## Sensors
+It should not own critical control state.
 
-Current:
-- Fridge Zone 1
-- Fridge Zone 2
-- Rear Seat Area
-- Outside Air
+Reason:
 
-Future:
-- Battery Bay
-- Cabin Air
-- Water Tank
+The dashboard may reboot, disconnect, or be removed without disabling the controller.
 
-## Configuration
+## Decision: UART Is the Primary Dashboard Link
 
-Configuration is stored on controller side, not browser side.
+UART is the preferred Pico-to-ESP32 communication path.
 
-## Logging
+Reason:
 
-No persistent logging currently planned.
+- Simple wiring
+- Deterministic
+- No WiFi dependency
+- Works offline
+- Easier to debug electrically
 
-Focus:
-- Live monitoring
-- Alarms
-- Control
+HTTP remains useful for setup, debugging, and future web UI.
+
+## Decision: HTTP and UART Should Share a Data Model
+
+The same status/config model should be used across:
+
+- UART
+- HTTP
+- Simulator
+- Future MQTT/Home Assistant integrations
+
+Reason:
+
+Maintaining multiple data models creates unnecessary rework and bugs.
+
+## Decision: Use Generic IDs Internally
+
+Firmware uses generic identifiers:
+
+    relay_1
+    relay_2
+
+    temp_1
+    temp_2
+    temp_3
+    temp_4
+    temp_5
+    temp_6
+    temp_7
+    temp_8
+
+Reason:
+
+The project should not be tied to one vehicle or one layout.
+
+## Decision: User Names Belong in Configuration
+
+Installation-specific names are saved in config, not hardcoded.
+
+Examples of allowed config names:
+
+    Fridge
+    Starlink
+    Cabin
+    Outside
+    House Battery
+
+Reason:
+
+The same firmware should work in different vehicles, trailers, campers, and power systems.
+
+## Decision: BMS Address Is Configurable
+
+The BMS BLE address is stored in configuration.
+
+Reason:
+
+Different users will have different BMS devices.
+
+The firmware should not require source code changes to connect to a battery.
+
+## Decision: BLE Setup Mode Exists
+
+BMS discovery runs in setup mode.
+
+Reason:
+
+BLE scanning can conflict with an active BMS connection.
+
+Setup mode pauses normal BMS reconnect behavior and allows repeated scans.
+
+## Decision: Keep USB Serial as a Service Interface
+
+USB serial remains available for:
+
+- Recovery
+- Troubleshooting
+- Factory reset
+- Manual configuration
+- Debug logging
+
+Reason:
+
+A physical service path is valuable when WiFi, UART, or dashboard software is broken.
+
+## Decision: Relays Should Drive Automotive Relays
+
+ESP32 relay outputs should not directly power high-current loads.
+
+Recommended pattern:
+
+    ESP32 output
+      -> relay module
+      -> automotive relay
+      -> fused load
+
+Reason:
+
+Loads like refrigerators, inverters, compressors, and Starlink should use proper fused automotive circuits.
+
+## Decision: DS18B20 Sensors Need Pull-Up Resistor
+
+The 1-Wire bus requires a pull-up resistor.
+
+Recommended value:
+
+    4.7k ohm
+
+Reason:
+
+Long DS18B20 leads are unreliable without the required pull-up.
+
+## Decision: Local-First Operation
+
+The system should not require internet access.
+
+Reason:
+
+Overland and remote-use scenarios may have no connectivity.
+
+## Decision: Keep APIs Human-Debuggable
+
+Messages use JSON.
+
+Reason:
+
+JSON is easy to inspect in serial logs, HTTP responses, simulators, and future tools.
+
+## Decision: Avoid Premature Cloud Features
+
+Cloud dashboards and remote access are not current priorities.
+
+Reason:
+
+The core controller/dashboard system should be reliable locally before remote features are considered.