Skip to main content

Extending the Cloud Backend

The backend is yours to extend once deployed. This page is for someone adding an endpoint or a handler to the ESP RainMaker Neo backend itself — not for someone integrating against its API, which is API getting started.

How the repository is laid out​

The deployment is AWS CDK in Python, organised as stack groups that deploy in dependency order — identity first, then the core IoT cloud and dashboard, then optional integrations. Stackfile.yaml declares those groups and their parameters; Makefile is the entry point for every workflow.

Application code sits behind the stacks: Lambda handlers per feature area, with shared helpers in app_common.py.

Adding a REST endpoint​

Four things change together, and a reviewer will look for all four:

  1. The OpenAPI spec in docs/api/. The spec is not documentation-after-the-fact — this site's entire API reference is generated from it, so an endpoint absent from the spec is invisible to every client.
  2. The handler, alongside its feature area's existing handlers.
  3. The stack wiring, so the route reaches the handler.
  4. Tests — see below.

Adding an IoT rule or Lambda​

Device-triggered work hangs off AWS IoT rules defined in the core stack. When you add one, decide deliberately whether it runs inline or through a queue: the backend already has a queue-backed mode for high-volume event handling, and choosing wrong shows up as throttling under load rather than as a functional bug.

Testing​

Manual Testing​

cli/morpheus.py is the integration harness — an interactive driver that authenticates as a real user or device and exercises endpoints and MQTT against a live deployment. Its README explains the contexts it offers. New endpoints belong in it, because unit tests alone will not catch a missing permission or an unattached IoT policy.

Mock-based Tests​

Most modules and main files have a corresponding _test.go file that contains Ginkgo-based tests. These run against mock implementations of AWS services and validate most of the 'logic' of the code, without needing a deploy on every edit-compile-debug cycle.

Mock-based tests make up the bulk of the suite because they can be parallelised and executed at high speed. Integration tests (next section) primarily focus on AWS-specific constraints like permissions and memory limits — but since those run against the deployment, they are slower. Once the mock-based tests pass, you still need to run the integration tests with your code deployed.

Integration Testing​

The test/itest directory houses multiple integration tests that are executed against a particular deployment. Once your mock-based tests pass, you move on to these integration tests. Typically you will deploy the code that you built and then execute the entire set of integration tests, to ensure that your code works, and also that it doesn't introduce any regressions.

What has to change together​

A feature is not done when the code works. The specification, the OpenAPI definition, the handler, the tests, and the deployment parameters form one unit — and because the specs are now published as their own Sphinx site, a behaviour change that skips the spec becomes a documentation bug in a place you do not control.