Owner/Admin Telemetry Control Workspace - Design

Date: 2026-05-10
Status: Approved in brainstorming, written for review

1. Goal

Build a new owner/admin workspace for operational decision-making where users can:

choose a farm as the working context
inspect telemetry from multiple source devices in that farm
keep a temporary set of telemetry sources pinned in the current session
open control actions for one target device at a time
decide control actions after comparing telemetry from other devices

This is not a KPI dashboard. It is an operational workspace for “observe first, then control”.

Source and target devices do not need to belong to the same pond. The guaranteed shared boundary for one session is:

same organization
same selected farm

2. Product decision summary

The approved direction is:

audience: owner and admin first
layout: table + drawer
control granularity: one target device at a time
control confirmation: no modal confirmation for normal actions
telemetry scope: flexible; user can inspect other devices before controlling
context boundary: devices must stay within the same organization and same farm
mobile support: required from the start

Additional approved behavior:

if the user can access exactly one farm, the page auto-selects that farm and loads immediately

3. Scope

In scope

new dedicated route for the workspace
owner/admin navigation entry to that route
farm selection as the root context for the page
device table with telemetry and control entry points
telemetry drawer for source inspection
control drawer for a single target device
session-only pinned telemetry sources
responsive behavior for desktop and mobile
permission-aware visibility and disabled states

Out of scope

replacing the existing /devices dashboard or DeviceDetail page
saved personal layouts or persistent workspaces
bulk control actions
cross-farm comparison in a single session
command history as a phase 1 launch requirement
technical assignment logic
technical/staff workspace support in phase 1
firmware or protocol changes
new automation logic

Add a dedicated route:

/devices/operations

Reasoning:

it keeps the feature under the existing devices domain
it avoids overloading /dashboard with an operational workspace
it leaves /devices and /devices/:id intact for overview and deep-dive flows

Add a new sidebar item for owner and admin:

label: Vận hành thiết bị
path: /devices/operations
required permission: device:read:*

This item should sit near the existing device entries, not under role dashboards.

5. User experience model

The page is a farm-scoped workspace with three layers:

farm context
device table
context drawer for telemetry or control

The page should answer two different questions without forcing the user into DeviceDetail:

“What are the current readings across the devices I care about?”
“Given those readings, should I send a control command to this target device?”

6. Layout

6.1 Desktop

Desktop uses a single main table with a right-side drawer.

Top toolbar:

farm selector
search by device name or serial
filters for status, pond, type, and “controllable only”
pinned telemetry source strip

Main content:

unified device table

Right drawer:

telemetry mode
control mode

Only one drawer is open at a time. Telemetry can switch between pinned sources without closing the workspace.

6.2 Mobile

Mobile keeps the same information hierarchy but collapses the interaction pattern:

toolbar becomes stacked controls
table becomes a mobile-friendly list/table hybrid
telemetry opens in a bottom sheet or full-screen drawer
control opens in a separate bottom sheet or full-screen drawer
pinned telemetry sources show as horizontally scrollable chips

The design must not rely on two visible panes at once.

7. Device table design

The table is the primary navigation surface.

Each row should expose enough operational context for quick decisions:

device name
serial number
device type
pond, if available
online/offline/error state
last seen
active alert count
capabilities summary:
- has telemetry
- controllable

Each row should expose actions independently:

View telemetry
Control
Open detail

Rules:

View telemetry is available when the device has telemetry support
Control is available only when the device is controllable and the user has control permission
if the device is controllable but offline, the action may still open the control drawer, but the submit controls are disabled

8. Telemetry drawer

Purpose:

inspect a source device quickly
compare current or recent telemetry before acting elsewhere in the same farm

Header:

device name
serial number
farm
pond, if available
online/offline state
last updated timestamp

Body:

latest telemetry summary
short-range chart
active alerts summary
telemetry freshness indicator

Actions:

Pin source
Unpin source
Open detail

Pinned telemetry behavior:

users can pin multiple telemetry sources in the same farm
pinning is session-only in phase 1
one pinned source is active at a time in the drawer
switching active source should be fast and not reload the whole page

9. Control drawer

Purpose:

send commands to one target device after reviewing telemetry elsewhere

Header:

device name
serial number
controllable capability summary
connection state

Body:

current IO or control state
per-control widgets based on device capabilities
warning text if the device is offline or the command cannot be sent

Actions:

send command immediately
show result inline and through toast
keep drawer open on failure

Constraints:

