# targo-s/sdmo architecture

> Architecture diagram of the GitHub repository targo-s/sdmo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/targo-s/sdmo
- Repository: https://github.com/targo-s/sdmo
- Video tour (about a minute): https://gitdiagram.com/targo-s/sdmo/video

## Overview

SDMO simulates a legacy sensor, an edge gateway, and a cloud service, with a hybrid X25519/ML-KEM protocol alongside legacy shared-key delivery. The principal workflow is: the gateway polls and optionally authenticates a device reading, then forwards it to the cloud using a negotiated encrypted session or legacy mode; the cloud validates and stores readings. Provisioning and crypto self-test/metrics are supporting capabilities. The README was empty, so subsystem coverage and links rely on the source index and sampled code; unsampled integrations are not inferred.

Main entry points: [`SDMO/sdmo/crypto.py`](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/crypto.py) (Crypto Primitives), [`SDMO/sdmo/gateway.py`](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/gateway.py) (Reading Forwarder), [`SDMO/sdmo/legacy_device.py`](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/legacy_device.py) (Legacy Sensor), [`SDMO/sdmo/cloud.py`](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/cloud.py) (Cloud HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Device and Gateway"]
  node_device["Legacy Sensor<br/>[legacy_device.py]"]
  node_gateway["Gateway Runtime<br/>[gateway.py]"]
  node_forwarder["Reading Forwarder<br/>[gateway.py]"]
  node_hybrid["Hybrid Client<br/>[gateway.py]"]
  node_ratchet["Fallback Ratchet<br/>[gateway.py]"]
end

subgraph group_cloud["Cloud Service"]
  node_cloud_api["Cloud HTTP API<br/>[cloud.py]"]
  node_cloud_state[("Sessions and Readings<br/>[cloud.py]")]
  node_protocol["JSON Helpers<br/>[common.py]"]
end

subgraph group_security["Security and Provisioning"]
  node_crypto["Crypto Primitives<br/>[crypto.py]"]
  node_provision["Key Provisioning<br/>[provision.py]"]
end

subgraph group_observability["Metrics"]
  node_metrics["Metrics Export<br/>[metrics.py]"]
end

node_sensor_actor(("Sensor Endpoint"))
node_cloud_actor(("Cloud Endpoint"))

node_gateway -->|"polls readings"| node_device
node_gateway -->|"verifies readings"| node_crypto
node_gateway -->|"forwards readings"| node_forwarder
node_forwarder -->|"uses hybrid mode"| node_hybrid
node_forwarder -->|"checks fallback"| node_ratchet
node_forwarder -->|"sends legacy readings"| node_cloud_actor
node_hybrid -->|"negotiates and sends"| node_cloud_actor
node_hybrid -->|"uses primitives"| node_crypto
node_cloud_actor -.->|"submits requests"| node_cloud_api
node_cloud_api -->|"validates and updates"| node_cloud_state
node_cloud_api -->|"parses and replies"| node_protocol
node_cloud_state -->|"uses protocol crypto"| node_crypto
node_device -->|"signs readings"| node_crypto
node_device -->|"formats responses"| node_protocol
node_metrics -->|"runs crypto self-test"| node_crypto

click node_device "https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/legacy_device.py"
click node_gateway "https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/gateway.py"
click node_forwarder "https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/gateway.py"
click node_hybrid "https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/gateway.py"
click node_ratchet "https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/gateway.py"
click node_cloud_api "https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/cloud.py"
click node_cloud_state "https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/cloud.py"
click node_protocol "https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/common.py"
click node_crypto "https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/crypto.py"
click node_provision "https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/provision.py"
click node_metrics "https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/metrics.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_device,node_gateway,node_forwarder,node_hybrid,node_ratchet toneBlue
class node_cloud_api,node_cloud_state,node_protocol toneAmber
class node_crypto,node_provision toneMint
class node_metrics toneRose
class node_sensor_actor,node_cloud_actor toneIndigo
```

## Components

### Device and Gateway

- [Legacy Sensor](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/legacy_device.py): `SDMO/sdmo/legacy_device.py`
- [Gateway Runtime](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/gateway.py): `SDMO/sdmo/gateway.py`
- [Reading Forwarder](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/gateway.py): `SDMO/sdmo/gateway.py`
- [Hybrid Client](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/gateway.py): `SDMO/sdmo/gateway.py`
- [Fallback Ratchet](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/gateway.py): `SDMO/sdmo/gateway.py`

### Cloud Service

- [Cloud HTTP API](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/cloud.py): `SDMO/sdmo/cloud.py`
- [Sessions and Readings](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/cloud.py): `SDMO/sdmo/cloud.py`
- [JSON Helpers](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/common.py): `SDMO/sdmo/common.py`

### Security and Provisioning

- [Crypto Primitives](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/crypto.py): `SDMO/sdmo/crypto.py`
- [Key Provisioning](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/provision.py): `SDMO/sdmo/provision.py`

### Metrics

- [Metrics Export](https://github.com/targo-s/sdmo/blob/main/SDMO/sdmo/metrics.py): `SDMO/sdmo/metrics.py`

### Other components

- **Sensor Endpoint**
- **Cloud Endpoint**

## Connections

- Gateway Runtime → Legacy Sensor: polls readings (evidence: `SDMO/sdmo/gateway.py`)
- Gateway Runtime → Crypto Primitives: verifies readings (evidence: `SDMO/sdmo/gateway.py`)
- Gateway Runtime → Reading Forwarder: forwards readings (evidence: `SDMO/sdmo/gateway.py`)
- Reading Forwarder → Hybrid Client: uses hybrid mode (evidence: `SDMO/sdmo/gateway.py`)
- Reading Forwarder → Fallback Ratchet: checks fallback (evidence: `SDMO/sdmo/gateway.py`)
- Reading Forwarder → Cloud Endpoint: sends legacy readings (evidence: `SDMO/sdmo/gateway.py`)
- Hybrid Client → Cloud Endpoint: negotiates and sends (evidence: `SDMO/sdmo/gateway.py`)
- Hybrid Client → Crypto Primitives: uses primitives (evidence: `SDMO/sdmo/gateway.py`)
- Cloud Endpoint → Cloud HTTP API: submits requests
- Cloud HTTP API → Sessions and Readings: validates and updates (evidence: `SDMO/sdmo/cloud.py`)
- Cloud HTTP API → JSON Helpers: parses and replies (evidence: `SDMO/sdmo/cloud.py`)
- Sessions and Readings → Crypto Primitives: uses protocol crypto (evidence: `SDMO/sdmo/cloud.py`)
- Legacy Sensor → Crypto Primitives: signs readings (evidence: `SDMO/sdmo/legacy_device.py`)
- Legacy Sensor → JSON Helpers: formats responses (evidence: `SDMO/sdmo/legacy_device.py`)
- Metrics Export → Crypto Primitives: runs crypto self-test (evidence: `SDMO/sdmo/metrics.py`)
