BigFred – Web Application Architecture Plan
This document describes the proposed architecture for a web application that
controls model railroad locomotives. It builds on top of the existing
pkgs/loco and pkgs/rb packages (Go core), which already provide a clean
LocoApp controller layer, a Station interface (Z21, LocoNet) and SQLite
access via modernc.org/sqlite (pure Go, CGO_ENABLED=0).
The architecture is split across multiple files under
./architecture/. For an orientation read start at
the architecture index; for a specific
topic, jump directly to one of the sections below.
Section numbering used in the prose (§3a.4, §4.5, §7b.1, …) is
preserved verbatim in the headings of the split files, so existing
cross-references inside the text still work via Ctrl+F.
On the Go server, responsibilities are split across three packages under
pkgs/bigfred/server/: http (and ws) terminate transport and
authentication; service owns validation, orchestration, and
permission checks via security; see
§3.1 Backend layer responsibilities.
Terminology
Goals
Usage context
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)
Authentication, Roles & Authorization
API Keys & Built-in MCP Server
Makefile Additions
Delivery Order (Milestones)
Acceptance Criteria
Process Supervisor (Supervisord)
DCC Bus Daemon (dcc-bus)
Task-scoped implementation plans live under ./plans/: