iot_skeleton/doc/architecture/adr-001-local-gateway.md

Architectural Decision Record: Local Gateway + External Backend

Status

Accepted

Context

Initial design considered direct communication between IoT devices (ESP32) and a backend hosted on the internet.

Concerns identified:

• High volume of small messages from devices
• Unnecessary exposure of raw telemetry to the internet
• Increased complexity on constrained devices (TLS, crypto, reconnect logic)
• Security overhead (encryption, signing on every message)

At the same time, the system does not require real-time global access to raw device data. Most data is only useful locally or in aggregated form.

Decision

Adopt a local gateway architecture:

ESP32 devices → Local Backend (LAN) → External Backend (Internet) → Mobile App

Key principles

1. Devices communicate only within LAN

   • No direct internet access required
   • No inbound connections to devices
   • Devices initiate outbound connections only to local backend

2. Local backend acts as a gateway

   • Maintains persistent secure connection (WebSocket over TLS) to external backend
   • Aggregates telemetry data
   • Translates and routes commands

3. External backend is the only internet-facing component

   • Serves mobile applications
   • Sends commands to local backend
   • Receives aggregated data only

Rationale

1. Reduced complexity on devices

ESP32 devices:

• Do not implement TLS
• Do not handle complex cryptography
• Maintain simple communication protocol

Result:

• Lower memory and CPU usage
• Simpler firmware
• Higher reliability

2. Network efficiency

Instead of many small messages:

• Local backend aggregates data
• Sends fewer, larger messages

Result:

• Reduced bandwidth usage
• Fewer connections

3. Clear trust boundary

• LAN is treated as a controlled (conditionally trusted) environment
• Internet is treated as untrusted

Security measures are concentrated at the boundary:

• TLS on gateway ↔ external backend
• Authentication and validation at gateway

4. Data control and privacy

• Raw telemetry remains in local network
• Only aggregated/necessary data leaves the network
• No dependency on third-party cloud for device data

Security Model

LAN (conditionally trusted)

Assumptions:

• Network is controlled
• Unauthorized access is unlikely but possible

Mitigations:

• Device IP whitelist
• Device identification (deviceId)
• Simple authentication (pre-shared token)
• Network segmentation (IoT VLAN)

No encryption required inside LAN.

Internet (untrusted)

• All communication secured via TLS
• Strong authentication required
• Single controlled connection (gateway → backend)

Command Flow

1. Mobile app → External backend
2. External backend → Local backend (via secure WebSocket)
3. Local backend → Device (LAN)

Local backend is responsible for:

• Validating commands
• Ensuring they match device capabilities

Consequences

Positive

• Simpler device firmware
• Reduced attack surface (no exposed devices)
• Better performance and scalability
• Full control over data

Negative

• Requires always-on local backend
• Adds one architectural component (gateway)
• LAN cannot be treated as fully secure

Notes

If LAN is compromised, impact is broader than IoT telemetry leakage and should be treated as a separate security incident class.

Therefore, the system does not attempt to provide full zero-trust security within LAN, but instead applies reasonable safeguards.

Future Considerations

• Optional message signing inside LAN if threat model changes
• Key rotation for device tokens
• Device revocation mechanisms
• Monitoring of gateway ↔ external connection