# abideya/sensorwatch architecture

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

- Interactive diagram: https://gitdiagram.com/abideya/sensorwatch
- Repository: https://github.com/abideya/sensorwatch

## Overview

SensorWatch is a serverless IoT monitoring and anomaly-detection platform. Its main workflow sends simulated sensor readings through the REST ingestion API, validates and stores them, then asynchronously analyzes them to update device state and create alerts. Separate scheduled jobs detect silent devices and produce daily statistics and exports; administrators query device status, history, alerts, and statistics. The dashboard is a documented capability, but no frontend source appears in the tree. Edges reflect shown calls or README-described triggers; unsampled infrastructure wiring is not inferred.

Main entry points: [`backend/analyze/app.py`](https://github.com/abideya/sensorwatch/blob/main/backend/analyze/app.py) (Anomaly analysis), [`backend/aggregate_export/app.py`](https://github.com/abideya/sensorwatch/blob/main/backend/aggregate_export/app.py) (Daily aggregation), [`backend/common/db.py`](https://github.com/abideya/sensorwatch/blob/main/backend/common/db.py) (DynamoDB helpers), [`backend/ingest/app.py`](https://github.com/abideya/sensorwatch/blob/main/backend/ingest/app.py) (Measurement ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Measurement ingestion"]
  node_ingest_lambda["Measurement ingestion<br/>[app.py]"]
end

subgraph group_analysis["Detection and reporting"]
  node_analyze_lambda["Anomaly analysis<br/>[app.py]"]
  node_offline_check["Offline detection<br/>[app.py]"]
  node_aggregate_export["Daily aggregation<br/>[app.py]"]
end

subgraph group_admin["Administration API"]
  node_devices_query["Device and history API<br/>[app.py]"]
  node_authorizer["JWT authorizer<br/>[app.py]"]
end

subgraph group_shared["Shared runtime services"]
  node_validation["Input validation<br/>[validation.py]"]
  node_db_helpers["DynamoDB helpers<br/>[db.py]"]
  node_rules["Detection rules<br/>[rules.py]"]
  node_config["Threshold configuration<br/>[config.py]"]
  node_stats["Statistics helpers<br/>[stats.py]"]
  node_http["HTTP responses<br/>[http.py]"]
  node_jwt_utils["JWT utilities<br/>[jwt_utils.py]"]
  node_ids["Alert identifiers<br/>[ids.py]"]
  node_logs["Logs and metrics<br/>[logs.py]"]
end

subgraph group_operations["Simulation and scheduling"]
  node_simulator["Sensor simulator<br/>[simulator.py]"]
end

node_iot_actor(("IoT simulator actor"))
node_admin_actor(("Administrator"))
node_scheduler(("EventBridge scheduler"))
node_api_gateway{{"API Gateway"}}
node_measurements_store[("Measurements table")]
node_device_data_store[("Device and alert data")]
node_dynamodb[("Amazon DynamoDB")]
node_lambda_service{{"AWS Lambda"}}
node_sns{{"Amazon SNS"}}
node_ssm[("SSM Parameter Store")]
node_s3[("Amazon S3")]

node_iot_actor -->|"runs"| node_simulator
node_simulator -->|"sends readings"| node_api_gateway
node_api_gateway -->|"routes requests"| node_ingest_lambda
node_ingest_lambda -->|"validates"| node_validation
node_ingest_lambda -->|"uses"| node_db_helpers
node_ingest_lambda -->|"writes readings"| node_measurements_store
node_ingest_lambda -->|"updates device"| node_device_data_store
node_ingest_lambda -->|"invokes asynchronously"| node_lambda_service
node_lambda_service -->|"dispatches analysis"| node_analyze_lambda
node_analyze_lambda -->|"evaluates readings"| node_rules
node_analyze_lambda -->|"loads thresholds"| node_config
node_analyze_lambda -->|"uses"| node_db_helpers
node_analyze_lambda -->|"reads history"| node_measurements_store
node_analyze_lambda -->|"writes alerts and state"| node_device_data_store
node_analyze_lambda -->|"publishes alerts"| node_sns
node_scheduler -->|"triggers checks"| node_offline_check
node_offline_check -->|"loads thresholds"| node_config
node_offline_check -->|"uses"| node_db_helpers
node_offline_check -->|"marks offline; stores alerts"| node_device_data_store
node_offline_check -->|"publishes alerts"| node_sns
node_scheduler -->|"triggers daily export"| node_aggregate_export
node_aggregate_export -->|"uses"| node_db_helpers
node_aggregate_export -->|"validates day"| node_validation
node_aggregate_export -->|"summarizes measurements"| node_stats
node_aggregate_export -->|"reads measurements"| node_measurements_store
node_aggregate_export -->|"reads alerts; stores statistics"| node_device_data_store
node_aggregate_export -->|"writes daily reports"| node_s3
node_admin_actor -->|"uses administration API"| node_api_gateway
node_api_gateway -->|"routes requests"| node_devices_query
node_devices_query -->|"uses"| node_db_helpers
node_devices_query -->|"queries history"| node_measurements_store
node_devices_query -->|"queries devices and alerts"| node_device_data_store
node_devices_query -->|"formats responses"| node_http
node_devices_query -->|"uses token utilities"| node_jwt_utils
node_authorizer -->|"verifies tokens"| node_jwt_utils
node_authorizer -->|"logs decisions"| node_logs
node_db_helpers -->|"accesses tables"| node_dynamodb
node_config -->|"creates SSM client"| node_db_helpers
node_config -->|"logs configuration issues"| node_logs
node_config -->|"loads parameters"| node_ssm

click node_simulator "https://github.com/abideya/sensorwatch/blob/main/simulator/simulator.py"
click node_ingest_lambda "https://github.com/abideya/sensorwatch/blob/main/backend/ingest/app.py"
click node_analyze_lambda "https://github.com/abideya/sensorwatch/blob/main/backend/analyze/app.py"
click node_offline_check "https://github.com/abideya/sensorwatch/blob/main/backend/offline_check/app.py"
click node_aggregate_export "https://github.com/abideya/sensorwatch/blob/main/backend/aggregate_export/app.py"
click node_devices_query "https://github.com/abideya/sensorwatch/blob/main/backend/devices_query/app.py"
click node_authorizer "https://github.com/abideya/sensorwatch/blob/main/backend/authorizer/app.py"
click node_validation "https://github.com/abideya/sensorwatch/blob/main/backend/common/validation.py"
click node_db_helpers "https://github.com/abideya/sensorwatch/blob/main/backend/common/db.py"
click node_rules "https://github.com/abideya/sensorwatch/blob/main/backend/common/rules.py"
click node_config "https://github.com/abideya/sensorwatch/blob/main/backend/common/config.py"
click node_stats "https://github.com/abideya/sensorwatch/blob/main/backend/common/stats.py"
click node_http "https://github.com/abideya/sensorwatch/blob/main/backend/common/http.py"
click node_jwt_utils "https://github.com/abideya/sensorwatch/blob/main/backend/common/jwt_utils.py"
click node_ids "https://github.com/abideya/sensorwatch/blob/main/backend/common/ids.py"
click node_logs "https://github.com/abideya/sensorwatch/blob/main/backend/common/logs.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_ingest_lambda toneBlue
class node_analyze_lambda,node_offline_check,node_aggregate_export,node_measurements_store,node_device_data_store,node_dynamodb,node_ssm,node_s3 toneAmber
class node_devices_query,node_authorizer,node_api_gateway toneMint
class node_validation,node_db_helpers,node_rules,node_config,node_stats,node_http,node_jwt_utils,node_ids,node_logs,node_scheduler toneRose
class node_simulator,node_iot_actor,node_admin_actor,node_lambda_service,node_sns toneIndigo
```

## Components

### Measurement ingestion

- [Measurement ingestion](https://github.com/abideya/sensorwatch/blob/main/backend/ingest/app.py): `backend/ingest/app.py`

### Detection and reporting

- [Anomaly analysis](https://github.com/abideya/sensorwatch/blob/main/backend/analyze/app.py): `backend/analyze/app.py`
- [Offline detection](https://github.com/abideya/sensorwatch/blob/main/backend/offline_check/app.py): `backend/offline_check/app.py`
- [Daily aggregation](https://github.com/abideya/sensorwatch/blob/main/backend/aggregate_export/app.py): `backend/aggregate_export/app.py`

### Administration API

- [Device and history API](https://github.com/abideya/sensorwatch/blob/main/backend/devices_query/app.py): `backend/devices_query/app.py`
- [JWT authorizer](https://github.com/abideya/sensorwatch/blob/main/backend/authorizer/app.py): `backend/authorizer/app.py`

### Shared runtime services

- [Input validation](https://github.com/abideya/sensorwatch/blob/main/backend/common/validation.py): `backend/common/validation.py`
- [DynamoDB helpers](https://github.com/abideya/sensorwatch/blob/main/backend/common/db.py): `backend/common/db.py`
- [Detection rules](https://github.com/abideya/sensorwatch/blob/main/backend/common/rules.py): `backend/common/rules.py`
- [Threshold configuration](https://github.com/abideya/sensorwatch/blob/main/backend/common/config.py): `backend/common/config.py`
- [Statistics helpers](https://github.com/abideya/sensorwatch/blob/main/backend/common/stats.py): `backend/common/stats.py`
- [HTTP responses](https://github.com/abideya/sensorwatch/blob/main/backend/common/http.py): `backend/common/http.py`
- [JWT utilities](https://github.com/abideya/sensorwatch/blob/main/backend/common/jwt_utils.py): `backend/common/jwt_utils.py`
- [Alert identifiers](https://github.com/abideya/sensorwatch/blob/main/backend/common/ids.py): `backend/common/ids.py`
- [Logs and metrics](https://github.com/abideya/sensorwatch/blob/main/backend/common/logs.py): `backend/common/logs.py`

### Simulation and scheduling

- [Sensor simulator](https://github.com/abideya/sensorwatch/blob/main/simulator/simulator.py): `simulator/simulator.py`

### Other components

- **IoT simulator actor**
- **Administrator**
- **EventBridge scheduler**
- **API Gateway**
- **Measurements table**
- **Device and alert data**
- **Amazon DynamoDB**
- **AWS Lambda**
- **Amazon SNS**
- **SSM Parameter Store**
- **Amazon S3**

## Connections

- IoT simulator actor → Sensor simulator: runs (evidence: `README.md`)
- Sensor simulator → API Gateway: sends readings (evidence: `README.md`)
- API Gateway → Measurement ingestion: routes requests (evidence: `README.md`)
- Measurement ingestion → Input validation: validates (evidence: `backend/ingest/app.py`)
- Measurement ingestion → DynamoDB helpers: uses (evidence: `backend/ingest/app.py`)
- Measurement ingestion → Measurements table: writes readings (evidence: `backend/ingest/app.py`)
- Measurement ingestion → Device and alert data: updates device (evidence: `backend/ingest/app.py`)
- Measurement ingestion → AWS Lambda: invokes asynchronously (evidence: `backend/ingest/app.py`)
- AWS Lambda → Anomaly analysis: dispatches analysis
- Anomaly analysis → Detection rules: evaluates readings (evidence: `backend/analyze/app.py`)
- Anomaly analysis → Threshold configuration: loads thresholds (evidence: `backend/analyze/app.py`)
- Anomaly analysis → DynamoDB helpers: uses (evidence: `backend/analyze/app.py`)
- Anomaly analysis → Measurements table: reads history (evidence: `backend/analyze/app.py`)
- Anomaly analysis → Device and alert data: writes alerts and state (evidence: `backend/analyze/app.py`)
- Anomaly analysis → Amazon SNS: publishes alerts (evidence: `backend/analyze/app.py`)
- EventBridge scheduler → Offline detection: triggers checks (evidence: `README.md`)
- Offline detection → Threshold configuration: loads thresholds (evidence: `backend/offline_check/app.py`)
- Offline detection → DynamoDB helpers: uses (evidence: `backend/offline_check/app.py`)
- Offline detection → Device and alert data: marks offline; stores alerts (evidence: `backend/offline_check/app.py`)
- Offline detection → Amazon SNS: publishes alerts (evidence: `backend/offline_check/app.py`)
- EventBridge scheduler → Daily aggregation: triggers daily export (evidence: `README.md`)
- Daily aggregation → DynamoDB helpers: uses (evidence: `backend/aggregate_export/app.py`)
- Daily aggregation → Input validation: validates day (evidence: `backend/aggregate_export/app.py`)
- Daily aggregation → Statistics helpers: summarizes measurements (evidence: `backend/aggregate_export/app.py`)
- Daily aggregation → Measurements table: reads measurements (evidence: `backend/aggregate_export/app.py`)
- Daily aggregation → Device and alert data: reads alerts; stores statistics (evidence: `backend/aggregate_export/app.py`)
- Daily aggregation → Amazon S3: writes daily reports (evidence: `backend/aggregate_export/app.py`)
- Administrator → API Gateway: uses administration API (evidence: `README.md`)
- API Gateway → Device and history API: routes requests (evidence: `backend/devices_query/app.py`)
- Device and history API → DynamoDB helpers: uses (evidence: `backend/devices_query/app.py`)
- Device and history API → Measurements table: queries history (evidence: `backend/devices_query/app.py`)
- Device and history API → Device and alert data: queries devices and alerts (evidence: `backend/devices_query/app.py`)
- Device and history API → HTTP responses: formats responses (evidence: `backend/devices_query/app.py`)
- Device and history API → JWT utilities: uses token utilities (evidence: `backend/devices_query/app.py`)
- JWT authorizer → JWT utilities: verifies tokens (evidence: `backend/authorizer/app.py`)
- JWT authorizer → Logs and metrics: logs decisions (evidence: `backend/authorizer/app.py`)
- DynamoDB helpers → Amazon DynamoDB: accesses tables (evidence: `backend/common/db.py`)
- Threshold configuration → DynamoDB helpers: creates SSM client (evidence: `backend/common/config.py`)
- Threshold configuration → Logs and metrics: logs configuration issues (evidence: `backend/common/config.py`)
- Threshold configuration → SSM Parameter Store: loads parameters (evidence: `backend/common/config.py`)
