Architecture
WebSocket Telemetry
Q-OS is designed to operate offline, but when a network is available, it provides a high-performance WebSocket telemetry stream at /api/v1/stream. This powers the Admin HUD with zero-latency updates.
#NDJSON Event Formats
Events are streamed as Newline-Delimited JSON (NDJSON) over the WebSocket. There are three primary event types:
1. STATE_MUTATION
Fired whenever a WASM module calls qos_sdk::state::set.
{
"type": "STATE_MUTATION",
"key": "guestbook:visits:total",
"old_value": [42],
"new_value": [43],
"timestamp": 1718223401000
}2. EXECUTION_RECEIPT
Fired when a WASM module successfully completes execution and returns a receipt.
{
"type": "EXECUTION_RECEIPT",
"module_id": "@official/guestbook",
"latency_ms": 1.2,
"receipt": { "status": "checked_in", "guest": "Alice" },
"timestamp": 1718223401001
}3. SYSTEM_BROADCAST
Fired explicitly by a module using the broadcast ABI (e.g. for low inventory alerts).
{
"type": "SYSTEM_BROADCAST",
"level": "WARNING",
"message": "SKU_0912 stock is below 5 units",
"timestamp": 1718223401005
}