# 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