BigFred – Architecture (split documents)

This folder holds the BigFred architecture proposal, split into one file per top-level section. The parent file ../README.md is the entry point with the full table of contents.

Section numbering (§3a.4, §7b.1, …) is preserved in heading text so cross-references inside the prose still work via Ctrl+F. Large sections that grew beyond ~250 lines are further split into subfolders; each subfolder carries its own README.md with its sub-TOC.

Terminology

Goals

Usage context

LAN-only hub deployment, scale (~100–150 vehicles), low latency, non-technical end users, simple Raspberry Pi setup, and proportionate security (PIN + WPA, no HTTPS).

Technology Stack

High-Level Architecture

Repository Layout

Domain Model (REL — Data Mapper)

Communication Protocol (REST + WebSocket)

Backend Components

Frontend Components

Cross-Cutting Concerns

Internationalization (i18n)

Offline-first frontend assets

Bundled fonts/CSS/JS, no CDN at runtime, check-offline-bundle gate.

Authentication, Roles & Authorization

API Keys & Built-in MCP Server

Makefile Additions

Delivery Order (Milestones)

Acceptance Criteria

Process Supervisor (Supervisord)

Non-root process groups, Go templates, hot reload, daemon lifecycle.

DCC Bus Daemon (dcc-bus)

Per-(layout × command station) sibling daemon for the throttle data plane; session-aware, security-policy-driven, Redis-cached.

Reliability — reconnect & retry

WebSocket backoff, command retries, DMS grace, mobile screen wake.