SPEC-UIX-DEV · v1.5
2 July 2026
Owner: Platform team

Design specification · build-ready · Portal · Monitoring

The device monitoring system — the Portal's heart

The exhaustive design specification for RiverSync's live device monitoring: the device inventory the customer lands on and the per-device detail that is the product's centrepiece — its Telemetry · Control · Maintenance · Configuration · Activity · Alarms tabs, where a health event becomes an action. It specifies every region, control, state and realtime contract of these surfaces — down to the sort fields, the filter controls, the card telemetry panel, the multi-metric time-series stack, the live-tween cadence, the online/offline behaviour and the role gating — so an implementer needs no further decisions. Telemetry is heterogeneous (three product families, six models, per-module units); the spec covers how the Portal renders the right shape for each device and degrades safely when it cannot.

1What it is — and what it is not

Device monitoring is where the customer sees the live health of every RiverSync converged micro data center across its sites, drills into one unit's telemetry, twin and history, and turns a raised alarm into a ticket or a scheduled visit. Devices is the Portal landing surface — there is no separate dashboard.

2The three surfaces at a glance

One landing surface and the device detail it navigates to. Every device carries a status, a family, a live telemetry shape, a single active maintenance agreement and a count of active alarms; those five facts are legible before a card is even opened. Alarms and maintenance are not standalone surfaces — they are tabs on the device detail.

Colour never carries meaning alone: every status pairs a tinted dot/badge with a word; every severity pairs a tint with an icon and a label.

3The device inventory — layout & grid

The landing surface is a wide page (rs-page--wide) with a 40px full-width command navbar pinned to the top of the content area, then a body of device cards in a responsive grid, then a pager when the working set exceeds one page. Card view only — there is no list/table toggle and no export (PTL-10). Sort and filter live in dropdowns on the right of the command bar; free-text search is an inline autocomplete beside them.

	Region	Sizing	Specification
1	Live-feed indicator .pv-devbar__feed	auto · 40px bar	The device glyph + a Live / Offline feed pill. Online: success-toned, the broadcast icon pulses. Offline: neutral, the offline glyph, static. Reflects the WebSocket telemetry feed (§6).
2	Fleet meta	auto	{n} devices · {n} sites · {n} need attention — a live count line after a vertical separator.
3	Search .pv-devsearch	auto · left of Sort	Inline autocomplete over id / model / site / serial (§4). Docked in the command bar to the left of the Sort button.
4	Sort · Filter .pv-cmd	auto · right edge	Two dropdown buttons; Filter carries an active-filter count badge and a dot. Both open a popover anchored to the command bar's right edge (§7).
5	Card telemetry panel	fills card main	Schema-aware live tiles with streaming sparklines (§5.2, §6).
6	Card rail	fixed right of card	Maintenance agreement (tier · partner · term bar · expiry) over active-alarm state (§5.3).
7	Pager .pv-devfoot	auto · 9/page	DS Pager + "Page X of N"; shown only when the working set exceeds PAGE_SIZE = 9. Resets to page 1 on any filter / sort change.

Grid: .pv-devgrid is a responsive card grid (three-up on a wide viewport, reflowing to two / one). Cards align to the command bar with equal left/right gutters. The empty result shows the DS EmptyState ("No devices match these filters").

4Search — inline autocomplete

Search lives in the command bar (not the filter popover), to the left of Sort. It is a combobox: as the customer types, a dropdown lists up to seven matching devices; picking one jumps straight to that device's detail. The same text also filters the card grid live, so search narrows the list and offers a shortcut simultaneously.

Element	Spec
Match set	Case-insensitive substring over id + model + siteName + serial, capped at 7 results (.pv-devsearch__pop).
Option row	Status dot + id (bold mono) + model · site subline + a chevron that fades in on the active row.
Keyboard	↓/↑ move the highlight, Enter opens the highlighted device, Esc closes the popover (and clears the field if it had text). Highlight resets to the top on every keystroke.
Clear	An x button appears when the field has text; it clears and refocuses the input.
ARIA	role="combobox" + aria-expanded on the input; role="listbox"/option + aria-selected on the dropdown. Outside-click closes it.

