ratdeck/docs/ARCHITECTURE.md

# Ratdeck — Architecture

## Overview

Ratdeck is a standalone Reticulum mesh node with LXMF encrypted messaging, built for the LilyGo T-Deck Plus (ESP32-S3). It runs the full Reticulum protocol stack on-device — no host computer, no gateway, no KISS protocol. LoRa, WiFi, and BLE transports operate independently or bridged.

## Layer Diagram

```
+---------------------------------------------+
|           UI Layer (LVGL v8.4)              |
|  Screens: Home, Friends, Msgs, Peers, Setup |
|  LvStatusBar, LvTabBar, LvInput            |
|  Theme: Matrix green (#00FF41) on black     |
+---------------------------------------------+
|         Application Layer                   |
|  LXMFManager  AnnounceManager              |
|  IdentityManager  UserConfig               |
|  MessageStore  AudioNotify                  |
+---------------------------------------------+
|         Reticulum Layer                     |
|  ReticulumManager (microReticulum C++)      |
|  Identity, Destination, Transport           |
+---------------------------------------------+
|         Transport Layer                     |
|  LoRaInterface   WiFiInterface              |
|  TCPClientInterface   BLESideband           |
+---------------------------------------------+
|         Storage Layer                       |
|  FlashStore (LittleFS, 7.875 MB)            |
|  SDStore (FAT32 microSD)                    |
|  NVS (ESP32 Preferences)                    |
+---------------------------------------------+
|         Hardware Layer                      |
|  SX1262 Radio    ST7789V Display            |
|  I2C Keyboard    GPIO Trackball             |
|  ESP32-S3 (8MB PSRAM, 16MB Flash)           |
+---------------------------------------------+
```

## Directory Structure

```
src/
+-- main.cpp                    Setup + main loop (single-threaded, core 1)
+-- config/
|   +-- BoardConfig.h           GPIO pins, SPI config, hardware constants
|   +-- Config.h                Version, feature flags, storage paths, limits
|   +-- UserConfig.*            Runtime settings (JSON, dual SD+flash backend)
+-- radio/
|   +-- SX1262.*                SX1262 LoRa driver (register-level, async TX)
|   +-- RadioConstants.h        SX1262 register addresses and command bytes
+-- hal/
|   +-- Display.*               LovyanGFX ST7789V driver + LVGL flush callback
|   +-- Power.*                 Screen dim/off/wake, battery ADC, brightness
|   +-- Keyboard.*              I2C keyboard (ESP32-C3 at 0x55)
|   +-- Trackball.*             GPIO trackball (ISR-based, 5 pins)
|   +-- TouchInput.*            GT911 capacitive touch (disabled)
+-- input/
|   +-- InputManager.*          Unified keyboard + trackball + touch polling
|   +-- HotkeyManager.*         Ctrl+key dispatch table
+-- ui/
|   +-- Theme.h                 Color palette, layout constants
|   +-- LvTheme.*               LVGL theme application
|   +-- LvStatusBar.*           Signal bars + brand + battery %
|   +-- LvTabBar.*              5-tab bar with unread badges
|   +-- LvInput.*               Key event routing to active screen
|   +-- UIManager.*             Screen lifecycle, boot/normal modes
|   +-- screens/
|       +-- LvBootScreen.*      Boot animation with progress bar
|       +-- LvHomeScreen.*      Name, LXMF address, status, online nodes
|       +-- LvContactsScreen.*  Saved friends (display name only)
|       +-- LvMessagesScreen.*  Conversation list (sorted, previews, unread dots)
|       +-- LvMessageView.*     Chat bubbles + status colors + text input
|       +-- LvNodesScreen.*     Node browser (contacts + online sections)
|       +-- LvSettingsScreen.*  7-category settings editor
|       +-- LvHelpOverlay.*     Hotkey reference modal
|       +-- LvNameInputScreen.* First-boot name entry
+-- reticulum/
|   +-- ReticulumManager.*      microReticulum lifecycle, transport loop
|   +-- AnnounceManager.*       Node discovery, friend persistence
|   +-- LXMFManager.*           LXMF send/receive, queue, delivery tracking
|   +-- LXMFMessage.*           Wire format + JSON storage format
|   +-- IdentityManager.*       Multi-slot identity management
+-- transport/
|   +-- LoRaInterface.*         SX1262 <-> Reticulum (1-byte header)
|   +-- WiFiInterface.*         WiFi AP, TCP server on port 4242
|   +-- TCPClientInterface.*    WiFi STA, TCP client to remote nodes
|   +-- BLEInterface.*          BLE transport
|   +-- BLESideband.*           NimBLE Sideband interface
+-- storage/
|   +-- FlashStore.*            LittleFS with atomic writes
|   +-- SDStore.*               SD card (FAT32) with atomic writes
|   +-- MessageStore.*          Per-conversation dual-backend storage
+-- audio/
    +-- AudioNotify.*           Notification sounds
```

## Data Flow

### Incoming LoRa Packet

