Portal — product requirements
portal.riversync.com — customer device monitoring: live telemetry, configuration and connection health for every RiverSync converged micro data center across your sites, whatever its model, plus the service that keeps it running.
1Devices the Portal monitors
RiverSync ships three product families across six models. The fleet is heterogeneous — generations, series and module counts differ — so telemetry shape differs by family and model. Every device on a customer's sites appears in the Portal regardless of family.
| Family | Models | In the field | Telemetry schema |
|---|---|---|---|
| frigo 20 · frigo 30 | Edge / small-site enclosures | Refrigeration family — established shape | |
| koelkast 20 · koelkast 30 | Larger enclosures, more cooling modules | Refrigeration family — wider module set | |
| nevera 30 · nevera 40 | Newest generation new to the model | Newer generation/series — additional fields |
2Telemetry data source
Product-facing summary only — the pipeline, schema registry and storage strategy are specified in the Devices domain (SVC-DVC, SVC-9). The Portal does not own this data; it reads it.
Each device emits three independent streams to RiverSync's ingest plane (mTLS, never through the user gateway): telemetry (the live readings), the device twin (reported state + desired configuration), and connection (online/offline transitions). Readings land in a time-series store outside the relational model — the ⚠ the ERD records under PTL-1 — and only Alert rows cross into Postgres. A device catalog maps each unit to its (family, schema-version) so the Portal renders the right metrics per device; a device with no registered schema is read unknown-safe — never silently null-mapped (see PTL-7).
3Requirements
Live device monitoring — the device list and per-device telemetry (temperature, power, PUE and per-module readings), health states and alert/alarm streams across all site locations. Devices is the Portal landing surface — there is no separate dashboard. Values stream live and tween in the UI; deltas shown are factual. Telemetry is served from the time-series store, not Postgres (the ERD ⚠). On device detail, the readings are read as a single full-width multi-metric time-series stack (one card, the DS TimeSeriesStack): several panes share one time axis with a synchronized crosshair, one overview brush for the whole period, and a header carrying event-milestone annotations (toggle), a Live / Paused control and a time-scale selector (5m · 30m · 1h · 1d · 1mo · 1y · 3y). The refrigeration schema stacks three panes — (1) air temperature & humidity: return-air, supply-air and ambient air on the left °C axis (with the setpoint band) and humidity on the right %RH axis (40–55% band); (2) power draw & COP: metered power (kW, area) on the left and the cooling COP on the right; (3) door access: the enclosure's front · back · side doors as open→close state bands that escalate to alarm past the 5-min threshold (a single door never opens again while already open). Event milestones line up across every pane. The converged/Nevera schema renders the same three panes plus its extra tiles (PUE, battery, bus voltage). Build-ready detail in SPEC-UIX-DEV §7.
Alarms are actionable — acknowledge, see cause and effect ("MDC-6610 return air at 41.4°C — 6.4°C above setpoint"), and open a ticket from the alarm. Alarms are read on the device detail's Alarms tab, scoped to that device — there is no standalone Alerts & alarms page (removed, prototype Jul 2026); cross-device alarm context is surfaced through the device list's attention ranking and the top-bar notification bell.
Per-device maintenance visibility — on the device detail's Maintenance tab (there is no standalone Maintenance menu — removed, prototype Jul 2026), each device shows its single active maintenance agreement — tier (Silver 8×5 NBD · Gold 24×7 ND), servicing partner, period and expiration — above the full list of its previous agreements, sorted latest to oldest. Renewals surface ahead of time (master PRT-2). Specified in the Maintenance PRD (SPEC-PRD-MNT, MNT-1/2).
Service & messaging — tickets are the single Service conversation surface: each ticket carries engineer visit scheduling and the message thread with RiverSync support or the servicing partner. Messages is merged into Tickets (prototype Jun 2026) — there is no separate Messages menu; the conversation lives inside the ticket. A customer opens a new ticket from the command bar through a comprehensive composer — affected device, category → sub-category, priority, subject & message, and image / log attachments — with live RiverSync Assist (suggested classification with one-click apply, mentioned-device detection, similar tickets, a recommended runbook); the opener and classification are recorded (OpenedByParty=customer, DM-60). The build-ready design of this multi-party surface — reused by the Admin (agent) and Partners apps — is specified in SPEC-UIX-TKT (entities ServiceTicket · TicketMessage, rules DM-55/56/60, SVC-19).
Role-gated — what a member sees and controls (acknowledge, configure, control equipment, firmware) follows the Portal column of Account's permission matrix.
Family & model identity — every device is shown with its family (Frigo · Koelkast · Nevera), model and serial. The family reads as the canonical family badge (PRO-17, SPEC-PRD-PRO §3) — capability-axis glyph on the family hue with the capability tooltip — never a generic icon or a text-only label. The device list is a card view — each card is a considered at-a-glance summary (not the full device detail): the header carries identity, status, family and firmware; a schema-aware telemetry panel shows the family's key readings with sparklines (refrigeration: return-air, supply-air & ambient temperature, humidity, power and efficiency; converged/Nevera: return, supply, ambient, PUE, power and battery); and a right rail organises the maintenance agreement (tier, servicing partner, term-progress bar and expiry) and active-alarm state (count + top alarms). Sorting and filtering live in dropdowns on the right of the device command bar. Sorting offers needs-attention · id · status · active alarms · site · family · model · firmware · agreement-expiry · commissioned with an order toggle; the list is paged. Filtering — built on the design-system form controls — covers family, status, one or more sites (tag autocomplete), maintenance tier and active-alarm state, plus free-text search which lives inline in the command bar as an autocomplete combobox (to the left of Sort): typing matches up to seven devices by id / model / site / serial — arrow keys navigate, Enter opens the highlighted device, Esc / ✕ clears — while the same text narrows the card grid live. The customer never needs to know about schema versions; the Portal resolves them. The build-ready detail of the command bar, sort/filter dropdowns and card is SPEC-UIX-DEV.
Schema-aware telemetry — metric and field sets differ per family, model and schema version (e.g. Nevera carries fields Frigo does not, and multi-module units report per module). The Portal renders the correct metric set for each device. A device whose schema is uncataloged or unregistered degrades gracefully: identity and connection state still show, its readings are marked unavailable rather than guessed, and it is flagged for RiverSync to catalog — never silently null-mapped or dropped.
Device twin visibility — each device shows its reported state (firmware version, operating mode, current setpoints) and, where permitted, its desired configuration. Configuration changes (setpoints, mode, firmware) are role-gated commands (PTL-5), always audited, and reconcile against the twin's reported state.
Connection state — online/offline, last-seen and link health come from the connection stream. Offline devices are visibly distinct, telemetry gaps are explained by connection loss rather than read as zeroes, and a device going offline can itself raise an alert (PTL-2). The Portal's own live telemetry feed (a WebSocket) carries its state in a command-bar Live / Offline indicator: online it is success-toned and the broadcast icon pulses; offline it is neutral and static, and all real-time motion pauses (card tile tweens and sparkline streaming hold their last value — nothing is read as zero). Presentation, cadence and the reduced-motion / hidden-tab pausing are specified in SPEC-UIX-DEV §6.
History — telemetry is browsable over selectable time windows (with the time-series brush). On device detail the brush drives the whole multi-metric stack at once (PTL-1) — dragging it selects one period across every pane and pauses the live feed. The prototype simulates a continuous 3-year record per device at adaptive resolution (dense recent, coarse far back), so a scale from 5m to 3y reads the same history — fine live detail up close, seasonal cycles across years. History depth follows the time-series store's retention; any gap from the legacy-store cutover is surfaced, not hidden. Data export is not offered — the Portal provides no telemetry or device-inventory export function.
Service scheduling — the customer agrees the visit time. The Portal's Schedule surface lets the customer (a) set standing scheduling preferences — preferred service windows, blackout dates and a minimum lead time, org-wide or per site — and (b) review the time options RiverSync proposes for each corrective, maintenance or preventive visit and select one (or decline all and request alternatives). The selected slot schedules the visit for Field execution. The propose → select model and its entities are specified in SPEC-PWF-SCH (VisitProposal · VisitProposalOption · SchedulingPreference, DM-57…59); the counterpart sides are Admin ADM-7 (RiverSync proposes) and Partners PAR-15 (the servicing partner works its assigned visits within scope). The surface is the shared PV.Schedule engine (persona=customer), specified in SPEC-UIX-SCH. Acting — setting preferences, accepting a slot — is role-gated to Editor or above (PTL-5); all four roles can view the schedule.