Diagramming a Smart-Home IoT Platform with C4

What this model is

This is a C4 model of the production smart-home / smart-electrical platform I have owned since 2017. The diagrams are the work: one LikeC4 source file, several views you can drill into.

The live estate behind the pictures is 70,000+ devices, 10,000+ accounts, 100+ events per second and 99.999% uptime. The system in the model is the Smart Device IoT Platform. Around it sit a Home Gateway, a Platform API, and the neighbouring services a household actually talks to.

• Live explorer: nilushan.github.io/nilushan-projects-c4
• Source: github.com/nilushan/nilushan-projects-c4

How it was built, as a method: C4 / LikeC4 notes.

How to read it

Start wide and click in. Context is who is around the platform. Containers are what we deploy. The device pipeline, identity, voice and data views are slices of the same model, not separate drawings. Flows are request-time pictures. Deployment is where those containers run.

Matter manufacturing is marked designed, not shipped. I do not claim a payment gateway, a GraphQL API, or Apple Home as a cloud fulfilment integration I built.

System context

People: the customer, the installer who commissions a household, and internal admin / support / operator roles. Neighbours: a managed identity provider, an MQTT broker, Google Home, Alexa, mobile push, transactional email, a customer-engagement platform.

System context Open interactive view

The home side is a local device mesh plus a home gateway. The gateway is the only thing that speaks MQTT to the cloud. Devices stay on the LAN.

Core containers

Clients on the left, API and shared library in the middle, stores on the right.

Core containers Open interactive view

Worth noticing:

• a shared platform library — RBAC dispatch, typed document access, MQTT broker port, domain models
• an invitation portal for installer → customer handover
• Redis as cache, pub/sub backplane and delayed-job store
• an OAuth authorization server used to link Alexa and Google Home, not a generic identity box

Device telemetry and control

Unsolicited telemetry and cloud-to-device commands share one decode path.

Device telemetry and control Open interactive view

The gateway publishes state, requests and schedules onto the MQTT broker. A device event bus fans those messages to pull subscribers. A register decoder turns a packed binary protocol into typed state — dimmers, fans, garage doors and sensors expose different registers; every type also reports power.

Snapshot goes to the document store, history and power to partitioned PostgreSQL, hot state to Redis. Redis pub/sub feeds a WebSocket realtime gateway so apps do not poll. User-visible register changes are reported to Alexa and Google Home. Gateway requests (provisioning, keys, CRC, schedules) are request/response, not fire-and-forget.

Identity and access

The platform API validates the identity-provider JWT on every call, then dispatches through role-aware handlers: unrestricted admin path versus ownership-scoped customer path. Voice assistants never see those credentials — they link accounts through the OAuth server.

Voice assistants

Both Alexa Smart Home v3 and Google Home are certified. Multi-function hardware is mapped to virtual endpoints (switch, dimmer, fan, outlet, blind, garage). Alexa hits a thin voice-cloud wrapper; fulfilment, state and commands stay on GCP. Report-state comes from the telemetry processor so the assistant does not poll.

Data platform

• Document store: system of record for users, networks, memberships and the latest device snapshot.
• Redis: hot reads, pub/sub into the realtime gateway, delayed/duration jobs.
• PostgreSQL: control history, power, custom time-series. Monthly range partitions, prune on query, archive-and-drop expired ranges to object storage.
• A document-to-SQL sync keeps a reporting replica with JSONB and schema evolution.

The sync and partition tools were delivered with AI coding assistance. I do not list Go or Python as production expertise.

Firmware and onboarding

Device-specific releases, beta channels and user-targeted rollouts. Gateways ask the catalog, then pull a signed image from a private CDN. Constrained devices trust a private certificate chain.

Installers commission on the LAN, then the customer accepts a code, QR, email link or handover file in a focused Next.js portal.

Flows

A customer toggling a device from the app — authenticated API call, MQTT command, decode, live UI confirmation:

Flow — app command Open interactive view

Voice directive, unsolicited telemetry, and installer handover:

Production deployment

Long-running services on GKE. Invitation portal, CRM sync, document-to-SQL and partition management on Cloud Run. Domain-event publishers as Cloud Functions. Data and buses are managed services. The same versioned images are promoted across environments. GitHub Actions and GKE workloads talk to GCP through Workload Identity Federation — no long-lived service-account keys.

Designed, not shipped

The Matter manufacturing cloud — factory registration, catalogues, quotas, serials, pairing material, mTLS and HSM-backed identity — is an architecture I designed. It is not a live factory, and the diagrams mark it that way.

Apple Home appears only as a local Matter path on that designed-only view.

What the diagrams are arguing

A few boundaries that the pictures are there to keep honest:

• The gateway is the cloud-facing device. Nothing on the LAN speaks MQTT northbound. That keeps the fleet protocol in one place and keeps individual loads off the public internet.
• One decode path. Telemetry and commands share a register model. Two decoders would be two device types.
• Identity is split on purpose. App JWT + RBAC is not the same as voice OAuth linking. Mixing them would either over-privilege an assistant or make account linking look like a user session.
• Redis is a backplane, not a cache box. If you only draw it as cache, you miss pub/sub into WebSockets and the delayed jobs that duration-based device behaviour depends on.
• History is a lifecycle. Snapshots are documents; time-series is partitioned SQL that can be archived. Treating both as “the database” is how the hot path inherits last year’s power samples.

Related implementation work

• Zero-downtime Xively → GCP migration — how this platform got onto GCP
• Admin dashboard — the operator console on these APIs
• Voice assistants — translators, linking, report-state
• Partner API — OAuth and events for third parties
• Keyless CI/CD — artifact promotion and Workload Identity Federation
• Database and logging cost — monthly partitions and archive-and-drop

The LikeC4 source lives in nilushan/nilushan-projects-c4. Pushes to main publish the interactive explorer.