5Sort — a comprehensive dropdown

The Sort button opens a popover with an order toggle (High → low / Low → high, a DS Segmented) and a radio list of ten sort fields, each an icon + label + one-line description, the active one ticked. The choice is persisted (useStickyState('dev-sort')). The Sort button label reads simply Sort — it does not echo the selected field.

Field key	Default dir	Ordering
Needs attention attention	High → low	Default. STATUS_RANK×100 + activeAlarms — offline & warning units, most alarms, first.
Device ID id	A → Z	Identifier lexical.
Status status	High → low	By health rank (offline › warning › maintenance › uncataloged › online).
Active alarms alarms	High → low	Count of active alarms.
Site site	A → Z	Grouped by location name.
Family family	A → Z	Frigo · Koelkast · Nevera.
Model model	A → Z	Model name.
Firmware fw	High → low	Firmware version string.
Agreement expiry expiry	Soonest first	Active agreement end date (uncataloged sorts last, 9999-99-99).
Commissioned since	Newest first	Commissioning date.

Ties break on id. The order toggle and the field are independent — changing one keeps the other.

5.1Filter — DS form controls

The Filter button opens a popover built entirely on the design-system form kit. An active-filter count badge sits on the button; a header Clear all appears when any filter is set; a footer shows the live match count and a Done button. Outside-click and Esc close it.

Filter	Control	Values
Family	DS Select	All families · Frigo · Koelkast · Nevera.
Status	DS Select	All · Online · Warning · Offline · In service · Uncataloged.
Sites	DS TagInput (multi)	Tag-autocomplete over the org's site names; each chosen site is a removable chip. No free creation.
Maintenance tier	DS Segmented	Any tier · Gold · Silver.
Only active alarms	DS Switch	Restrict to devices with ≥ 1 active alarm.

5.2The device card — anatomy

Each card (.pv-devcard) is a considered at-a-glance summary, not the full detail. The whole card is a button to the device detail; the menu and rail stop propagation so their own controls work. A card with an active alarm carries a top severity accent bar (.pv-devcard--danger / --critical / --warning). The card chassis is square — border-radius:0, matching the shell-chrome idiom (nav rows and chrome are square; the DS is not a rounded brand) — with the hairline border + shadow-sm carrying the elevation.

5.2.1The live tile

A tile (.pv-dk on the card, .pv-tile on the detail) is a label, a big value with a small unit, and a streaming sparkline. Decimal precision follows the unit: 0 dp for %RH · V · %, 2 dp for the unitless (PUE), 1 dp otherwise. A tile with no value shows "—". A tile can carry a tone (danger / warning) that tints the value and sparkline.

6The realtime feed — online / offline

The Portal reads a live telemetry feed (a WebSocket in production; a simulated stream in the prototype). The command bar's Live / Offline indicator reflects the feed's connection, and the whole surface's motion is gated on it.

This is distinct from a device going offline: a single unit's connection loss is a per-device state (status offline, last-seen, and it can raise an alert, PTL-2/9), whereas the feed indicator is about the Portal's own live channel. Both use the same vocabulary so the reading stays consistent.

7The device detail — the centrepiece

Opening a card navigates to the device detail (PV.Device) — a single-column page (.pv-devwrap, rs-page--wide) led by a 40px full-width tab bar pinned to the top of the content: a back-to-Devices chevron, the six tabs, and a right-aligned role-gated Schedule command. Below it a header band carries identity + status; the selected tab's content fills the column. There is no persistent right rail — each tab owns its full width.

