Skip to content

architecture.md

Latest commit

 

History

History
58 lines (45 loc) · 2.86 KB

architecture.md

File metadata and controls

58 lines (45 loc) · 2.86 KB
Raw

Architecture

Nomyk-style devices are best understood as small edge systems. They read a plant's environment, normalize noisy physical signals, report telemetry, and provide local feedback when the network or application is not nearby.

This public reference uses a four-layer model:

  1. Hardware adapters read physical sensors and expose typed readings.
  2. Domain services calibrate, classify, and summarize those readings.
  3. Device runtime schedules sampling, persistence, networking, and local status.
  4. Cloud boundary receives telemetry and returns non-secret configuration.
flowchart LR
  Sensors[Sensor hardware] --> Adapters[Sensor adapters]
  Adapters --> Calibration[Calibration and normalization]
  Calibration --> Runtime[Device runtime]
  Runtime --> Status[Status light]
  Runtime --> Telemetry[Telemetry envelope]
  Telemetry --> Cloud[Cloud ingestion boundary]
  Cloud --> Config[Device config]
  Config --> Runtime
Loading

Design Principles

  • Stable contracts over exact implementation. Public schemas describe the long-lived data shape, not production service internals.
  • Adapters at the edge. ADC, I2C, and one-wire details stay behind sensor interfaces.
  • Calibration is a first-class lifecycle. Raw values are preserved, but product decisions use calibrated values.
  • Local feedback matters. LED states communicate health, setup, and fault conditions even when the app is unavailable.
  • Cloud is a boundary. The public model describes concepts like ingestion and command delivery without naming private infrastructure.

Runtime Loop

The reference device loop follows a predictable rhythm:

  1. Load device configuration and calibration profile.
  2. Read sensors using hardware-specific adapters.
  3. Convert raw readings into normalized values.
  4. Classify plant and device health.
  5. Update local status light state.
  6. Package telemetry with timestamps, firmware metadata, and quality flags.
  7. Publish to a cloud ingestion boundary when connectivity is available.
  8. Persist enough local state to recover after power loss.

Modules

Module Responsibility
Sensor adapters Convert hardware reads into typed raw readings.
Calibration Map raw signals into normalized units and confidence.
Telemetry Create versioned messages with readings and device metadata.
Status light Turn health and lifecycle events into LED states.
Config Store safe device preferences such as sample interval and quiet hours.
Cloud boundary Exchange telemetry and configuration without exposing backend details.

What Is Deliberately Omitted

This repository avoids production-specific auth, provisioning, private MQTT topics, internal database structure, backend routes, hardware manufacturing details, and commercial firmware logic. Those details change over time and are not needed to explain the architectural core.