Skip to content
SENS Platform Docs

System Overview

Purpose

Section titled “Purpose”

This platform is a tenant-aware IoT and telemetry platform.

The initial use case is LoRaWAN telemetry ingestion. Devices send data to an external Network Server. The Network Server decrypts the LoRaWAN payloads and forwards them to this platform over MQTT.

The platform receives the MQTT messages, stores raw payloads for a limited time, decodes payloads through versioned decoders, stores normalized measurements for long-term retention, and exposes telemetry through UI, API, and CSV exports.

Initial Network Server

Section titled “Initial Network Server”

The initial Network Server is Netmore.

Payload details are not yet part of the initial architecture baseline and must be documented before the MQTT ingestion implementation begins.

V1 Goals

Section titled “V1 Goals”

V1 must provide:

  • Tenant management.
  • Flexible organization structure inside tenants.
  • User and role management.
  • Device registry for sensors.
  • Optional gateway registry.
  • Device type management.
  • MQTT ingestion from the Network Server.
  • Durable internal processing.
  • Raw payload storage for approximately one month.
  • Normalized telemetry storage for at least five years.
  • Versioned TypeScript-based decoders.
  • Basic fixed UI views.
  • Telemetry API.
  • Asynchronous CSV export.
  • Kubernetes and Helm deployment.
  • Local development environment.
  • Repository-local documentation.

V1 Non-Goals

Section titled “V1 Non-Goals”

V1 does not include:

  • Device commands.
  • Full Network Server synchronization.
  • Free-form dashboard builder.
  • Alarm/rule engine.
  • Maps.
  • Firmware management.
  • Runtime user-uploaded scripts.
  • Multi-region deployment.
  • Air-gapped customer installation.
  • Full customer self-installation.

Main Components

Section titled “Main Components”

web-console

Section titled “web-console”

React-based user interface.

Responsibilities:

  • Login flow.
  • Tenant and organization views.
  • User and role management.
  • Device management.
  • Device type management.
  • Telemetry views.
  • CSV export request UI.

platform-api

Section titled “platform-api”

Main HTTP API.

Responsibilities:

  • Authentication integration.
  • Authorization.
  • Tenant and organization APIs.
  • User and membership APIs.
  • Device APIs.
  • Device type APIs.
  • Telemetry query APIs.
  • Export APIs.
  • Admin APIs.
  • Audit logging.

mqtt-ingestion-worker

Section titled “mqtt-ingestion-worker”

Worker that connects to the external MQTT broker of the Network Server.

Responsibilities:

  • Maintain MQTT connection.
  • Subscribe to configured topics.
  • Validate minimal message envelope.
  • Add ingestion metadata.
  • Publish raw messages to the internal stream.
  • Log and metric ingestion behavior.

telemetry-worker

Section titled “telemetry-worker”

Worker that processes internal raw telemetry messages.

Responsibilities:

  • Match messages to devices.
  • Enforce tenant scope.
  • Store raw payloads.
  • Execute the correct decoder version.
  • Store normalized measurements.
  • Handle decoder errors.
  • Handle unknown devices.
  • Handle duplicate messages.
  • Emit metrics and structured logs.

PostgreSQL/TimescaleDB

Section titled “PostgreSQL/TimescaleDB”

Primary database.

Responsibilities:

  • Relational data.
  • Tenant and organization data.
  • Users and memberships.
  • Devices and device types.
  • Decoder metadata.
  • Raw ingestion messages.
  • Long-term normalized telemetry.
  • Export jobs.
  • Audit logs.

Internal Message Broker

Section titled “Internal Message Broker”

Durable internal buffer between MQTT ingestion and telemetry processing.

Selected V1 broker: NATS JetStream.

Responsibilities:

  • Absorb temporary processing failures.
  • Allow retry.
  • Allow controlled consumer processing.
  • Expose backlog and processing delay.
  • Support dead-letter handling.

High-Level Data Flow

Section titled “High-Level Data Flow”
  1. LoRaWAN device sends data.
  2. Netmore receives and decrypts the payload.
  3. Netmore publishes MQTT message.
  4. mqtt-ingestion-worker receives the MQTT message.
  5. Worker publishes normalized raw ingestion event to internal stream.
  6. telemetry-worker consumes the event.
  7. Worker finds the device by DevEUI or configured external identifier.
  8. Worker stores raw payload.
  9. Worker executes decoder for the device type and decoder version.
  10. Worker stores normalized measurements.
  11. UI/API can query measurements.
  12. Export jobs can create CSV exports asynchronously.

Core Design Principles

Section titled “Core Design Principles”
  • Tenant boundaries are hard security boundaries.
  • Organization units represent flexible customer, region, branch, site, or other internal structures.
  • Device ingestion must tolerate duplicates, delayed messages, and out-of-order messages.
  • Decoder execution must be safe and versioned.
  • Telemetry queries must be bounded.
  • Exports should run asynchronously.
  • Documentation and contracts must stay in sync with code.