# Design and internals

The rest of these docs say what the bench does. This chapter says how it is
built and why — for contributors, and for anyone debugging behaviour that only
makes sense once the mechanism is visible.

Two constraints shape nearly everything here.

**Several processes look at one bench at the same time.** A CLI command you
type, the Qt console, the headless `fleet run`, the remote agent — each must be
able to answer *is pm100d running?*, *what did that install print?*, *why did
the server die?* about processes another one started, possibly yesterday. So
every piece of bench state is a small file in the home, and nothing the bench
manages is a child process of the thing that started it.

**Benches are Windows, developer machines are not.** The same code runs on
both, and nearly every bug this component has had was platform-specific. So
every platform branch lives in one module, and a test fails if one appears
anywhere else.

## The pages

- [Architecture](architecture.md) — the layers (model, services, presenter,
  view, host), what each may depend on, the home layout, fleets, where a
  device writes, and how one request travels through them.
- [Process management](processes.md) — why nothing is a child process, what the
  detached launcher does, how liveness and exit codes survive the process that
  started them, and the stop sequence.
- [Ports](ports.md) — the reserved numbers, where a port comes from, the
  difference between a named and an allocated port, and why allocation asks the
  socket rather than the bookkeeping.
- [The installer](installer.md) — how an installed version is matched to a
  declaration, the staging directory, the fallbacks for a release that is not
  on the index yet, and where `git` comes from.
- [The agent and the client](agent.md) — the wire protocol, why the CLI is the
  API, the one request type that is not a command invocation, and the split
  into two distributions.
- [The console's design](console.md) — what is taken from plesty-lib and what
  is designed here, how the view stays a view, and how it is tested offscreen.
- [Experiment runs](experiments.md) — the manifest, how Run checks the shared
  disk and serves devices across benches, how a run is watched and stopped
  through its directory, a run whose job died, operators and notes, the
  welcome demo, and how its report is written.
- [Cross-platform development](cross_platform.md) — the one-module rule, the
  full table of what differs, and how to add a difference.
- [Packaging and releases](packaging.md) — the two wheels, the light
  installers, updating from the app, the CI jobs on a tag, signing, and the
  uninstall design.