Region	Specification
Header band	The id (mono h1) · FamilyChip · a schema-resolution strip (Model · Firmware → Schema+version, or “Schema unregistered” for uncataloged) and, right-aligned, the StatusBadge. The metarow reads model · rack · site · region.
Tab bar .pv-devtabs	Six tabs, in order: Telemetry (default) · Control · Maintenance · Configuration · Activity · Alarms (carries a count badge when the device has active alarms). Each tab is a .pv-cmd button (icon + label) in a top-pinned 40px navbar. The tab is deep-linkable (go('device', {deviceId, tab})) so a card menu, a ticket link or an alarm opens a specific tab; initialTab seeds it and re-seeds on device change.
Schedule action	The tab bar's right edge carries a Schedule command (calendar icon) — role-gated (Editor +, schedule) and disabled while uncataloged; it opens the schedule flow (SPEC-UIX-SCH).
In-tab actions	Remote control lives in the Control tab; twin edit + firmware in Configuration; the alarm acknowledge→ticket flow in Alarms. All are role-gated (§9) and disabled entirely while uncataloged.

7.1Telemetry tab (PTL-1)

The default tab. It leads with the family's live tiles, then a single full-width multi-metric time-series stack card, then (for multi-module units) the cooling-module panel.

Element	Spec
Live tiles	The full schema tile set (§5.2.1), each tweening + streaming while the feed is online.
Telemetry stack TimeSeriesStack	One full-width card (.pv-widget), no card header — the stack's own legend + control row is the header. The DS multi-pane telemetry chart — several panes sharing one time axis with a synchronized crosshair, one overview brush for the whole period, and event-milestone annotations that line up across every pane. Streams live; hovering any pane freezes the scroll and crosshairs all panes at that instant. The header carries a combined legend (all line series), the Live / Paused pill, an Annotations toggle (show/hide the milestones) and the time-scale selector (ChartRange: 5m · 30m · 1h · 1d · 1mo · 1y · 3y). The card subline names the streams: return / supply / ambient air · humidity · power · COP · doors.
— Pane 1 air temperature & humidity	Left °C axis (setpoint band): return air, supply air and ambient air. Right %RH axis (40–55% band): humidity.
— Pane 2 power draw & COP	Left kW axis (zero-based): power draw as a filled area. Right axis: cooling COP as a line.
— Pane 3 door access	An EventTimeline pane (merged track) with the enclosure's three doors — front · back · side — as open→close state bands, each in its door colour; a band's overflow escalates to alarm (red, alert icon) once open past the 5-minute threshold; a door still open runs live with a pulsing edge. A single door's opens never overlap in time — a door can't open again while already open — so per-door events are laid end-to-end; different doors do overlap and stack into sub-rows.
Events (annotations)	Event milestones (dashed diamonds with an icon glyph) drawn across the full stack — setpoint changes, alarms, maintenance, offline. Door-open is not a milestone — doors have their own dedicated pane (3), so a door annotation would be redundant. The header Events toggle shows/hides the milestones.
Converged / Nevera	Renders the same three panes; its extra fields (PUE, battery, bus voltage) stay in the tile strip above.
Cooling modules	Shown when a unit reports > 1 module (pay-as-you-grow). One row per module: role, temperature, a load Meter and a state badge — nominal (success) · derated (warning) · offline (danger).
Degrade	Uncataloged units show "Telemetry unavailable — schema not registered": identity + connection only, readings marked unavailable, "Pending classification" — never null-mapped (PTL-7).

Prototype: apps/portal/portal-device.jsx (TelemetryTab) composes RSC.TimeSeriesStack; the panes/markers are built per family schema in apps/portal/portal-data.js (never in the view); the .rs-ts* chart chrome is apps/portal/portal-charts.css. Each device has one continuous 3-year record built once (cached) with adaptive resolution — 30-second samples in the last 6h coarsening to 1-day samples years back — carrying a diurnal + seasonal shape, so every scale reads the same history: fine live detail at 5m, three seasonal cycles at 3y. The overview brush stays proportionate to the window (~2.4×) clamped to the record start. The live tail appends samples on a ~2.4s cadence, mean-reverting toward each series' last reading, and pauses on a hidden tab / reduced motion.

