Key design decisions
The choices that shape the system, and what each one buys us. Most came from lessons in the proof of concept.
Topic rules feed a queue, not a Lambda
In the proof of concept, IoT rules called a Lambda directly. Now they write to SQS, and ingest reads from it.
Why: retries, a dead-letter queue to inspect bad messages, and batches of up to 100.
Commands go through an outbox
The proof of concept locked devices through an unauthenticated public URL. Now every command is a database row, delivered by device-commander to the shadow.
Why: no public way to lock a device, commands are written in the same transaction as the decision, and only the newest one per device is sent, in order.
Lock state follows the device's report
We store what the device says it did, not what we asked.
Why: the admin can't show a device as locked when it isn't.
One model runner, offline and live
The same loop runs models on simulated datasets and on live data.
Why: a score measured offline holds in production. Live and offline runs of the same fleet gave identical decisions.
Thin handlers, pure logic
Each Lambda is a thin entry point. The logic takes its database, clock and outside services as inputs.
Why: the same code runs in tests, in a local replay of the whole pipeline, and on AWS.
Safe to receive twice
Duplicates are ignored, state only moves forward, and models resume where they stopped.
Why: SQS can deliver a message more than once, and retries must never double-count.
One time zone file
Every “which night” or “which school window” question goes through one file (America/Toronto).
Why: daylight saving changes make 7-hour and 9-hour nights. The proof of concept assumed UTC−4 all year.
Postgres + PostGIS instead of DynamoDB
A fresh relational schema replaced the proof of concept’s DynamoDB tables. Old data wasn’t migrated.
One AWS account per stage, no personal stages
dev, staging and production are fully separate.
Why: isolation between stages. A second stage in the dev account would receive every device message twice.
The hardware spec's samples are a contract
The hardware team’s sample messages are kept as test fixtures and must parse exactly. They’re never edited.