only one control target is active at a time
no bulk control in phase 1
no confirmation modal for standard actions
higher-risk actions already present in current components, such as “turn all off”, can remain explicit button actions without adding a blocking modal

10. Farm selection behavior

Farm selection is mandatory for data scoping.

Behavior:

if the user has access to exactly one farm, auto-select it and load the workspace immediately
if the user has access to multiple farms, show an uninitialized state until a farm is selected
if the user has no accessible farms, show a dedicated empty state

When the farm changes:

clear the pinned telemetry sources
clear the active telemetry source
clear the active control target
reload the device table for the new farm

This prevents cross-farm state leakage.

11. State model

The frontend workspace state should be explicit and local to this page:

selectedFarmId
filters
search
pinnedTelemetrySourceIds
activeTelemetrySourceId
activeControlTargetId
drawerMode as telemetry | control | closed

Phase 1 should not persist this state to the backend.

Optional enhancement later:

sync selected farm and filters to the URL query string

This is useful but not required for the first delivery.

12. Data model and API expectations

The page should prefer aggregation-oriented reads instead of stitching everything from DeviceDetail.

12.1 Farm access

The page needs a farm list filtered to farms the current user can access.

12.2 Workspace device dataset

The device table should be backed by a farm-scoped dataset that includes:

id
name
serialNumber
type
pond summary
status
lastSeenAt
activeAlertCount
telemetrySupport flag
controllable flag
control capability summary

This can come from:

a new workspace endpoint, or
a composition of existing device endpoints if the current contracts are sufficient

Recommended direction:

prefer a dedicated read model endpoint for this workspace if current endpoints cause too many follow-up requests

12.3 Telemetry reads

Telemetry drawer reads can reuse the existing telemetry history and latest telemetry contracts where possible.

12.4 Control writes

Control drawer should continue using the existing control command endpoint and backend permission checks as the source of truth.

Phase 1 explicitly does not require:

a new generalized commandType/payload contract
command history writes or reads
technical-device maintenance assignment

13. Permission model

Page access:

requires device read permission

Telemetry action:

requires the same read access the user already has for that device

Control action:

requires control permission and device-level backend authorization

UI rules:

hide or disable control actions when the user cannot control the device
do not assume visibility implies controllability
backend remains authoritative for final allow/deny behavior

14. Error and edge-case handling

14.1 Offline target device

allow the control drawer to open
show current known state if available
disable submit actions
explain why control is unavailable

14.2 No recent telemetry

telemetry drawer still opens
show empty data messaging with last updated information
do not treat stale or absent telemetry as a hard error

14.3 Control failure

keep the user in context
show inline error plus toast
do not clear pinned telemetry state

14.4 Farm switching

reset session workspace state before loading the next farm

14.5 Slow read states

table should have a proper loading state
drawer content should show skeletons or loading placeholders independently
one slow telemetry read must not block the entire page

15. Integration with existing screens

This workspace should reuse and adapt existing pieces where practical:

telemetry rendering patterns from DeviceDetail
control widgets from GatewayControlPanel
device links to /devices/:id

But it should not embed DeviceDetail wholesale. The workspace needs:

lighter context reads
faster switching
a session model with pinned telemetry sources

16. Testing strategy

16.1 Frontend behavior tests

auto-selects the farm when only one farm is accessible
waits for manual farm selection when multiple farms exist
clears pinned state when switching farms
opens telemetry drawer from a source row
pins and switches between telemetry sources
opens control drawer for a target device
disables control submission for offline targets
hides or disables control for users without control permission

16.2 Responsive tests

desktop drawer flow works with table as the main surface
mobile opens telemetry and control in sheet/drawer patterns without broken navigation

16.3 Backend contract verification

workspace reads stay farm-scoped
telemetry reads stay organization and farm safe
control writes still enforce backend authorization

17. Rollout plan

Phase 1:

route
owner/admin navigation entry
farm selector with auto-select for single-farm users
device table
telemetry drawer
control drawer
session-only pinned telemetry sources
reuse of the existing POST /devices/:id/control backend path

Phase 2 candidates:

richer telemetry comparison views
URL-synced filters
saved workspaces
role expansion beyond owner/admin
command history
generalized control contract if current gateway control is no longer sufficient
technical assignment and technical-role support

18. Success criteria

The design is successful when:

owner/admin can enter one workspace and choose a farm quickly
users can inspect telemetry from multiple source devices before controlling a target device
users can keep telemetry context pinned while switching targets
the page works cleanly on mobile and desktop
the page reduces the need to bounce between multiple DeviceDetail pages for routine operational decisions