\chapter{Class Reference}
\label{ch:classes}

This chapter documents the firmware's public classes at the design level:
what each class is responsible for, which collaborators it depends on, its
key invariants, and how it fits the system. It complements --- and does
not duplicate --- the generated API documentation, which carries the exact
method signatures. The HTTP JSON endpoints are documented separately in
Chapter~\ref{ch:api}.

\begin{drnote}[How this chapter grows]
Per the development rules, every public, architecturally-significant class
(the drivers, the application services, and the public domain-core types)
gets a section here, tagged \texttt{\textbackslash label\{cls:ClassName\}},
added in the same change that introduces the class. A tooling check keeps
this chapter in step with the code, so it is always current.
\end{drnote}

The firmware is under active development. As each public class lands, its
section appears below, grouped by layer: domain core, application
services, and hardware drivers.

% ------------------------------------------------------------------
% Domain core (Slice 1)
% ------------------------------------------------------------------

\section{FirmwareVersion}\label{cls:FirmwareVersion}
Strong type wrapping the firmware release identifier (e.g.\ \texttt{0.1.0}).
Used by \texttt{HealthStatus} and the \texttt{/api/health} endpoint so
version strings are never passed as bare \texttt{char*} across module
boundaries. Invariant: non-empty at construction.

\section{HealthStatus}\label{cls:HealthStatus}
Immutable health-check DTO returned by \texttt{GET /api/health}. Built via
\texttt{HealthStatus::ok(FirmwareVersion)} in the pure core; JSON
serialisation lives in \texttt{serializeHealthStatusJson()}. No ESP-IDF
headers.

% ------------------------------------------------------------------
% Network shell (Slice 1)
% ------------------------------------------------------------------

\section{SoftApConfig}\label{cls:SoftApConfig}
Immutable value type holding SoftAP parameters (SSID, channel, station
limit). Factory \texttt{setupDefault()} yields SSID \texttt{DigiRadio-setup}
for first-time provisioning.

\section{SoftApHost}\label{cls:SoftApHost}
RAII wrapper around the ESP-IDF Wi-Fi stack that starts and stops the
configured SoftAP. Imperative shell; no business logic.

\section{SetupWebServer}\label{cls:SetupWebServer}
Minimal HTTP server: gzipped setup UI, \texttt{GET /api/health}, and
\texttt{POST /api/wifi} for provisioning. JSON parsing and serialisation
delegate to the pure core; credentials persist via \texttt{ISecureStore}.

\section{NetBootstrap}\label{cls:NetBootstrap}
Owns network resources for setup or STA mode. \texttt{start(store)}
initialises the platform, joins stored Wi-Fi when credentials exist, or
falls back to the \texttt{DigiRadio-setup} SoftAP. Must outlive
\texttt{app\_main} for the process lifetime.

% ------------------------------------------------------------------
% Domain core + secure store (Slice 2)
% ------------------------------------------------------------------

\section{Secret}\label{cls:Secret}
Opaque wrapper for sensitive strings. Buffer is zeroised on destruction;
no \texttt{operator<<} and no plaintext serialisation. Shell code uses
\texttt{usePlaintext()} transiently for driver APIs only.

\section{WifiSsid}\label{cls:WifiSsid}
Validated Wi-Fi SSID (1--32 bytes). Parsed once from untrusted JSON at
the HTTP boundary before persistence or driver calls.

\section{WifiCredentials}\label{cls:WifiCredentials}
Domain value pairing \texttt{WifiSsid} with a \texttt{Secret} password.
Open networks use an empty password; WPA-PSK requires 8--63 characters.

\section{ISecureStore}\label{cls:ISecureStore}
Abstract persistence boundary for credentials at rest. Slice~2 implements
Wi-Fi credential save/load/clear; station list and user credentials arrive
in later slices. Host tests use fakes; the shell uses \texttt{NvsSecureStore}.

\section{StaClient}\label{cls:StaClient}
RAII STA join helper with an explicit connect timeout. Assumes
\texttt{esp\_wifi\_init()} was already called by \texttt{NetBootstrap}.

\section{NvsSecureStore}\label{cls:NvsSecureStore}
\texttt{ISecureStore} implementation backed by an NVS namespace. Passwords
are stored as NVS strings and never logged. Production should enable NVS
encryption using the reserved \texttt{nvs\_keys} partition.

% ------------------------------------------------------------------
% Future slices (drivers, services)
% ------------------------------------------------------------------
% \section{Si4684Driver}\label{cls:Si4684Driver}
% \section{TunerService}\label{cls:TunerService}
% ...