parking_solution/wiki/concepts/first-run-setup.md

type, tags, sources, updated

type	tags	sources	updated
concept	parking architecture devices admin	parking-system-architecture	2026-06-15

First-Run Setup (device selection)

The admin install flow that makes the system device-agnostic in practice: on first run, an admin adds controllers (each declaring its relays — entry/exit/both — the entry-button terminal, and the one-car-one-ticket guard: a presence-loop input or a cooldown, see entry-double-press) and then readers/cameras/printers bound to a controller relay, choosing from the device-registry catalog and entering each device's connection config. There is no lane — the pool-of-spaces model; see entry-exit-points.

Implementation-derived (from apps/server + apps/web), not the source doc.

Flow

1. Read the catalog — GET /api/setup/catalog returns supported drivers per category (no secrets, just schema) plus a discoverable list. The web SetupWizard renders a picker + the driver's config fields, and a Scan button for discoverable drivers (device-discovery).
2. Test (optional, no save) — POST /api/setup/test (admin-only). Validates the config, probes reachability (healthCheck), and reports preconditions (e.g. input_link_relay) — without saving or changing the device. The wizard's Test connection button shows a health badge + any precondition warnings.
3. Save & configure — POST /api/setup/assign (admin-only). Validates, then configures the device: fixes preconditions (e.g. disables input_link_relay) and sets up the Digest- authenticated input push (device-input-flow) — the admin never touches the device's own web UI. Fails the save (no DB row) if the device can't be configured, so there are no orphan/half-configured rows. On success persists to devices.
4. Remove — DELETE /api/setup/assign/:id (admin-only) drops one instance's row. Only our row is removed; the device itself is not un-hardened/un-configured (a stale push from an unknown device id is already rejected, and re-assigning reconfigures it).
5. Complete — POST /api/setup/complete marks the single-row setup_state.

Config granularity — multi-instance per category

The data model is multi-instance: devices holds one row per instance, keyed by a generated id. So the site can have more than one of every category — multiple controllers, readers, cameras, and printers (e.g. an entry dispenser + a booth printer; see printer-roles-failover). assign always inserts a new row (never an upsert), and state returns the full list.

The SetupWizard reflects this: each category shows the list of assigned instances (with Remove) plus an Add another form — not a single fixed slot. select-type config fields (e.g. a printer's role) render as dropdowns.

There is no lane. Direction lives on each access relay; readers/cameras bind to a controller relay (config.controllerId + relay) — the barrier they serve — and inherit its direction. The wizard adds controllers first, then binds the other devices to a relay. See entry-exit-points, entry-exit-readers.

Security notes

• The assign/state/delete/complete endpoints require the admin role (local-jwt-auth).
• Device credentials are stored in devices.config — protect at rest (disk-os-hardening); device hosts belong on the isolated VLAN (network-isolation).
• Secrets are stripped on the way out: assign and state both redact pushPassword, webPassword, and relayPassword from the returned config (the UI lists devices; it never needs the stored secrets).