Telemetry Service Architecture

Bounded context: Telemetry Ingestion · Stack: Rust / Axum / Postgres + TimescaleDB · Code-level walkthrough: Telemetry Service

The telemetry realises the Telemetry Ingestion context. It is the platform’s ingestion gateway, and its architecture answers two independent pressures: absorbing new sensor types without touching the core, and keeping every I/O technology out of the logic that decides what a reading means.

Architectural Style

Hexagonal (ports & adapters) and microkernel on orthogonal axes. They are not competing patterns here; each governs a different direction of change.

The Node predecessor had the microkernel half only. Its modules owned their own persistence and Redis calls, so infrastructure reached into every metric implementation.

Layers

The kernel never names a plugin. Every metric-specific decision is reached through a &dyn SensorPlugin resolved from PluginRegistry, so a new metric is a new file plus one registration line in main.rs.

tests/architecture.rs enforces the table: no crate::plugins or crate::adapters under src/kernel, no I/O crate under src/kernel or src/types, and no plugin importing a sibling.

graph TD
    subgraph Driving
        HTTP[HTTP API]
        KC[Kafka registration consumer]
    end
    subgraph Kernel
        K[Use cases: ingest, readings, thresholds, sensors, actions, registration]
        R[PluginRegistry]
    end
    subgraph Plugins
        T[temperature]
        P[peopleCount]
        A[airQuality]
    end
    subgraph Driven
        PG[(Postgres + Timescale)]
        RD{{Redis pub/sub}}
        KP[Kafka producer]
        TW[digital-twin directory]
        DEV[Device ACL]
    end
    HTTP --> K
    KC --> K
    K --> R
    R --> T
    R --> P
    R --> A
    K --> PG
    K --> RD
    K --> KP
    K --> DEV
    HTTP -.->|authz| TW

Components & Connectors diagram

Key Architectural Decisions

• One plugin per metric, declaring everything. MetricDescriptor names the fields, their kinds, the unit, and which field becomes value; bounds() names the threshold keys; actions() names what the metric can be told to do. GET /contracts and POST /ingest are driven by the same declaration, so the catalog and the validator cannot drift.
• Ports for every technology. The kernel holds Arc<dyn ReadingStore>, not a PgPool. The whole kernel is unit-tested against in-memory fakes with no database in sight.
• Persist before publish. A reading reaches Postgres before it reaches Redis, so no consumer sees an event that is not yet queryable. Publishing is fire-and-forget: a broker failure is logged and never fails an ingest that already landed.
• Threshold scope is a column, not a nesting depth. room_id NULL means building-level; a room-level row wins during resolution. Room thresholds cannot be silently dropped.
• Room thresholds are set in one request, not one per room. PATCH /thresholds/{sensorType}/buildings/{id}/rooms takes a map of room id to bounds. Registering a building sets a threshold for every room at once, and one request per room made that both the bulk of the round trips — each paying its own edge auth — and partially appliable. Every patch is validated before any is written, so a rejected bound stores nothing. The writes are still one upsert per room: the store has no transactional bulk write, and a mid-write failure is rare and idempotent to retry.
• Device vocabulary lives behind one port. ActionDispatch takes a Command in our own vocabulary; URLs, methods and field names exist only in the dispatch adapter. See Sensor Actions & the Device ACL.
• Authorization asks the owner. Building-to-domain lookups go to digital-twin over its existing endpoint rather than into a local copy of someone else’s data; a failed lookup denies.

Integration

• Owns telemetry-db (Postgres + TimescaleDB); no other service reads it. Retention and rollup policy in Telemetry Storage & Retention.
• Publishes every accepted reading to Redis telemetry:raw, and every threshold breach to the Kafka alerts topic keyed buildingId:roomId, with no reference to whichever service consumes them. Breaches are enqueued, never awaited (send_result), so a broker outage cannot stall /telemetry/ingest.
• Receives a threshold baseline from digital-twin: over Kafka for a new building’s registration, over REST (PUT /thresholds/buildings/:id) for every later edit. Both are driving adapters over the same registration use case.
• Exposes a self-describing metric catalog to dashboard at GET /contracts, now including each metric’s available actions.
• Scraped at /metrics. See Observability.

For the request lifecycle, the plugin template, the extension guide, and the API, see the Telemetry Service internals page.