From 24cf7e565385151bb3018b3168f62f3c073501db Mon Sep 17 00:00:00 2001
From: root <root@development.info>
Date: Tue, 2 Jun 2026 23:46:59 -0600
Subject: [PATCH] Add system architecture document

---
 docs/architecture.md | 235 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 235 insertions(+)

diff --git a/docs/architecture.md b/docs/architecture.md
index e69de29..870d9bd 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,235 @@
+# Xterra Overland Power & Monitoring Dashboard Architecture
+
+## Overview
+
+The Xterra Overland Power & Monitoring Dashboard is a distributed monitoring and control system consisting of:
+
+* Raspberry Pi Pico 2 W dashboard module
+* ESP32 cargo-area controller
+* RS-485 wired communications
+* WiFi backup communications
+* Touchscreen dashboard interface
+
+The system is designed to operate completely offline and continue functioning even when WiFi is disabled.
+
+---
+
+## System Goals
+
+* Monitor house battery status
+* Monitor fridge temperatures
+* Monitor rear seat temperature
+* Monitor outside ambient temperature
+* Control Starlink power
+* Control fridge power
+* Provide a dashboard display while driving
+* Expand later to vehicle telemetry and trip logging
+
+---
+
+## Dashboard Module
+
+### Hardware
+
+* Raspberry Pi Pico 2 W
+* 3.5" touchscreen
+* Powered by 5V from cargo-area buck converter
+
+### Responsibilities
+
+* Display information
+* Accept touch input
+* Send commands to controller
+* Display alarms and warnings
+* Provide user configuration interface
+
+### Communications
+
+Primary:
+
+* RS-485 over CAT5
+
+Secondary:
+
+* WiFi HTTP API
+
+---
+
+## Controller Module
+
+### Hardware
+
+* ESP32 relay board
+* House battery connection
+* Bosch-style automotive relays
+
+### Responsibilities
+
+* Read sensors
+* Interface with BMS
+* Control relays
+* Serve API data
+* Handle logging
+
+---
+
+## Temperature Sensors
+
+### Planned Sensors
+
+1. Fridge Zone 1
+2. Fridge Zone 2
+3. Rear Seat Temperature
+4. Outside Ambient Temperature
+5. Battery Compartment Temperature (future)
+
+### Interface
+
+* DS18B20
+* Shared 1-Wire bus
+* Connected to ESP32
+
+---
+
+## Battery Monitoring
+
+### Planned BMS
+
+* Xiaoxiang / JBD Bluetooth BMS
+
+### Data Collected
+
+* State of Charge
+* Voltage
+* Current
+* Remaining Capacity
+* Runtime Estimate
+* Battery Temperature
+* Cell Voltages
+* Cell Imbalance
+
+---
+
+## Relay Control
+
+### Current Loads
+
+* Starlink
+* Fridge
+
+### Future Loads
+
+* Inverter
+* Camp Lights
+
+### Design
+
+ESP32 relay outputs SHALL NOT carry load current.
+
+ESP32 relays will only energize Bosch-style 30A/40A automotive relays.
+
+All loads must be fused appropriately.
+
+---
+
+## Communications
+
+### Primary
+
+RS-485 over CAT5
+
+Advantages:
+
+* Reliable
+* Noise resistant
+* Independent of WiFi
+* Works while driving
+
+### Backup
+
+WiFi HTTP API
+
+Used for:
+
+* Phone access
+* Web dashboard
+* Configuration
+* Future Home Assistant integration
+
+---
+
+## WiFi Rules
+
+### Starlink OFF
+
+* Dashboard operational
+* Sensors operational
+* Relay control operational
+* WiFi disabled
+* Web dashboard disabled
+
+### Starlink ON
+
+* WiFi enabled
+* Web dashboard enabled
+* Remote access enabled
+
+### Override
+
+User may temporarily enable WiFi for troubleshooting.
+
+Default timeout:
+10 minutes.
+
+---
+
+## Dashboard Behavior
+
+### Ignition ON
+
+* Screen active
+* Full brightness
+
+### Ignition OFF
+
+* Screen black
+* Pico remains powered
+* Touch input remains active
+
+Touching screen:
+
+* Wake display
+* Display dashboard
+* Auto-sleep after timeout
+
+---
+
+## Future Expansion
+
+### Vehicle Data
+
+* OBD-II
+* CAN bus
+* Fuel level
+* RPM
+* Coolant temperature
+* Vehicle speed
+
+### Navigation
+
+* GPS
+* Trip logging
+
+### Connectivity
+
+* MQTT
+* Home Assistant
+* InfluxDB
+* Grafana
+
+### Additional Sensors
+
+* Additional DS18B20 sensors
+* Voltage sensors
+* Current sensors
+* Environmental monitoring