```
SX1262 IRQ (DIO1, GPIO 45) -> SX1262::receive() reads FIFO
    -> LoRaInterface::loop() strips 1-byte header
        -> RNS::InterfaceImpl::receive_incoming()
            -> RNS::Transport processes packet
                +-- Announce -> AnnounceManager callback -> UI update
                +-- LXMF data -> LXMFManager -> MessageStore (flash + SD) -> UI notification
                +-- Path/link -> Transport table update -> persist to flash + SD backup
```

### Outgoing LXMF Message

```
User types message -> LvMessageView -> LXMFManager::send()
    -> Save to MessageStore (QUEUED status)
    -> Pack: dest_hash(16) + src_hash(16) + signature(64) + msgpack([ts, title, content, fields])
        -> RNS::Packet -> RNS::Transport selects interface
            +-- LoRaInterface -> prepend 1-byte header -> SX1262::beginPacket/endPacket (async)
            +-- TCPClient -> HDLC frame (0x7E delimit, 0x7D escape) -> TCP socket
    -> StatusCallback fires -> re-save with SENT/DELIVERED/FAILED status
```

### Config Save

```
LvSettingsScreen -> UserConfig::save(sd, flash)
    +-- serialize to JSON string
    +-- SDStore::writeAtomic("/ratputer/config/user.json")   -> .tmp -> verify -> .bak -> rename
    +-- FlashStore::writeAtomic("/config/user.json")         -> .tmp -> verify -> .bak -> rename
```

## Key Design Decisions

### Radio Driver

Register-level SX1262 driver with no library abstraction. Async TX mode (`endPacket(true)`) returns immediately — `isTxBusy()` polls completion in `LoRaInterface::loop()`. `waitOnBusy()` calls a yield callback so LVGL stays responsive during SPI waits. TCXO 1.8V, DIO2 as RF switch, 8 MHz SPI clock.

### Display

LovyanGFX drives the ST7789V over SPI at 15 MHz. LVGL v8.4 renders to a flush buffer with DMA transfer. 320x240 landscape, 20px status bar top, 20px tab bar bottom, 200px content area.

### Reticulum Integration

microReticulum C++ library with LittleFS-backed filesystem. Device runs as either an Endpoint (default) or Transport Node (configurable in Settings). All interfaces (LoRa, WiFi, TCP, BLE) register with `RNS::Transport`.

### LXMF Wire Format

```
[dest_hash:16][src_hash:16][signature:64][msgpack_payload]
```

MsgPack payload: `fixarray(4): [timestamp(float64), title(str), content(str), fields(map)]`

Signature covers: `dest_hash || src_hash || msgpack_payload`

Messages under MDU (~254 bytes for LoRa) are sent as single direct packets. Stored as JSON per-conversation in flash and SD.

### Shared SPI Bus

Display, SX1262 radio, and SD card all share SPI2_HOST (FSPI on ESP32-S3). Single-threaded access from `loop()` — no mutex needed. Arduino FSPI=0 maps to SPI2 hardware; do NOT use `SPI2_HOST` IDF constant directly.

### WiFi Transport

Three mutually exclusive modes:
- **OFF**: No WiFi — saves power and ~20 KB heap
- **AP**: Creates `ratdeck-XXXX` hotspot, TCP server on port 4242, HDLC framing
- **STA**: Connects to existing network, TCP client connections to configured endpoints

AP+STA concurrent mode was removed — consumed too much heap and caused instability.

### TCP Client Transport

Outbound TCP connections to remote Reticulum nodes. Created on WiFi STA connection, auto-reconnect on disconnect (15s interval). Settings changes apply live via `_tcpChangeCb` callback — `reloadTCPClients()` stops old clients and creates new ones. Switching servers clears transient nodes.

### Dual-Backend Storage

FlashStore (LittleFS, 7.875 MB partition) is the primary store. SDStore (FAT32 microSD) provides backup and extended capacity. Both use atomic writes (`.tmp` -> verify -> `.bak` -> rename) to prevent corruption on power loss. UserConfig, MessageStore, and AnnounceManager write to both backends.

### Identity System

Triple-redundant storage: Flash (LittleFS), SD card, and NVS (ESP32 Preferences). Load order: Flash -> SD -> NVS -> generate new. On any successful load or creation, saves to all three tiers. Multi-slot identity management with per-slot display names.

### Transport Reference Stability

`RNS::Transport::_interfaces` stores `Interface&` references (not copies). All `RNS::Interface` wrappers must outlive the transport — stored in `std::list` (not vector, which would invalidate references on reallocation).

### Power Management

Three states: ACTIVE -> DIMMED -> SCREEN_OFF. Strong activity (keyboard, trackball nav/click) wakes from any state. Weak activity (trackball raw movement) wakes from DIMMED only. Configurable timeouts via Settings.

### Boot Loop Recovery

NVS counter tracks consecutive boot failures. After 3 failures, WiFi is forced OFF on next boot. Counter resets to 0 at end of successful `setup()`.

### Input System

Trackball click uses deferred release with 80ms GPIO debounce. Long press fires at 1200ms hold, suppresses click on release. Nav events are rate-limited to 200ms with threshold of 3 accumulated deltas. I2C keyboard at address 0x55 with interrupt on GPIO 46.