From fddc086b4e8184ac37820cc2b73bb82f0c42d8db Mon Sep 17 00:00:00 2001
From: eugene-admin <pavloveugene@gmail.com>
Date: Sun, 5 Apr 2026 19:53:03 +0300
Subject: [PATCH] init: add docs

---
 README.md                                 |   3 +
 doc/architecture/adr-001-local-gateway.md | 153 ++++++++++++++++++++++
 2 files changed, 156 insertions(+)
 create mode 100644 README.md
 create mode 100644 doc/architecture/adr-001-local-gateway.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8a62d04
--- /dev/null
+++ b/README.md
@@ -0,0 +1,3 @@
+## Documentation
+
+- Architecture decisions: `doc/architecture/`
\ No newline at end of file
diff --git a/doc/architecture/adr-001-local-gateway.md b/doc/architecture/adr-001-local-gateway.md
new file mode 100644
index 0000000..2a6b1fa
--- /dev/null
+++ b/doc/architecture/adr-001-local-gateway.md
@@ -0,0 +1,153 @@
+# 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