schema_version: 1
model:
  id: iot-telemetry
  name: IoT Telemetry
  description: >
    An arc42 example: a fictional heat pump maker collects device telemetry
    over MQTT, stores it, raises alerts and shows it to operations and customers.
    Where the 12 arc42 sections live:
    1 introduction and goals, 2 constraints, 4 solution strategy,
    11 risks and 12 glossary are cards on this overview;
    3 business context is this overview, technical context in 0300-context;
    5 building blocks in 0500-building-blocks (black boxes in the registry);
    6 runtime in 0600-runtime; 7 deployment in 0700-deployment;
    8 crosscutting concepts a card on 0500-building-blocks/level-1;
    9 decisions in decisions/; 10 quality tree in 1000-quality.
diagram_type: architecture
meta:
  title: Business context
  output: main.html
components:
  - ref: homeowner
    pos: [40, 60]
    size: [130, 60]
  - ref: ops-engineer
    pos: [40, 160]
    size: [130, 60]
  - ref: installer
    pos: [40, 260]
    size: [130, 60]
  - ref: telemetry-platform
    pos: [280, 160]
    size: [150, 60]
  - ref: heat-pump
    pos: [540, 60]
    size: [130, 60]
  - ref: push-service
    pos: [540, 160]
    size: [130, 60]
  - ref: service-desk
    pos: [540, 260]
    size: [130, 60]
connections:
  - { from: homeowner, to: telemetry-platform, label: checks }
  - { from: ops-engineer, to: telemetry-platform, label: monitors }
  - { from: installer, to: telemetry-platform, label: registers }
  - { from: heat-pump, to: telemetry-platform, label: telemetry, variant: emphasis }
  - { from: telemetry-platform, to: push-service, label: alerts }
  - { from: telemetry-platform, to: service-desk, label: tickets }
cards:
  - dot: orange
    title: 1.1 Requirements
    items:
      - Collect telemetry from every heat pump every 30 s
      - Alert homeowner and ops on fault codes
      - Show live and historic data in app and dashboard
      - Register and provision new devices on site
  - dot: cyan
    title: 1.2 Quality goals
    items:
      - Reliability, no telemetry lost once accepted
      - Timeliness, alert within 60 s of a fault
      - Security, every device authenticated
  - dot: emerald
    title: 1.3 Stakeholders
    items:
      - "Homeowner: sees status, gets alerts quickly"
      - "Ops engineer: fleet view, few false alarms"
      - "Installer: register a device in minutes"
      - "Firmware partner: stable MQTT contract"
  - dot: slate
    title: 2 Constraints
    items:
      - Devices speak MQTT only; firmware by a partner
      - Data stays in one EU region
      - Team of six; PostgreSQL skills in house
  - dot: amber
    title: 4 Solution strategy
    items:
      - MQTT with mutual TLS for devices (security, ADR 0001)
      - TimescaleDB for telemetry, SQL everywhere (ADR 0002)
      - Ingest acks only after commit (reliability)
      - Rules engine on the ingest stream (timeliness)
      - Split by flow, ingest vs read vs provisioning
  - dot: rose
    title: 11 Risks and technical debt
    items:
      - "Risk: fleet growth beyond one TSDB node"
      - "Risk: partner firmware delays cert rotation"
      - "Debt: payload v1 decoder kept for old firmware"
      - "Debt: rules configured in code, no UI"
  - dot: violet
    title: 12 Glossary
    items:
      - Telemetry, readings a device sends
      - Rollup, hourly aggregate of telemetry
      - Provisioning, giving a device its identity
      - Fault code, error number from the device