7.2Configuration — the device twin (PTL-8)

The Configuration tab shows the device twin: reported state ↔ desired configuration. A table of settings, each with its Reported value, its Desired value and a reconciliation state — in sync (success) or drift (warning).

The Configuration tab also carries an Identity card (family · model · serial · firmware · schema+version · site · region · commissioned) above the twin, and a Firmware widget — running version + “Up to date”, with an Update firmware command (Owner / Admin, firmware) that stages to the twin and applies at the next maintenance window, audited.

7.3Control · Maintenance · Alarms · Activity tabs

Tab	Content
Control (PTL-5)	Customer remote control, Owner / Admin only (control) — other roles see a read-only LockNote and the controls are disabled; uncataloged units degrade. Two cards: Power — an on/off switch (Running “cooling — modules balanced under the master controller” / Off “standby — refrigeration circuit idle”); and Set temperature — the return-air setpoint on a stepper + range slider (18–30°C, 0.5° steps) with a pending vs applied readout and an Apply button (disabled until dirty, and while powered off). Every command toasts and is staged to the device twin and audited (PTL-5/8); a note repeats the recommended operating range (25–35°C).
Maintenance (PTL-3)	Active agreement (tier detail, servicing partner, term, “Renews in {n} days” when < 60) above Previous agreements, latest → oldest. Read-only in Portal; renewals are sold in Pipeline / Partners. This tab — not a standalone menu — is the Portal's maintenance surface.
Alarms (PTL-2)	This device's alarm rows (§8), scoped to the unit, with a tab-bar count badge; acknowledge / open a ticket inline. This tab — not a standalone menu — is the Portal's alarm surface.
Activity	A timeline: telemetry streaming (now) · any alarm raised · setpoint confirmed · preventive maintenance · commissioned. Each an icon + tone + text + relative time.

8Alarms — the device Alarms tab (PTL-2)

Alarms are read on the device detail's Alarms tab (AlarmsTab), scoped to that unit — there is no standalone Alerts & alarms page (removed Jul 2026). Cross-device alarm awareness comes from the device list's attention ranking (offline & alarmed units sort first, PTL-6) and the top-bar notification bell (the active alarms, newest first). Each alarm is an AlarmCard that makes it actionable: it names the cause and effect, and offers acknowledge + open-a-ticket.

Element	Spec
Scope	All alarm rows for the open device (alertsFor(dev.id)), newest first. Empty state: “No alarms recorded for this device.”
Card AlarmCard	A DS rs-card: a severity icon tile (warning / danger / critical soft tint + alert glyph) · title · SeverityBadge · id · time (mono) · a state badge (Acknowledged · {by} / Cleared). The cause→effect body reads operationally (“return air 41.4°C — 6.4°C above setpoint”).
Actions (active)	Acknowledge (records the actor) and Open ticket — the acknowledge→ticket flow (PTL-2/4). A resolved alarm that spawned a ticket shows a ghost link to that ticketId instead. All four roles may acknowledge and open tickets (PTL-5).

8.1Device state vocabulary

9Role gating (PTL-5)

Every customer role reaches every Portal surface; the difference is the actions inside. The device detail's action row and the twin editor gate by permission; monitoring, acknowledgement, ticket creation and messaging are open to all four roles.

Action	Requires	Notes
Monitor · acknowledge · open ticket	Viewer +	All four roles.
Configure · set thresholds · edit twin	Editor +	The Edit button on the twin; the Configure command.
Schedule visit	Editor +	Opens the schedule surface (SPEC-UIX-SCH).
Control equipment · apply firmware	Owner / Administrator	Reserved commands; others see a LockNote ("Control & firmware: Owner / Admin only").
Any action on an uncataloged unit	—	Disabled entirely until the unit is classified.

10Design-system mapping

Every element resolves to a RiverSync DS v2 component, class, icon or token. The surfaces are React pages composing DS charts + form controls; the pv-* classes are the Portal-local layer (portal.css), themed entirely through DS tokens.

