Skip to main content

System Architecture

ESP RainMaker Neo is an IoT platform you deploy into your own AWS account: firmware on the device, a serverless backend built from AWS managed services, and clients that talk to both. This page is the shape of the whole system, for someone evaluating Neo or trying to work out which part of it a problem belongs to.

Neo has no servers you operate and no shared multi-tenant service in the middle. Every deployment is a set of CloudFormation stacks in one AWS account, in one region.

The four planes​

Device plane. The Neo firmware SDK, one C source tree that builds for both ESP-IDF and POSIX targets. A Node holds an X.509 certificate, connects to AWS IoT Core over mutual TLS, and owns its own state: it evaluates Schedules from its real-time clock, watches Trigger conditions, and reports Parameter values into its shadows.

Cloud plane. AWS IoT Core is the message broker and the shadow store. Around it sits a serverless backend: API Gateway in front of Go functions on Lambda, DynamoDB for state, S3 for firmware images and device files, and IoT rules that route device messages — sometimes straight to a Lambda, sometimes straight into DynamoDB with no compute in the path at all.

Client plane. Phone apps, web dashboards, and voice assistant integrations. Clients use two separate credentials: a signed HTTPS call to the REST API for anything transactional, and a scoped MQTT connection to IoT Core for live state and control. Neither the phone apps nor the web clients live in the Neo repositories — they are the existing ESP RainMaker apps and SDKs, talking Neo's protocols. Users of the system interact with their nodes through these clients.

Admin plane. A dashboard and its APIs, backed by a separate identity pool and a separate IAM role. Admins interact with the system through this interface. Admins register Nodes in bulk, run OTA jobs, and query the fleet. They deliberately hold fewer AWS permissions than you might expect — see Security.

The four planes side by side — device plane (the firmware SDK, X.509 and mTLS), cloud plane (IoT Core, API Gateway, Lambda, DynamoDB, S3), client plane (phone, web and voice, using two separate credentials), and admin plane (bulk registration, OTA and fleet queries, with its own identity pool and IAM role)

What runs in your AWS account​

Neo deploys as a small number of CDK stacks, split by lifecycle rather than by feature:

  • An identity pair of stacks creates the two Cognito user pools — one for end users, one for admins — and their app clients.
  • A base stack holds everything long-lived: the Cognito Identity Pool and the IAM roles it hands out, the API Gateway REST API and its Cognito authorizer, DynamoDB tables, S3 buckets, the default IoT policy attached to every Node, IoT role aliases, and the AWS IoT Fleet Indexing configuration.
  • A core stack holds the compute: the Lambda functions and their API Gateway wiring, grouped per feature area — users, groups, nodes, node admin, node services, notifications, files, voice assistant integrations.
  • An optional admin dashboard stack hosts the operator UI.

Splitting base from core is what makes the backend safely re-deployable: you can ship new function code without touching the resources that hold your data or your customers' identities.

Two AWS services show up in less obvious roles. ECS Fargate runs bulk Node registration, because a job covering thousands of devices does not fit inside a Lambda timeout. SQS is an optional shape for the device-to-cloud request path: the same handler can either be invoked directly by an IoT rule, one invocation per message, or fed from a queue that absorbs bursts. Which mode is active can be flipped at runtime by a super admin, and neither the firmware nor the wire protocol changes between them.