From d90f1910327b21678562dc54da786aea6753ce19 Mon Sep 17 00:00:00 2001
From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
Date: Wed, 22 Apr 2026 14:37:38 -0400
Subject: [PATCH] Add README with architecture overview, SSM parameters, and
 phone setup instructions

---
 README.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..664f02c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,37 @@
+# Sea Haven Door Unlock API
+
+AWS Lambda middleware that allows a Yealink T58A desk phone to unlock the front door controlled by LenelS2 Elements. Press a DSS key on the phone, and the door unlocks.
+
+```
+Yealink T58A → HTTPS GET → API Gateway → Lambda → LenelS2 Elements API → Door Unlocks
+```
+
+## Architecture
+
+- **API Gateway (HTTP API)** — single `GET /unlock` endpoint with throttling (5 burst / 2 sustained req/sec)
+- **Lambda (Node.js 20.x)** — validates a shared auth token, calls the Elements `TemporaryUnlock` command
+- **SSM Parameter Store** — stores the Elements API key, auth token, and door device ID
+- **Custom Domain** — `doorunlock.seahaven.com` via Route 53 + ACM wildcard cert
+
+## SSM Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `/seahaven/door-unlock/elements-api-key` | SecureString | LenelS2 Elements API key |
+| `/seahaven/door-unlock/auth-token` | SecureString | Shared secret embedded in the Yealink DSS key URL |
+| `/seahaven/door-unlock/door-id` | String | Elements device ID for the front door reader |
+
+## Deployment
+
+```bash
+npm install
+npx cdk deploy
+```
+
+## Phone Configuration
+
+Configure a DSS key on the Yealink T58A (via phone web UI or 3CX):
+
+- **Type:** URL
+- **Label:** Unlock Door
+- **Value:** `https://doorunlock.seahaven.com/unlock?token=<auth-token-value>`