Element	Class / component	DS basis
App pill (top bar)	rs-portalbadge--portal	Canonical Portal app badge (shell-chrome.css). Mandatory.
Shell	AppShell (hub)	The DS shell — sidebar HUB_NAV, top bar, product switcher.
Time series	TimeSeriesStack · Sparkline · Meter	DS charts — live tween ~900ms, crosshair, zero-based meters.
Tiles	.pv-dk · .pv-tile	Portal-local, DS tokens; hosts a DS Sparkline.
Status / severity	Badge · StatusDot · StatusBadge · SeverityBadge · FamilyChip	DS Badge (2px, soft tint, sentence case) + Portal atoms.
Tier badge	TierBadge	DS maintenance-tier chip (Silver / Gold + SLA tooltip).
Form controls	Select · Segmented · Switch · TagInput · Tabs · Pager · Menu · EmptyState	DS app-UI kit — the filter/sort popovers, tabs, paging.
Command buttons	.pv-cmd · .pv-icobtn	Command-bar buttons over DS tokens.
Feed indicator	.pv-devbar__feed + broadcast / offline	Portal-local; success/neutral DS tones, pulse keyframe.
Toast	PVToast(title, msg, kind)	Portal toast — success / info / warning / accent.
Icons	<Icon name="…"/>	Proprietary icon system (the G table) — never a third-party set.

Icons in use: server · activity · broadcast · offline · search · x · sliders · filter · chevron-down/-right · check · alert · warning · success · map-pin · settings · power · upload · wrench · calendar · shield-check · clock · more-vertical · external-link · help · minus · layers · cabinet. Any new glyph is added to the DS G table first, never drawn inline.

11Responsive & accessibility

Breakpoint	Behavior
Wide	Card grid three-up; command bar shows the full fleet-meta line.
≤ 960px	Search input narrows (184 → 120px); grid reflows to two-up.
≤ 720px	Search input narrows to 88px; grid one-up; fleet-meta may truncate.

Accessibility: cards and alarm rows are buttons (Enter-activatable); the search is a labelled combobox with a keyboard-navigable listbox; status/severity pair a tint with a word/icon (never colour alone); the sort/filter popovers carry role="dialog" + labels and close on Esc/outside-click; hit targets ≥ 40px; all live motion honours prefers-reduced-motion.

12As-built vs production targets

The prototype is the source of truth for look & behavior; these are the deltas a production build must close. None changes the model except where flagged.

Area	As-built	Production target
Live feed	simulated stream + Online Tweak	A real WebSocket telemetry channel; the indicator reflects its actual connection; drop & reconnect handled with backoff.
Card tween	client random-walk	Bind tiles to the real feed's latest reading; keep the ~2.3s cadence, hidden-tab pause and reduced-motion suppression.
Twin edit	toast stub	Real desired-config write with reconciliation + audit; confirm which changes are customer-initiated vs RiverSync-only (open question, PRD §5).
History depth	generated window	Honour the time-series store's retention; surface any legacy-cutover gap (PTL-10).
Uncataloged UX	degrade card + banner	Confirm the exact "pending classification" wording and how the customer vs RiverSync are notified (open question, PRD §5).

13Traceability

This spec	Traces to
Inventory + search/sort/filter (§3–5)	PTL-1 · PTL-6 (device list, card view, sort/filter) · PTL-9 (connection state).
Realtime feed (§6)	PTL-1 (live stream) · PTL-9 (online/offline).
Device detail (§7)	PTL-1 (telemetry) · PTL-7 (schema-aware) · PTL-8 (device twin) · PTL-3 (maintenance) · PTL-10 (history).
Alarms (§8)	PTL-2 (acknowledge · cause→effect · open ticket, on the device Alarms tab) → SPEC-UIX-TKT.
Role gating (§9)	PTL-5 · Account permission matrix (ACC-2).
Data model	Device · Alert (SPEC-ERD-PTL), Product Catalog (SPEC-ERD-PRO), telemetry/twin plane (SPEC-DDD-DVC, SVC-9). Telemetry readings live outside Postgres (PTL-1 ⚠).
Cross-links	Schedule (SPEC-UIX-SCH) · Maintenance (SPEC-PRD-MNT) · site map (Account, ACC-1).

