OpenSonde

Appearance

OpenSonde Product and System Specification ​

1. System Overview ​

OpenSonde is an IoT environmental telemetry platform with two runtime applications:

  • OpenSonde.API (ingestion API): receives telemetry payloads from authenticated devices and persists readings.
  • OpenSonde.App (MVC web app): provides authenticated users with dashboards, device/site management, readings views, and account management.

The shared data model and utilities live in OpenSonde.Shared, and both API + MVC applications use the same PostgreSQL-backed EF Core OpenDbContext.

2. Architecture Split ​

2.1 API (OpenSonde.API) ​

Purpose:

  • Device-facing ingestion endpoint.
  • Device-token authentication.
  • API docs via Swagger.

Key components:

  • Authentication/DeviceAuthHandler.cs
    • Validates Bearer token against device_tokens + devices.
    • Attaches claims for device id, site id, and device model id.
  • Controllers/ReadingsController.cs
    • POST /api/readings: writes readings + reading values, updates devices.last_seen, devices.last_reading_date, battery, optional coordinates, and sites.date_last_reading.
    • GET /api/readings: internal/debug endpoint returning recent readings for authenticated device.

Operational tooling:

  • Sentry tracing enabled.
  • Swagger/OpenAPI enabled.
  • Kestrel min request body data rate disabled (supports constrained/slow devices).

2.2 MVC App (OpenSonde.App) ​

Purpose:

  • Human user UI for monitoring and management.
  • Cookie-authenticated web workflows.

Key components:

  • Cookie auth (/login, /logout) and session-backed user context.
  • Feature modules via controllers:
    • HomeController: home + recent devices.
    • AuthController, PasswordController: login, logout, forgot/reset password (tokenized).
    • DevicesController: device list/detail/overview/readings/parameters.
    • SitesController: site list/create/view/settings/parameters/devices/alerts.
    • SiteReadingsController: manual site reading import.
    • DashboardsController: create and edit tile-based dashboards.
    • AccountController: profile + organisation management.
    • IncidentsController: incidents index placeholder page.

Frontend:

  • Razor views with partials.
  • HTMX-style partial loading for dynamic readings table updates.
  • JS/CSS assets bundled via Vite/Tailwind/Sass pipeline.

2.3 Shared Library (OpenSonde.Shared) ​

Purpose:

  • Canonical entities (Device, Reading, ReadingValue, Site, Dashboard, etc.).
  • EF Core OpenDbContext.
  • Shared utilities/services:
    • TimeHelper (including custom Epoch 2025 conversion).
    • IMU/unit helpers.
    • Email and encryption services.
    • common enums/constants/extensions.

3. Feature Inventory ​

3.1 Authentication and Security ​

Implemented:

  • User login/logout with persistent auth cookie.
  • Password reset flow with expiring protected token.
  • Optional Cloudflare Turnstile validation on login and forgot-password.
  • Device bearer token auth for ingestion API.
  • Data protection key persistence for token/cookie protection.

Authorization model:

  • Resource-based authorization handlers for:
    • Site access.
    • Device access (including organisation member ownership checks).
    • Organisation edit permissions (owner/admin).

3.2 Account and Organisation ​

Implemented:

  • User profile editing (first name, last name).
  • Organisation overview and member listing.
  • Organisation name update when authorized.

3.3 Device Management and Monitoring ​

Implemented:

  • Device list for owned + organisation-related devices.
  • Device detail page with:
    • last reading snapshot,
    • online/offline state,
    • missed heartbeat estimate,
    • 24h sparkline-ready series.
  • Device overview editing (device name).
  • Device parameter list (read-only in current version).

Readings table capabilities ​

Implemented:

  • Paginated table with infinite-scroll style loading.
  • Range filters: 1h, 24h, 7d, and custom datetime range.
  • Column metadata from device_parameters.
  • Numeric sorting for sortable columns.
  • Row detail expansion with timestamp + GPS.
  • Column visibility modal controls.

3.4 Site Management ​

Implemented:

  • Site list and create site.
  • Site overview (latest readings, count, location, metadata).
  • Site settings edit (name/description/location).
  • Site parameter management (add parameter type per site).
  • Site devices listing.
  • Alerts view scaffold.

3.5 Site Reading Import (Manual) ​

Implemented:

  • Manual import form for site readings.
  • Writes site_readings + site_reading_values.
  • Captures UTC DateTaken and optional notes.

3.6 Dashboards ​

Implemented:

  • Dashboard list.
  • Create new dashboard.
  • Tile-based page with persisted layout metadata.
  • Add text tile operation.
  • Update tile layout operation.
  • Update tile content operation.

3.7 Auditing and Activity ​

Implemented:

  • Audit log writes for account events (e.g., failed login, login).
  • Recently viewed device tracking used on home page.

3.8 Observability and Operations ​

Implemented:

  • API Sentry tracing.
  • Swagger docs + endpoint explorer.
  • Dockerfiles for API and App runtimes.

4. Data and Time Handling ​

  • Device telemetry timestamps are derived from a custom Epoch 2025 UTC reference.
  • Core operational timestamps (last_seen, audit dates, etc.) are written in UTC.
  • MVC custom range inputs are interpreted and normalized to UTC before filtering.

5. Notable Current Constraints (from code/TODOs) ​

  • Some endpoints still contain TODOs (for example, stricter auth checks in specific site/dashboard paths).
  • Device parameters are intentionally read-only in the current UI.
  • Validation hardening remains for some import/ingestion edge cases.
  • Dashboard sharing/collaboration appears not yet implemented.

6. Repository Map (High Level) ​

  • OpenSonde.API: device ingestion API.
  • OpenSonde.App: web MVC application.
  • OpenSonde.Shared: entities, data context, shared services/utilities.
  • docs/opensonde-spec.md: this specification.