Device Control Backend Foundation for Workspace - Design

Date: 2026-05-10
Status: Revised to align with the owner/admin telemetry control workspace design

1. Goal and scope

This design defines the backend foundation for the telemetry-first control workspace that will ship as:

route: /devices/operations
audience in phase 1: owner and admin

The product flow is:

user selects a farm
user inspects telemetry from one or more source devices in that farm
user sends control commands to one target device at a time

This document is backend-focused. It is intentionally split into:

phase 1 backend prerequisites needed to ship the owner/admin workspace
phase 2 backend extensions that support broader control workflows later

2. Alignment decisions

The following decisions are fixed and must stay aligned with the workspace design:

phase 1 keeps the existing control endpoint contract
phase 1 does not require a new generalized commandType/payload write contract
phase 1 does not require technical-device maintenance assignment
phase 1 does not require command history for the workspace to launch
the control workspace is a dedicated devices-domain route, not a role dashboard page

3. Phase 1 scope

In scope

preserve and reuse the current POST /api/v1/devices/:deviceId/control behavior
preserve current backend permission enforcement as the source of truth for control writes
provide farm-scoped reads needed by the workspace
support farm selection with auto-select behavior when only one accessible farm exists
support telemetry reads and device metadata reads needed for a table + drawer UI

Out of scope

changing the control write contract in phase 1
command history persistence or history API as a launch blocker
technical assignment rules
technical/staff workspace support
device firmware or protocol changes

4. Phase 1 authorization model

The phase 1 workspace targets owner and admin users only.

Backend rules for phase 1:

page-level access depends on read access to devices in the selected farm
telemetry reads use existing read authorization
control writes continue to use the existing POST /devices/:id/control authorization path
backend remains authoritative for final allow or deny behavior per device

Phase 1 does not add technical-specific assignment checks.

5. Phase 1 backend architecture

5.1 Workspace read model

The workspace needs a farm-scoped dataset that is cheaper than opening many DeviceDetail pages.

The backend should provide either:

a dedicated workspace read endpoint, or
a composition-friendly set of existing endpoints that can return the following without excessive round trips:
- device identity
- device type
- pond summary
- status
- last seen
- active alert count
- telemetry support
- controllable flag
- control capability summary

Recommended direction:

prefer a dedicated farm-scoped workspace read model if current endpoints force too many follow-up requests

5.2 Farm access read path

The frontend needs a list of farms the current user can access.

Behavior expectations:

if exactly one farm is returned, the UI can auto-select it
if multiple farms are returned, the UI waits for explicit user selection
if no farms are returned, the UI shows an empty state

5.3 Telemetry read path

The workspace should reuse existing telemetry APIs where practical:

latest telemetry
telemetry history
alert summaries if already available

No new telemetry write behavior is needed for this design.

5.4 Control write path

Phase 1 reuses the existing control endpoint:

POST /api/v1/devices/:deviceId/control

This endpoint remains the write source of truth for the workspace.

Phase 1 does not require replacing the current payload shape. Any current device-specific control limitations remain acceptable for launch as long as they satisfy the owner/admin workspace use case.

6. Phase 1 API contract expectations

6.1 Farm access

The backend must expose a way to fetch accessible farms for the current user.

6.2 Workspace device dataset

The backend must expose a farm-scoped read model, either explicitly or through acceptable existing endpoints, that supports:

filtering by farm
listing devices with enough metadata for the workspace table
identifying which devices have telemetry
identifying which devices are controllable

6.3 Telemetry reads

The workspace may continue to use the current telemetry history and latest telemetry contracts in phase 1.

6.4 Control writes

The workspace continues using:

POST /api/v1/devices/:deviceId/control

No generalized commandType/payload contract is introduced in phase 1.

7. Phase 1 error handling

400 Bad Request: invalid control payload under the current endpoint contract
401 Unauthorized: unauthenticated user
403 Forbidden: user can read but cannot control this device
404 Not Found: device or farm-scoped resource is not accessible
500 Internal Server Error: unexpected read or dispatch failure

Behavioral expectations:

telemetry absence or staleness is not a hard backend error
control failure should not require the frontend to reset workspace state

8. Phase 1 testing strategy

8.1 Read-side tests

farm access list is scoped correctly
single-farm users receive exactly one accessible farm
workspace device reads remain organization and farm scoped
controllable flags are returned consistently with existing backend rules

8.2 Control tests

owner/admin with valid control permission can send commands
user without control permission is denied
cross-organization access is denied
offline or unsupported device behavior remains consistent with the current endpoint contract

9. Phase 2 backend extensions

These are still valid ideas, but they are explicitly deferred until after the owner/admin workspace is live.

9.1 Generalized command contract

Possible future direction:

introduce a generalized control DTO such as commandType/payload
support more than the current gateway-specific control shape

This should be done only when there is a concrete device capability need that the current endpoint cannot serve cleanly.

9.2 Centralized control authorization service

Create a dedicated canControl(user, device) style service when broader role expansion justifies it.

Use cases:

consistent authorization reasons
reuse across multiple controllers and read models
future technical-role support

9.3 Command history

Possible future additions:

device_control_commands audit table
paginated history endpoint filtered by farm, device, and time range
UI history table or history tab inside the workspace

This is useful, but not required to ship phase 1.

9.4 Technical assignment