14Revision history

Version	Date	Changes
1.5	2 Jul 2026	Alerts & Maintenance menus removed — spec reframed to the device-detail tabs; Control tab & single-column layout documented. The standalone Alerts & alarms and Maintenance pages are gone (prototype Jul 2026): the framing (§1–2), the inherit note and §8 now describe alarms as the device detail's Alarms tab (the AlarmCard), maintenance as its Maintenance tab; cross-device awareness is the device-list attention ranking + the notification bell. §7 is corrected to the real layout — a single-column page led by a top tab bar of six tabs (Telemetry · Control · Maintenance · Configuration · Activity · Alarms, no persistent right rail) with a role-gated Schedule action; the Control tab (power switch + return-air setpoint stepper/slider, staged & audited) and the Configuration Firmware widget are now fully specified. Matches SPEC-APP-PTL v0.24.
1.4	2 Jul 2026	Continuous 3-year telemetry record + header removed (§7.1). Each device now has one continuous 3-year history generated once with adaptive resolution (30s recent → 1-day far back) and a diurnal + seasonal shape, so every scale (5m…3y) reads the same record — fine live detail up close, seasonal cycles far out. The Telemetry card's header band is removed (the stack's legend/control row is the header). Prototype: portal-data.js seriesLong/cache, portal-device.jsx overview clamp + full-history call.
1.3	2 Jul 2026	Telemetry stack tuning (§7.1). Time-scale set aligned to the DS reference (5m · 30m · 1h · 1d · 1mo · 1y · 3y, default 1h); door pane alarm threshold set to 5 min with non-overlapping per-door events (a door can't reopen while open); the Events milestones exclude door-open (dedicated pane); the air-temperature pane raised to 224px. Matches SPEC-APP-PTL v0.22.
1.2	2 Jul 2026	Device-detail multi-metric telemetry stack (§7.1). Fully specified the Telemetry tab's single full-width TimeSeriesStack card: three shared-time-axis panes — air temperature & humidity (return · supply · ambient air on °C, humidity on %RH), power draw & COP, and a door-access EventTimeline pane (front · back · side doors, alarm past 5 min) — with cross-stack event-milestone annotations (header toggle), a Live / Paused control, a combined legend and the time-scale selector. New telemetry fields (ambient, COP, door state) reflected in SPEC-APP-PTL PTL-1, the Devices domain and Master ERD §5.
1.1	2 Jul 2026	Square card chassis. The device card (.pv-devcard) drops its corner radius — border-radius:0 on the chassis, header and rail (§5.2 + the §3 wireframe) — aligning the inventory with the square shell-chrome idiom. Prototype (apps/portal/portal.css) updated the same turn; cross-referenced from SPEC-APP-PTL v0.20.
1.0	1 Jul 2026	First issue — the device monitoring system specified across its three surfaces as built: the device inventory (command bar with the live/offline feed indicator, inline autocomplete search, the ten-field sort dropdown and the DS-control filter dropdown, the responsive paged card grid), the device card anatomy and the live tile realtime contract (tween cadence, sparkline streaming, hidden-tab & offline & reduced-motion pausing), the online/offline feed behaviour (incl. the prototype Tweak), the device detail (header, tabs, persistent summary column, telemetry time-series + cooling modules, the device twin / configuration, maintenance / alarms / activity tabs), the alerts & alarms surface, the device-state vocabulary, role gating, full design-system mapping, responsive & accessibility, as-built vs targets, and traceability. A presentation view over a settled model — no new entities or fields. Added to the User interface experience family (SPEC-UIX-DEV) and registered in docs-nav + the design index.