Initial commit — multi-tenant WiFi hotspot monetization platform

Node.js/Express backend with Omada SDN integration, M-Pesa payments via
Snippe, SMS notifications, captive portal, and tenant dashboard API.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.env.example

@@ -0,0 +1,41 @@
+# Server
+PORT=3000
+NODE_ENV=development
+
+# Portal — host:port as Omada sees it (no scheme)
+PORTAL_HOST=your-domain.com:3000
+PORTAL_SCHEME=http
+
+# MySQL
+DB_HOST=localhost
+DB_PORT=3306
+DB_USER=wifiuser
+DB_PASS=wifipass
+DB_NAME=wifiplatform
+
+# JWT
+JWT_SECRET=change_me_to_a_long_random_string_min_32_chars
+JWT_ADMIN_SECRET=change_me_admin_secret_min_32_chars
+
+# Omada Controller
+OMADA_URL=https://13.63.50.201:8043
+OMADA_USER=Mbonea
+OMADA_PASS=yourpassword
+
+# Snippe Payments
+SNIPPE_API_KEY=snp_live_...
+SNIPPE_WEBHOOK_SECRET=whsec_...
+
+# SMS Gateway (Android SMS Gateway)
+SMS_GATEWAY_URL=https://your-sms-gateway.hf.space/api/3rdparty/v1/messages
+SMS_GATEWAY_USER=your_user
+SMS_GATEWAY_PASS=your_pass
+
+# Admin access token (simple bearer token for admin endpoints)
+ADMIN_TOKEN=change_me_strong_admin_token
+
+# Platform config
+PLATFORM_COMMISSION_RATE=0.05
+SNIPPE_FEE_RATE=0.005
+DEVICE_MONTHLY_FEE=20000
+DEVICE_TRIAL_DAYS=14

.gitignore

@@ -0,0 +1,28 @@
+# Dependencies
+node_modules/
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+
+# Runtime
+pids/
+*.pid
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+
+# Build / uploads
+dist/
+portals/uploads/

API_DOCUMENTATION.md

@@ -0,0 +1,1018 @@
+# WiFi Platform — Backend API Documentation
+
+> For frontend engineers building the Tenant Dashboard and Super Admin Panel.  
+> Base URL: `http://{SERVER_HOST}:3000`  
+> All API responses are JSON. All request bodies must be `Content-Type: application/json`.
+
+---
+
+## Table of Contents
+
+1. [Authentication](#1-authentication)
+2. [Tenant — Devices](#2-tenant--devices)
+3. [Tenant — WiFi Plans](#3-tenant--wifi-plans)
+4. [Tenant — Dashboard](#4-tenant--dashboard)
+5. [Tenant — Sessions](#5-tenant--sessions)
+6. [Tenant — Payouts](#6-tenant--payouts)
+7. [Tenant — Alerts](#7-tenant--alerts)
+8. [Super Admin](#8-super-admin)
+9. [Captive Portal (Public)](#9-captive-portal-public)
+10. [Error Format](#10-error-format)
+11. [Enums & Constants](#11-enums--constants)
+12. [UI Building Guide](#12-ui-building-guide)
+
+---
+
+## 1. Authentication
+
+All tenant endpoints require a `Bearer` token in the `Authorization` header:
+
+```
+Authorization: Bearer <jwt_token>
+```
+
+The token is returned on login and registration. It expires after **30 days**.
+
+---
+
+### POST `/api/auth/register`
+Register a new tenant account.
+
+**Body:**
+```json
+{
+  "business_name": "Sunset Hostel",
+  "contact_name":  "John Doe",
+  "email":         "john@sunset.co.tz",
+  "phone":         "0712345678",
+  "password":      "mypassword"
+}
+```
+
+**Validation:**
+- All fields required
+- `password` minimum 8 characters
+- `email` and `phone` must be unique
+
+**Response `201`:**
+```json
+{
+  "token": "eyJhbGci...",
+  "client": {
+    "id": 1,
+    "business_name": "Sunset Hostel",
+    "contact_name": "John Doe",
+    "email": "john@sunset.co.tz",
+    "phone": "0712345678",
+    "balance": 0,
+    "total_earned": 0,
+    "total_withdrawn": 0,
+    "is_active": 1,
+    "created_at": "2026-04-15T10:00:00.000Z"
+  }
+}
+```
+
+> A welcome SMS is sent to `phone` on success.
+
+---
+
+### POST `/api/auth/login`
+Login with email and password.
+
+**Body:**
+```json
+{
+  "email":    "john@sunset.co.tz",
+  "password": "mypassword"
+}
+```
+
+**Response `200`:**
+```json
+{
+  "token": "eyJhbGci...",
+  "client": { ...same as register... }
+}
+```
+
+---
+
+### POST `/api/auth/forgot-password`
+Request a password reset OTP via SMS.
+
+**Body:**
+```json
+{ "phone": "0712345678" }
+```
+
+**Response `200`:**
+```json
+{ "message": "If that number is registered, an OTP has been sent." }
+```
+
+> Always returns 200 regardless of whether the phone exists — prevents enumeration.  
+> OTP is a 6-digit code, valid for **10 minutes**, single-use.  
+> Rate limited to 3 requests per 15 minutes per IP.
+
+---
+
+### POST `/api/auth/reset-password`
+Set a new password using the OTP received via SMS.
+
+**Body:**
+```json
+{
+  "phone":        "0712345678",
+  "otp":          "482910",
+  "new_password": "newsecurepassword"
+}
+```
+
+**Validation:**
+- `new_password` minimum 8 characters
+- OTP must be unused and not expired
+
+**Response `200`:**
+```json
+{ "message": "Password reset successfully. Please log in." }
+```
+
+**Error `400`:** `"Invalid or expired OTP"`
+
+---
+
+### GET `/api/auth/me`
+Get the authenticated tenant's profile.
+
+**Auth:** Required
+
+**Response `200`:**
+```json
+{
+  "id": 1,
+  "business_name": "Sunset Hostel",
+  "contact_name": "John Doe",
+  "email": "john@sunset.co.tz",
+  "phone": "0712345678",
+  "balance": 45000.00,
+  "total_earned": 320000.00,
+  "total_withdrawn": 275000.00,
+  "created_at": "2026-04-15T10:00:00.000Z"
+}
+```
+
+---
+
+## 2. Tenant — Devices
+
+A **device** represents one WiFi access point (AP) registered to a tenant. Each device maps to one Omada site and has its own captive portal, WiFi plans, billing, and guest sessions.
+
+---
+
+### GET `/api/devices`
+List all devices for the authenticated tenant.
+
+**Auth:** Required
+
+**Response `200`:**
+```json
+[
+  {
+    "id": 3,
+    "name": "Main Building",
+    "location": "Floor 1",
+    "mac": "24-2F-D0-DF-19-9C",
+    "model": "EAP110-Outdoor",
+    "ip": "192.168.1.137",
+    "status": "online",
+    "billing_status": "active",
+    "billing_expires_at": "2026-05-15T00:00:00.000Z",
+    "monthly_fee": 20000.00,
+    "cpu_util": 12,
+    "mem_util": 63,
+    "guest_count": 4,
+    "client_count": 5,
+    "last_seen_at": "2026-04-15T11:30:00.000Z",
+    "registered_at": "2026-03-01T08:00:00.000Z",
+    "omada_site_id": "69dcc0a73044367bfbc43692"
+  }
+]
+```
+
+**`status` values:** `pending` · `adopting` · `online` · `offline` · `removed`  
+**`billing_status` values:** `trial` · `active` · `suspended` · `cancelled`
+
+---
+
+### POST `/api/devices`
+Register a new WiFi access point.
+
+**Auth:** Required
+
+**Body:**
+```json
+{
+  "name":            "Main Building",
+  "mac":             "24:2F:D0:DF:19:9C",
+  "location":        "Floor 1",
+  "device_username": "admin",
+  "device_password": "MyCustomPass@123"
+}
+```
+
+**Notes:**
+- `name` and `mac` are required. All other fields are optional.
+- MAC is auto-normalized to `AA-BB-CC-DD-EE-FF` format.
+- `device_username` / `device_password` are the credentials the AP was configured with. If not supplied, Omada's auto-generated site credentials are used. Supply these if the AP already has custom credentials set before registration.
+- An Omada site and captive portal are created automatically.
+- Device starts in `trial` billing status (default 14-day trial).
+
+**Response `201`:**
+```json
+{
+  "device": { ...full device object... },
+  "message": "Device registered. Plug in your AP and wait for it to come online."
+}
+```
+
+---
+
+### GET `/api/devices/:id`
+Get a single device with today's stats and active guest sessions.
+
+**Auth:** Required
+
+**Response `200`:**
+```json
+{
+  "id": 3,
+  "name": "Main Building",
+  "status": "online",
+  "billing_status": "active",
+  "sales_today": 12,
+  "earned_today": 11400.00,
+  "active_sessions": [
+    {
+      "client_mac": "2A-61-D9-9B-90-7C",
+      "started_at": "2026-04-15T09:00:00.000Z",
+      "bytes_down": 4321769,
+      "bytes_up": 6990620,
+      "expires_at": "2026-04-15T11:00:00.000Z",
+      "code": "ABCD-1234",
+      "plan_name": "2 Hour Plan"
+    }
+  ]
+}
+```
+
+---
+
+### DELETE `/api/devices/:id`
+Pause a device (suspends billing, kicks all connected guests, revokes active tokens).
+
+**Auth:** Required
+
+> This is reversible — use `POST /api/devices/:id/renew` to reactivate.  
+> The captive portal will show a "Renew Subscription" page to guests.  
+> Tenant receives an SMS with the renewal amount.
+
+**Response `200`:**
+```json
+{
+  "message": "Device paused. Renew your subscription to reactivate."
+}
+```
+
+---
+
+### POST `/api/devices/:id/renew`
+Initiate a monthly subscription payment for a device via M-Pesa.
+
+**Auth:** Required
+
+**Body:** *(empty)*
+
+**Response `200`:**
+```json
+{
+  "reference": "abc123def456ghi789",
+  "amount": 20000,
+  "message": "Check your phone for M-Pesa prompt"
+}
+```
+
+> Payment is processed via M-Pesa. On success the webhook automatically extends `billing_expires_at` by 30 days and sets `billing_status = 'active'`.
+
+---
+
+## 3. Tenant — WiFi Plans
+
+Plans define what guests can purchase on the captive portal. Each plan belongs to a specific device.
+
+---
+
+### GET `/api/plans?deviceId=:id`
+List all plans (active and inactive) for a device.
+
+**Auth:** Required  
+**Query:** `deviceId` (required)
+
+**Response `200`:**
+```json
+[
+  {
+    "id": 7,
+    "client_id": 1,
+    "device_id": 3,
+    "name": "1 Hour Browsing",
+    "duration_seconds": 3600,
+    "price": 500.00,
+    "down_limit": 5,
+    "down_unit": 2,
+    "up_limit": 2,
+    "up_unit": 2,
+    "display_order": 0,
+    "is_active": 1,
+    "created_at": "2026-03-01T08:00:00.000Z"
+  }
+]
+```
+
+**Speed units:** `1` = Kbps · `2` = Mbps
+
+---
+
+### POST `/api/plans`
+Create a new WiFi plan.
+
+**Auth:** Required
+
+**Body:**
+```json
+{
+  "device_id":        3,
+  "name":             "1 Hour Browsing",
+  "duration_seconds": 3600,
+  "price":            500,
+  "down_limit":       5,
+  "down_unit":        2,
+  "up_limit":         2,
+  "up_unit":          2,
+  "display_order":    0
+}
+```
+
+**Required:** `device_id`, `name`, `duration_seconds`, `price`  
+**Defaults:** `down_limit: 2`, `down_unit: 2`, `up_limit: 2`, `up_unit: 2`, `display_order: 0`
+
+**Response `201`:** Full plan object.
+
+---
+
+### PUT `/api/plans/:id`
+Update a plan. All fields are optional (partial update supported).
+
+**Auth:** Required
+
+**Body (all optional):**
+```json
+{
+  "name":             "1 Hour Plan",
+  "duration_seconds": 3600,
+  "price":            600,
+  "down_limit":       10,
+  "down_unit":        2,
+  "up_limit":         5,
+  "up_unit":          2,
+  "display_order":    1,
+  "is_active":        1
+}
+```
+
+**Response `200`:** Updated plan object.
+
+> Set `is_active: 0` to hide a plan from the portal without deleting it.
+
+---
+
+### DELETE `/api/plans/:id`
+Deactivate a plan (soft delete — it stops appearing on the portal).
+
+**Auth:** Required
+
+**Response `200`:**
+```json
+{ "message": "Plan deactivated" }
+```
+
+---
+
+## 4. Tenant — Dashboard
+
+---
+
+### GET `/api/dashboard/summary`
+Main dashboard overview for the authenticated tenant.
+
+**Auth:** Required
+
+**Response `200`:**
+```json
+{
+  "balance":         45000.00,
+  "total_earned":    320000.00,
+  "total_withdrawn": 275000.00,
+  "alert_count":     2,
+  "devices": [
+    {
+      "id": 3,
+      "name": "Main Building",
+      "location": "Floor 1",
+      "status": "online",
+      "billing_status": "active",
+      "billing_expires_at": "2026-05-15T00:00:00.000Z",
+      "model": "EAP110-Outdoor",
+      "cpu_util": 12,
+      "mem_util": 63,
+      "guest_count": 4,
+      "last_seen_at": "2026-04-15T11:30:00.000Z",
+      "sales_today": 12,
+      "earned_today": 11400.00,
+      "guests_online": 4
+    }
+  ]
+}
+```
+
+---
+
+### GET `/api/dashboard/revenue/weekly`
+Last 7 days of revenue broken down by day.
+
+**Auth:** Required
+
+**Response `200`:**
+```json
+[
+  {
+    "day":   "2026-04-15",
+    "sales": 12,
+    "gross": 12000.00,
+    "net":   11340.00
+  }
+]
+```
+
+> `net` = `gross` minus Snippe fee (0.5%) minus platform commission (varies by tenant, default 5%).  
+> Days with no sales are omitted — fill gaps in the frontend.
+
+---
+
+## 5. Tenant — Sessions
+
+---
+
+### GET `/api/sessions/active`
+All currently active guest sessions across all devices.
+
+**Auth:** Required
+
+**Response `200`:**
+```json
+[
+  {
+    "id": 201,
+    "client_mac": "2A-61-D9-9B-90-7C",
+    "client_ip":  "192.168.1.156",
+    "ssid":       "Sunset Hostel WiFi",
+    "started_at": "2026-04-15T09:00:00.000Z",
+    "last_seen_at": "2026-04-15T11:25:00.000Z",
+    "bytes_down": 4321769,
+    "bytes_up":   6990620,
+    "duration_seconds": 8700,
+    "rssi":        -42,
+    "signal_level": 80,
+    "device_name":  "Main Building",
+    "token_code":   "ABCD-1234",
+    "expires_at":   "2026-04-15T11:00:00.000Z",
+    "plan_name":    "2 Hour Plan"
+  }
+]
+```
+
+---
+
+### GET `/api/sessions`
+Session history (active and ended).
+
+**Auth:** Required  
+**Query params:**
+- `deviceId` *(optional)* — filter by device
+- `limit` *(optional, default 50)* — max records to return
+
+**Response `200`:** Array of session objects including `ended_at` and `is_active`.
+
+---
+
+## 6. Tenant — Payouts
+
+Tenants withdraw their earned balance via M-Pesa.
+
+---
+
+### GET `/api/payouts`
+Payout history for the authenticated tenant (last 50).
+
+**Auth:** Required
+
+**Response `200`:**
+```json
+[
+  {
+    "id": 5,
+    "amount": 50000.00,
+    "payout_fee": 1500.00,
+    "net_amount": 48500.00,
+    "destination_phone": "0712345678",
+    "destination_provider": "mpesa",
+    "status": "completed",
+    "failure_reason": null,
+    "created_at": "2026-04-10T14:00:00.000Z",
+    "completed_at": "2026-04-10T14:02:00.000Z"
+  }
+]
+```
+
+**`status` values:** `pending` · `processing` · `completed` · `failed`
+
+---
+
+### POST `/api/payouts`
+Request a withdrawal to M-Pesa.
+
+**Auth:** Required
+
+**Body:**
+```json
+{
+  "amount":   50000,
+  "phone":    "0712345678",
+  "provider": "mpesa"
+}
+```
+
+**Validation:**
+- `amount` minimum: 5,000 TZS
+- `amount` must not exceed `balance`
+- `provider` options: `mpesa` · `airtel` · `tigo` · `halopesa` (default: `mpesa`)
+
+**Response `201`:**
+```json
+{
+  "id": 6,
+  "amount": 50000,
+  "payout_fee": 1500,
+  "net_amount": 48500,
+  "status": "processing",
+  "message": "Payout initiated. Funds will arrive shortly."
+}
+```
+
+> Balance is deducted immediately on request. If the payout fails, balance is automatically restored. Tenant receives an SMS on completion or failure.
+
+---
+
+## 7. Tenant — Alerts
+
+Alerts are AP events synced from the Omada controller (device offline, client blocked, etc.).
+
+---
+
+### GET `/api/alerts/unresolved`
+All unresolved alerts for the tenant (last 50, newest first).
+
+**Auth:** Required
+
+**Response `200`:**
+```json
+[
+  {
+    "id": 12,
+    "alert_key": "DEV_DISCONN",
+    "level": "error",
+    "content": "[ap:24-2F-D0-DF-19-9C] was disconnected.",
+    "device_mac": "24-2F-D0-DF-19-9C",
+    "alert_time": "2026-04-15T08:00:00.000Z",
+    "fetched_at": "2026-04-15T08:15:00.000Z",
+    "device_name": "Main Building"
+  }
+]
+```
+
+**`level` values:** `info` · `warning` · `error` · `critical`  
+**Common `alert_key` values:** `DEV_DISCONN` · `DEV_CONN` · `CLIENT_BLOCK`
+
+---
+
+### PATCH `/api/alerts/:id/resolve`
+Mark an alert as resolved.
+
+**Auth:** Required
+
+**Response `200`:**
+```json
+{ "message": "Alert resolved" }
+```
+
+---
+
+## 8. Super Admin
+
+All admin endpoints require a static admin token passed as a Bearer token.  
+This is a **separate secret** from tenant JWTs — set via `ADMIN_TOKEN` environment variable.
+
+```
+Authorization: Bearer <ADMIN_TOKEN>
+```
+
+---
+
+### GET `/api/admin/overview`
+Platform-wide stats for the admin dashboard.
+
+**Response `200`:**
+```json
+{
+  "tenants": 24,
+  "devices_online": 18,
+  "devices_offline": 3,
+  "devices_suspended": 2,
+  "guests_online": 47,
+  "sales_today": 312,
+  "gross_today": 312000.00,
+  "commission_today": 15600.00,
+  "snippe_fees_today": 1560.00,
+  "pending_payouts": 5,
+  "pending_payout_total": 230000.00
+}
+```
+
+---
+
+### GET `/api/admin/tenants`
+List all tenants with device counts.
+
+**Response `200`:**
+```json
+[
+  {
+    "id": 1,
+    "business_name": "Sunset Hostel",
+    "contact_name": "John Doe",
+    "email": "john@sunset.co.tz",
+    "phone": "0712345678",
+    "balance": 45000.00,
+    "total_earned": 320000.00,
+    "total_withdrawn": 275000.00,
+    "is_active": 1,
+    "created_at": "2026-03-01T08:00:00.000Z",
+    "device_count": 2,
+    "devices_online": 1
+  }
+]
+```
+
+---
+
+### GET `/api/admin/devices`
+List all devices across all tenants.
+
+**Response `200`:**
+```json
+[
+  {
+    "id": 3,
+    "name": "Main Building",
+    "location": "Floor 1",
+    "mac": "24-2F-D0-DF-19-9C",
+    "model": "EAP110-Outdoor",
+    "status": "online",
+    "billing_status": "active",
+    "billing_expires_at": "2026-05-15T00:00:00.000Z",
+    "monthly_fee": 20000.00,
+    "cpu_util": 12,
+    "mem_util": 63,
+    "guest_count": 4,
+    "last_seen_at": "2026-04-15T11:30:00.000Z",
+    "business_name": "Sunset Hostel",
+    "client_phone": "0712345678"
+  }
+]
+```
+
+---
+
+### GET `/api/admin/payouts/pending`
+All payouts in `pending` or `processing` state across all tenants.
+
+**Response `200`:**
+```json
+[
+  {
+    "id": 6,
+    "amount": 50000.00,
+    "payout_fee": 1500.00,
+    "net_amount": 48500.00,
+    "destination_phone": "0712345678",
+    "destination_provider": "mpesa",
+    "status": "processing",
+    "created_at": "2026-04-15T10:00:00.000Z",
+    "business_name": "Sunset Hostel",
+    "contact_name": "John Doe"
+  }
+]
+```
+
+---
+
+### GET `/api/admin/revenue/daily?days=30`
+Daily revenue breakdown across the entire platform.
+
+**Query:** `days` *(optional, default 30)*
+
+**Response `200`:**
+```json
+[
+  {
+    "day": "2026-04-15",
+    "sales": 312,
+    "gross": 312000.00,
+    "commission": 15600.00,
+    "tenant_credit": 294840.00
+  }
+]
+```
+
+---
+
+### POST `/api/admin/devices/:id/reboot`
+Send a reboot command to a specific AP via Omada.
+
+**Response `200`:**
+```json
+{ "message": "Reboot command sent" }
+```
+
+---
+
+## 9. Captive Portal (Public)
+
+These endpoints are hit by the AP firmware redirect and the guest's browser. No authentication required.
+
+---
+
+### GET `/portal/:siteId?clientMac=&apMac=&ssidName=`
+Render the captive portal page for a guest.
+
+**Query params (injected by Omada redirect):**
+- `clientMac` — guest's MAC address
+- `apMac` — AP MAC address
+- `ssidName` — SSID name
+
+**Behavior:**
+- If device is suspended/cancelled → renders **"Subscription Required"** page
+- If guest MAC has a valid active token → **auto-reconnects** silently and renders **"Welcome Back"** page
+- Otherwise → renders the **portal** with available plans
+
+> This is a server-rendered EJS page, not a JSON API.
+
+---
+
+### POST `/portal/:siteId/purchase`
+Guest initiates a WiFi plan purchase.
+
+**Body:**
+```json
+{
+  "planId": 7,
+  "phone":  "0712345678"
+}
+```
+
+**Response `200`:**
+```json
+{
+  "reference": "abc123def456ghi789jkl",
+  "status": "pending"
+}
+```
+
+> An M-Pesa payment prompt is sent to `phone`. Poll `/check/:reference` to track completion.
+
+---
+
+### GET `/portal/:siteId/check/:reference`
+Poll payment status after purchase.
+
+**Response — pending:**
+```json
+{ "status": "pending" }
+```
+
+**Response — paid:**
+```json
+{
+  "status":    "paid",
+  "code":      "ABCD-1234",
+  "plan_name": "1 Hour Browsing"
+}
+```
+
+**Response — failed:**
+```json
+{ "status": "failed" }
+```
+
+---
+
+### POST `/portal/:siteId/auth`
+Authorize a guest on the WiFi using their access code.
+
+**Body:**
+```json
+{
+  "code":      "ABCD-1234",
+  "clientMac": "2a:61:d9:9b:90:7c"
+}
+```
+
+**Response `200`:**
+```json
+{
+  "success":   true,
+  "code":      "ABCD-1234",
+  "expiresIn": 3600,
+  "expiresAt": "2026-04-15T13:00:00.000Z",
+  "speedDown": "5Mbps",
+  "speedUp":   "2Mbps"
+}
+```
+
+**Error responses:**
+- `404` — code not found
+- `403` — code locked to a different device MAC
+- `410` — code expired
+- `503` — AP offline, authorization failed
+
+> The code is locked to the guest's MAC on first use. The same guest can reconnect later using the same code — they'll be re-authorized automatically without re-entering it.
+
+---
+
+## 10. Error Format
+
+All errors follow this shape:
+
+```json
+{ "error": "Human-readable message" }
+```
+
+| Status | Meaning |
+|--------|---------|
+| `400` | Bad request — missing or invalid fields |
+| `401` | Not authenticated or invalid token |
+| `403` | Forbidden — resource belongs to another user |
+| `404` | Resource not found |
+| `409` | Conflict — duplicate email, phone, or MAC |
+| `410` | Gone — token expired or revoked |
+| `500` | Server error |
+| `502` | Upstream error (Omada or Snippe unreachable) |
+| `503` | Service unavailable (AP offline) |
+
+---
+
+## 11. Enums & Constants
+
+### Device `status`
+| Value | Meaning |
+|-------|---------|
+| `pending` | Registered, AP not yet visible to Omada |
+| `adopting` | Omada adoption in progress |
+| `online` | AP connected and serving guests |
+| `offline` | AP disconnected |
+| `removed` | Decommissioned |
+
+### Device `billing_status`
+| Value | Meaning |
+|-------|---------|
+| `trial` | Free trial period (default 14 days) |
+| `active` | Subscription paid and active |
+| `suspended` | Billing expired or manually paused — portal blocked |
+| `cancelled` | Permanently decommissioned |
+
+### Access token `status`
+| Value | Meaning |
+|-------|---------|
+| `unused` | Paid for, not yet activated |
+| `active` | In use — locked to a MAC |
+| `expired` | Time ran out |
+| `revoked` | Cancelled (device suspended/paused) |
+
+### Speed `unit`
+| Value | Meaning |
+|-------|---------|
+| `1` | Kbps |
+| `2` | Mbps |
+
+### Alert `level`
+| Value | Meaning |
+|-------|---------|
+| `info` | Informational |
+| `warning` | Non-critical issue |
+| `error` | AP disconnected or serious event |
+| `critical` | Requires immediate action |
+
+### Payout / Payment `status`
+| Value | Meaning |
+|-------|---------|
+| `pending` | Created, waiting for M-Pesa |
+| `processing` | M-Pesa prompt sent |
+| `completed` | Funds transferred |
+| `failed` | Payment/payout failed |
+
+---
+
+## 12. UI Building Guide
+
+### Tenant Dashboard — Recommended Pages
+
+| Page | Key endpoints |
+|------|--------------|
+| Login / Register | `POST /api/auth/login`, `POST /api/auth/register` |
+| Dashboard Home | `GET /api/dashboard/summary`, `GET /api/dashboard/revenue/weekly` |
+| Devices List | `GET /api/devices` |
+| Device Detail | `GET /api/devices/:id`, `GET /api/plans?deviceId=`, `GET /api/sessions/active` |
+| Add Device | `POST /api/devices` |
+| Manage Plans | `POST /api/plans`, `PUT /api/plans/:id`, `DELETE /api/plans/:id` |
+| Session History | `GET /api/sessions` |
+| Payouts | `GET /api/payouts`, `POST /api/payouts` |
+| Alerts | `GET /api/alerts/unresolved`, `PATCH /api/alerts/:id/resolve` |
+| Profile | `GET /api/auth/me` |
+
+### Super Admin Panel — Recommended Pages
+
+| Page | Key endpoints |
+|------|--------------|
+| Admin Overview | `GET /api/admin/overview` |
+| Tenants List | `GET /api/admin/tenants` |
+| Devices List | `GET /api/admin/devices` |
+| Pending Payouts | `GET /api/admin/payouts/pending` |
+| Revenue Chart | `GET /api/admin/revenue/daily?days=30` |
+| Device Actions | `POST /api/admin/devices/:id/reboot` |
+
+### Key UX Notes for Frontend
+
+**Device status indicators:**
+- Show `online` as green, `offline` as red, `adopting` as yellow spinner, `pending` as grey
+- `billing_status = 'suspended'` should show a prominent "Renew" CTA regardless of `status`
+- Show `billing_expires_at` with a warning if within 3 days
+
+**Balance display:**
+- `balance` = available to withdraw right now
+- `total_earned - total_withdrawn` should equal `balance` (use for sanity check display)
+- Show earnings chart from `revenue/weekly` on dashboard home
+
+**Payout flow:**
+1. Show current `balance` from `GET /api/auth/me`
+2. `POST /api/payouts` — deducts balance immediately on submit
+3. Poll or refresh `GET /api/payouts` to show updated status
+4. Show `net_amount` (after fee) prominently, not `amount`
+
+**Device renewal flow:**
+1. `POST /api/devices/:id/renew`
+2. Inform user to check their phone for M-Pesa prompt
+3. Poll `GET /api/devices/:id` until `billing_status = 'active'`
+
+**Alert badge:**
+- Use `alert_count` from `GET /api/dashboard/summary` for the sidebar badge
+- Refresh count after `PATCH /api/alerts/:id/resolve`
+
+**Data formatting:**
+- All amounts are TZS (Tanzanian Shilling) — display with `.toLocaleString()`
+- `bytes_down` / `bytes_up` are raw bytes — convert to MB/GB for display
+- `duration_seconds` — convert to human readable (e.g. `3600` → `1h`, `86400` → `1 day`)
+- All timestamps are UTC ISO strings — convert to local time for display
+
+**Icons and visuals:**
+- **Do not use emojis** anywhere in the UI. Use SVG icons exclusively (e.g. Lucide, Heroicons, Feather, or inline SVG).
+- Emojis render inconsistently across operating systems, fonts, and browsers — SVGs are predictable and styleable.
+- Icon stroke color should use the active theme's primary color or semantic colors (green for success, amber for warning, red for error).
+- Recommended semantic icon mappings:
+  - WiFi / connected → `wifi` icon, stroke = primary color
+  - Success / authorized → `check-circle` icon, stroke = `#22c55e`
+  - Suspended / locked → `lock` icon, stroke = `#f59e0b`
+  - Error / failed → `x-circle` icon, stroke = `#ef4444`
+  - Offline / disconnected → `wifi-off` icon, stroke = `#9ca3af`
+  - Device / AP → `radio` or `router` icon
+  - Payout → `send` or `credit-card` icon
+  - Alert → `alert-triangle` icon, stroke = `#f59e0b`

Dockerfile

@@ -0,0 +1,7 @@
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+EXPOSE 3000
+CMD ["node", "src/server.js"]

docker-compose.yml

@@ -0,0 +1,44 @@
+version: '3.8'
+
+services:
+  mysql:
+    image: mysql:8.0
+    container_name: wifi_mysql
+    restart: unless-stopped
+    environment:
+      MYSQL_ROOT_PASSWORD: rootpass
+      MYSQL_DATABASE: wifiplatform
+      MYSQL_USER: wifiuser
+      MYSQL_PASSWORD: wifipass
+    ports:
+      - "3306:3306"
+    volumes:
+      - mysql_data:/var/lib/mysql
+      - ./schema.sql:/docker-entrypoint-initdb.d/01_schema.sql
+    command: >
+      --character-set-server=utf8mb4
+      --collation-server=utf8mb4_unicode_ci
+      --default-authentication-plugin=mysql_native_password
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "wifiuser", "-pwifipass"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  app:
+    build: .
+    container_name: wifi_app
+    restart: unless-stopped
+    depends_on:
+      mysql:
+        condition: service_healthy
+    env_file: .env
+    environment:
+      DB_HOST: mysql
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./public:/app/public
+
+volumes:
+  mysql_data:

package.json

@@ -0,0 +1,26 @@
+{
+  "name": "wifi-platform",
+  "version": "1.0.0",
+  "description": "Multi-tenant WiFi hotspot platform",
+  "main": "src/server.js",
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "nodemon src/server.js"
+  },
+  "dependencies": {
+    "axios": "^1.6.8",
+    "bcryptjs": "^2.4.3",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "ejs": "^3.1.10",
+    "express": "^4.18.3",
+    "express-rate-limit": "^7.3.1",
+    "jsonwebtoken": "^9.0.2",
+    "mysql2": "^3.9.2",
+    "node-cron": "^3.0.3",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.0"
+  }
+}

public/engine.js

@@ -0,0 +1,252 @@
+/**
+ * WiFi Portal Engine
+ * Handles the guest payment & authorization flow.
+ * Requires window.PORTAL to be set before this script loads.
+ */
+(function () {
+  'use strict';
+
+  const P = window.PORTAL;
+  if (!P) return;
+
+  // ── DOM refs ──────────────────────────────────────────────────────────────
+  const $ = id => document.getElementById(id);
+
+  const screens = {
+    select:   $('screen-select'),
+    waiting:  $('screen-waiting'),
+    code:     $('screen-code'),
+    success:  $('screen-success'),
+  };
+
+  function showScreen(name) {
+    Object.values(screens).forEach(s => s && s.classList.remove('active'));
+    if (screens[name]) screens[name].classList.add('active');
+  }
+
+  function showError(elId, msg) {
+    const el = $(elId);
+    if (!el) return;
+    el.textContent = msg;
+    el.classList.add('show');
+  }
+
+  function clearError(elId) {
+    const el = $(elId);
+    if (el) { el.textContent = ''; el.classList.remove('show'); }
+  }
+
+  // ── State ─────────────────────────────────────────────────────────────────
+  let selectedPlanId    = null;
+  let selectedPlanPrice = null;
+  let pollTimer         = null;
+  let currentReference  = null;
+
+  // ── Plan selection ────────────────────────────────────────────────────────
+  const planBtns = document.querySelectorAll('.plan-btn');
+  const payBtn   = $('pay-btn');
+  const phoneInput = $('phone-input');
+
+  planBtns.forEach(btn => {
+    btn.addEventListener('click', () => {
+      planBtns.forEach(b => b.classList.remove('selected'));
+      btn.classList.add('selected');
+      selectedPlanId    = btn.dataset.planId;
+      selectedPlanPrice = btn.dataset.planPrice;
+      if (payBtn) {
+        payBtn.textContent = `Pay ${parseInt(selectedPlanPrice).toLocaleString()} TZS & Connect`;
+        payBtn.disabled    = false;
+      }
+    });
+  });
+
+  // ── Pay button ────────────────────────────────────────────────────────────
+  if (payBtn) {
+    payBtn.addEventListener('click', async () => {
+      clearError('select-error');
+      const phone = phoneInput?.value?.trim();
+      if (!selectedPlanId) return showError('select-error', 'Please select a plan.');
+      if (!phone || phone.replace(/\D/g, '').length < 9) {
+        return showError('select-error', 'Enter a valid phone number.');
+      }
+
+      payBtn.disabled = true;
+      showScreen('waiting');
+
+      try {
+        const res = await fetch(`/portal/${P.siteId}/purchase`, {
+          method:  'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body:    JSON.stringify({ planId: selectedPlanId, phone }),
+        });
+        const data = await res.json();
+
+        if (!res.ok || !data.reference) {
+          showScreen('select');
+          payBtn.disabled = false;
+          return showError('select-error', data.error || 'Purchase failed. Try again.');
+        }
+
+        currentReference = data.reference;
+        startPolling(data.reference);
+      } catch (err) {
+        showScreen('select');
+        payBtn.disabled = false;
+        showError('select-error', 'Network error. Please try again.');
+      }
+    });
+  }
+
+  // ── Polling ───────────────────────────────────────────────────────────────
+  function startPolling(reference) {
+    let attempts = 0;
+    const MAX    = 100; // ~5 min at 3s
+
+    clearInterval(pollTimer);
+    pollTimer = setInterval(async () => {
+      attempts++;
+      if (attempts > MAX) {
+        clearInterval(pollTimer);
+        showScreen('select');
+        if (payBtn) payBtn.disabled = false;
+        showError('select-error', 'Payment timed out. Please try again.');
+        return;
+      }
+
+      try {
+        const res  = await fetch(`/portal/${P.siteId}/check/${reference}`);
+        const data = await res.json();
+
+        if (data.status === 'paid' && data.code) {
+          clearInterval(pollTimer);
+          await authorizeWithCode(data.code);
+        } else if (data.status === 'failed') {
+          clearInterval(pollTimer);
+          showScreen('select');
+          if (payBtn) payBtn.disabled = false;
+          showError('select-error', 'Payment was declined. Please try again.');
+        }
+      } catch { /* network blip — keep polling */ }
+    }, 3000);
+  }
+
+  // Cancel button
+  const cancelBtn = $('cancel-btn');
+  if (cancelBtn) {
+    cancelBtn.addEventListener('click', () => {
+      clearInterval(pollTimer);
+      showScreen('select');
+      if (payBtn) payBtn.disabled = false;
+    });
+  }
+
+  // ── Auth with code ────────────────────────────────────────────────────────
+  async function authorizeWithCode(code) {
+    try {
+      const res  = await fetch(`/portal/${P.siteId}/auth`, {
+        method:  'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body:    JSON.stringify({ code, clientMac: P.clientMac }),
+      });
+      const data = await res.json();
+
+      if (!res.ok || !data.success) {
+        showScreen('select');
+        if (payBtn) payBtn.disabled = false;
+        showError('select-error', data.error || 'Authorization failed. Enter your code manually.');
+        return;
+      }
+
+      showSuccess(data);
+    } catch (err) {
+      // Show code entry as fallback so guest can manually enter
+      showCodeEntry(code);
+    }
+  }
+
+  function showSuccess(data) {
+    const codeEl = $('success-code');
+    if (codeEl) codeEl.textContent = data.code || '—';
+
+    const metaEl = $('success-meta');
+    if (metaEl) {
+      const hours = data.expiresIn ? Math.ceil(data.expiresIn / 3600) : '?';
+      metaEl.innerHTML = `
+        <div class="meta-row"><span>Speed</span><strong>${data.speedDown} ↓ / ${data.speedUp} ↑</strong></div>
+        <div class="meta-row"><span>Valid for</span><strong>${hours < 24 ? hours + 'h' : Math.ceil(hours/24) + 'd'}</strong></div>
+        <div class="meta-row"><span>Reconnect?</span><strong>Enter code above on login page</strong></div>
+      `;
+    }
+    showScreen('success');
+  }
+
+  // ── Code entry (reconnect) ────────────────────────────────────────────────
+  const showCodeEntryLink = $('show-code-entry');
+  const showPlansLink     = $('show-plans');
+  const codeInput         = $('code-input');
+  const codeSubmitBtn     = $('code-submit-btn');
+
+  if (showCodeEntryLink) {
+    showCodeEntryLink.addEventListener('click', () => {
+      clearError('code-error');
+      showScreen('code');
+    });
+  }
+  if (showPlansLink) {
+    showPlansLink.addEventListener('click', () => showScreen('select'));
+  }
+
+  function showCodeEntry(prefill) {
+    if (codeInput && prefill) codeInput.value = prefill;
+    clearError('code-error');
+    showScreen('code');
+  }
+
+  if (codeInput) {
+    codeInput.addEventListener('input', () => {
+      // Auto-insert dash after 4 chars
+      let v = codeInput.value.toUpperCase().replace(/[^A-Z0-9]/g, '');
+      if (v.length > 4) v = v.slice(0, 4) + '-' + v.slice(4, 8);
+      codeInput.value = v;
+    });
+  }
+
+  if (codeSubmitBtn) {
+    codeSubmitBtn.addEventListener('click', async () => {
+      clearError('code-error');
+      const code = codeInput?.value?.trim();
+      if (!code || code.length < 9) {
+        return showError('code-error', 'Enter a valid 8-character code (XXXX-XXXX).');
+      }
+
+      codeSubmitBtn.disabled = true;
+      codeSubmitBtn.textContent = 'Connecting...';
+
+      try {
+        const res  = await fetch(`/portal/${P.siteId}/auth`, {
+          method:  'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body:    JSON.stringify({ code, clientMac: P.clientMac }),
+        });
+        const data = await res.json();
+
+        if (!res.ok || !data.success) {
+          showError('code-error', data.error || 'Code not valid or expired.');
+        } else {
+          showSuccess(data);
+        }
+      } catch {
+        showError('code-error', 'Network error. Please try again.');
+      } finally {
+        codeSubmitBtn.disabled = false;
+        codeSubmitBtn.textContent = 'Connect';
+      }
+    });
+  }
+
+  // If clientMac is missing (portal opened in browser), warn in console only
+  if (!P.clientMac) {
+    console.warn('[WiFi Portal] No clientMac — running in preview mode');
+  }
+
+})();

schema.sql

@@ -0,0 +1,510 @@
+-- =============================================
+-- OMADA MULTI-TENANT WIFI PLATFORM
+-- Final Schema
+-- =============================================
+
+SET NAMES utf8mb4;
+SET FOREIGN_KEY_CHECKS = 0;
+
+
+-- =============================================
+-- TABLE 1: clients
+-- =============================================
+DROP TABLE IF EXISTS `clients`;
+CREATE TABLE `clients` (
+  `id`                INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  `business_name`     VARCHAR(100)   NOT NULL,
+  `contact_name`      VARCHAR(100)   NOT NULL,
+  `email`             VARCHAR(255)   NOT NULL,
+  `phone`             VARCHAR(20)    NOT NULL,
+  `password_hash`     VARCHAR(255)   NOT NULL,
+  `commission_rate`   DECIMAL(5,4)   NOT NULL DEFAULT 0.0500,
+  `balance`           DECIMAL(12,2)  NOT NULL DEFAULT 0.00,
+  `total_earned`      DECIMAL(12,2)  NOT NULL DEFAULT 0.00,
+  `total_withdrawn`   DECIMAL(12,2)  NOT NULL DEFAULT 0.00,
+  `is_active`         TINYINT(1)     NOT NULL DEFAULT 1,
+  `created_at`        TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `updated_at`        TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  UNIQUE KEY `uk_email` (`email`),
+  UNIQUE KEY `uk_phone` (`phone`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TABLE 2: client_staff
+-- =============================================
+DROP TABLE IF EXISTS `client_staff`;
+CREATE TABLE `client_staff` (
+  `id`            INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  `client_id`     INT UNSIGNED   NOT NULL,
+  `name`          VARCHAR(100)   NOT NULL,
+  `email`         VARCHAR(255)   NOT NULL,
+  `phone`         VARCHAR(20)    DEFAULT NULL,
+  `password_hash` VARCHAR(255)   NOT NULL,
+  `role`          ENUM('manager','viewer') NOT NULL DEFAULT 'viewer',
+  `is_active`     TINYINT(1)     NOT NULL DEFAULT 1,
+  `created_at`    TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE KEY `uk_staff_email` (`email`),
+  KEY `idx_staff_client` (`client_id`),
+  CONSTRAINT `fk_staff_client` FOREIGN KEY (`client_id`)
+    REFERENCES `clients`(`id`) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TABLE 3: devices
+-- =============================================
+DROP TABLE IF EXISTS `devices`;
+CREATE TABLE `devices` (
+  `id`                INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  `client_id`         INT UNSIGNED   NOT NULL,
+  `name`              VARCHAR(100)   NOT NULL,
+  `location`          VARCHAR(255)   DEFAULT NULL,
+  `omada_site_id`     VARCHAR(64)    DEFAULT NULL,
+  `omada_portal_id`   VARCHAR(64)    DEFAULT NULL,
+  `device_username`   VARCHAR(50)    DEFAULT NULL,
+  `device_password`   VARCHAR(100)   DEFAULT NULL,
+  `mac`               VARCHAR(17)    NOT NULL,
+  `model`             VARCHAR(50)    DEFAULT NULL,
+  `firmware_version`  VARCHAR(100)   DEFAULT NULL,
+  `ip`                VARCHAR(45)    DEFAULT NULL,
+  `public_ip`         VARCHAR(45)    DEFAULT NULL,
+  `portal_html_path`  VARCHAR(255)   DEFAULT NULL,
+  `status`            ENUM('pending','adopting','online','offline','removed') NOT NULL DEFAULT 'pending',
+  `registered_at`     TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `adopted_at`        TIMESTAMP      NULL DEFAULT NULL,
+  `last_seen_at`      TIMESTAMP      NULL DEFAULT NULL,
+  `billing_status`    ENUM('trial','active','suspended','cancelled') NOT NULL DEFAULT 'trial',
+  `billing_expires_at` TIMESTAMP     NULL DEFAULT NULL,
+  `monthly_fee`       DECIMAL(10,2)  NOT NULL DEFAULT 20000.00,
+  `cpu_util`          TINYINT UNSIGNED DEFAULT NULL,
+  `mem_util`          TINYINT UNSIGNED DEFAULT NULL,
+  `client_count`      SMALLINT UNSIGNED DEFAULT 0,
+  `guest_count`       SMALLINT UNSIGNED DEFAULT 0,
+  `uptime_seconds`    INT UNSIGNED   DEFAULT 0,
+  `download_bytes`    BIGINT UNSIGNED DEFAULT 0,
+  `upload_bytes`      BIGINT UNSIGNED DEFAULT 0,
+  `needs_upgrade`     TINYINT(1)     NOT NULL DEFAULT 0,
+  UNIQUE KEY `uk_device_mac` (`mac`),
+  UNIQUE KEY `uk_omada_site` (`omada_site_id`),
+  KEY `idx_device_client` (`client_id`),
+  KEY `idx_device_status` (`status`),
+  KEY `idx_device_billing` (`billing_status`, `billing_expires_at`),
+  CONSTRAINT `fk_device_client` FOREIGN KEY (`client_id`)
+    REFERENCES `clients`(`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TABLE 4: device_payments
+-- =============================================
+DROP TABLE IF EXISTS `device_payments`;
+CREATE TABLE `device_payments` (
+  `id`                BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  `client_id`         INT UNSIGNED   NOT NULL,
+  `device_id`         INT UNSIGNED   NOT NULL,
+  `amount`            DECIMAL(10,2)  NOT NULL DEFAULT 20000.00,
+  `reference`         VARCHAR(64)    NOT NULL,
+  `snippe_payment_id` VARCHAR(100)   DEFAULT NULL,
+  `period_start`      DATE           NOT NULL,
+  `period_end`        DATE           NOT NULL,
+  `status`            ENUM('pending','completed','failed') NOT NULL DEFAULT 'pending',
+  `created_at`        TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `completed_at`      TIMESTAMP      NULL DEFAULT NULL,
+  UNIQUE KEY `uk_devpay_ref` (`reference`),
+  KEY `idx_devpay_client` (`client_id`),
+  KEY `idx_devpay_device` (`device_id`),
+  KEY `idx_devpay_status` (`status`),
+  CONSTRAINT `fk_devpay_client` FOREIGN KEY (`client_id`) REFERENCES `clients`(`id`),
+  CONSTRAINT `fk_devpay_device` FOREIGN KEY (`device_id`) REFERENCES `devices`(`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TABLE 5: device_status_log
+-- =============================================
+DROP TABLE IF EXISTS `device_status_log`;
+CREATE TABLE `device_status_log` (
+  `id`          BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  `device_id`   INT UNSIGNED NOT NULL,
+  `old_status`  VARCHAR(20)  NOT NULL,
+  `new_status`  VARCHAR(20)  NOT NULL,
+  `reason`      VARCHAR(255) DEFAULT NULL,
+  `created_at`  TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  KEY `idx_devlog_device` (`device_id`),
+  KEY `idx_devlog_time` (`created_at`),
+  CONSTRAINT `fk_devlog_device` FOREIGN KEY (`device_id`)
+    REFERENCES `devices`(`id`) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TABLE 6: wifi_plans
+-- =============================================
+DROP TABLE IF EXISTS `wifi_plans`;
+CREATE TABLE `wifi_plans` (
+  `id`                INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  `client_id`         INT UNSIGNED   NOT NULL,
+  `device_id`         INT UNSIGNED   NOT NULL,
+  `name`              VARCHAR(50)    NOT NULL,
+  `duration_seconds`  INT UNSIGNED   NOT NULL,
+  `price`             DECIMAL(10,2)  NOT NULL,
+  `down_limit`        SMALLINT UNSIGNED NOT NULL DEFAULT 2,
+  `down_unit`         TINYINT UNSIGNED NOT NULL DEFAULT 2 COMMENT '1=Kbps 2=Mbps',
+  `up_limit`          SMALLINT UNSIGNED NOT NULL DEFAULT 2,
+  `up_unit`           TINYINT UNSIGNED NOT NULL DEFAULT 2 COMMENT '1=Kbps 2=Mbps',
+  `display_order`     TINYINT UNSIGNED NOT NULL DEFAULT 0,
+  `is_active`         TINYINT(1)     NOT NULL DEFAULT 1,
+  `created_at`        TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `updated_at`        TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  KEY `idx_plan_client` (`client_id`),
+  KEY `idx_plan_device` (`device_id`),
+  KEY `idx_plan_active` (`device_id`, `is_active`, `display_order`),
+  CONSTRAINT `fk_plan_client` FOREIGN KEY (`client_id`) REFERENCES `clients`(`id`),
+  CONSTRAINT `fk_plan_device` FOREIGN KEY (`device_id`) REFERENCES `devices`(`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TABLE 7: payments
+-- =============================================
+DROP TABLE IF EXISTS `payments`;
+CREATE TABLE `payments` (
+  `id`                  BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  `reference`           VARCHAR(64)    NOT NULL,
+  `client_id`           INT UNSIGNED   NOT NULL,
+  `device_id`           INT UNSIGNED   NOT NULL,
+  `plan_id`             INT UNSIGNED   NOT NULL,
+  `phone`               VARCHAR(20)    NOT NULL,
+  `phone_provider`      ENUM('mpesa','airtel','tigo','halopesa') NOT NULL DEFAULT 'mpesa',
+  `gross_amount`        DECIMAL(10,2)  NOT NULL,
+  `snippe_fee`          DECIMAL(10,2)  NOT NULL DEFAULT 0.00,
+  `commission_rate`     DECIMAL(5,4)   NOT NULL DEFAULT 0.0500,
+  `commission_amount`   DECIMAL(10,2)  NOT NULL DEFAULT 0.00,
+  `client_credit`       DECIMAL(10,2)  NOT NULL DEFAULT 0.00,
+  `status`              ENUM('pending','completed','failed','refunded') NOT NULL DEFAULT 'pending',
+  `snippe_payment_id`   VARCHAR(100)   DEFAULT NULL,
+  `access_token_code`   VARCHAR(20)    DEFAULT NULL,
+  `created_at`          TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `completed_at`        TIMESTAMP      NULL DEFAULT NULL,
+  UNIQUE KEY `uk_reference` (`reference`),
+  KEY `idx_pay_client` (`client_id`),
+  KEY `idx_pay_device` (`device_id`),
+  KEY `idx_pay_status` (`status`),
+  KEY `idx_pay_completed` (`completed_at`),
+  CONSTRAINT `fk_pay_client` FOREIGN KEY (`client_id`) REFERENCES `clients`(`id`),
+  CONSTRAINT `fk_pay_device` FOREIGN KEY (`device_id`) REFERENCES `devices`(`id`),
+  CONSTRAINT `fk_pay_plan` FOREIGN KEY (`plan_id`) REFERENCES `wifi_plans`(`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TABLE 8: access_tokens
+-- =============================================
+DROP TABLE IF EXISTS `access_tokens`;
+CREATE TABLE `access_tokens` (
+  `id`                BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  `client_id`         INT UNSIGNED   NOT NULL,
+  `device_id`         INT UNSIGNED   NOT NULL,
+  `plan_id`           INT UNSIGNED   NOT NULL,
+  `payment_id`        BIGINT UNSIGNED DEFAULT NULL,
+  `code`              VARCHAR(20)    NOT NULL,
+  `duration_seconds`  INT UNSIGNED   NOT NULL,
+  `down_limit`        SMALLINT UNSIGNED NOT NULL DEFAULT 2,
+  `down_unit`         TINYINT UNSIGNED NOT NULL DEFAULT 2,
+  `up_limit`          SMALLINT UNSIGNED NOT NULL DEFAULT 2,
+  `up_unit`           TINYINT UNSIGNED NOT NULL DEFAULT 2,
+  `status`            ENUM('unused','active','expired','revoked') NOT NULL DEFAULT 'unused',
+  `locked_mac`        VARCHAR(17)    DEFAULT NULL,
+  `activated_at`      TIMESTAMP      NULL DEFAULT NULL,
+  `expires_at`        TIMESTAMP      NULL DEFAULT NULL,
+  `total_seconds_used` INT UNSIGNED  NOT NULL DEFAULT 0,
+  `total_bytes_down`  BIGINT UNSIGNED NOT NULL DEFAULT 0,
+  `total_bytes_up`    BIGINT UNSIGNED NOT NULL DEFAULT 0,
+  `created_at`        TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE KEY `uk_token_code` (`code`),
+  KEY `idx_token_client` (`client_id`),
+  KEY `idx_token_device` (`device_id`),
+  KEY `idx_token_status` (`status`),
+  KEY `idx_token_expires` (`status`, `expires_at`),
+  KEY `idx_token_payment` (`payment_id`),
+  CONSTRAINT `fk_token_client` FOREIGN KEY (`client_id`) REFERENCES `clients`(`id`),
+  CONSTRAINT `fk_token_device` FOREIGN KEY (`device_id`) REFERENCES `devices`(`id`),
+  CONSTRAINT `fk_token_plan` FOREIGN KEY (`plan_id`) REFERENCES `wifi_plans`(`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TABLE 9: sessions
+-- =============================================
+DROP TABLE IF EXISTS `sessions`;
+CREATE TABLE `sessions` (
+  `id`                BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  `access_token_id`   BIGINT UNSIGNED DEFAULT NULL,
+  `client_id`         INT UNSIGNED   NOT NULL,
+  `device_id`         INT UNSIGNED   DEFAULT NULL,
+  `client_mac`        VARCHAR(17)    NOT NULL,
+  `client_ip`         VARCHAR(45)    DEFAULT NULL,
+  `client_name`       VARCHAR(100)   DEFAULT NULL,
+  `ssid`              VARCHAR(64)    DEFAULT NULL,
+  `started_at`        TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `last_seen_at`      TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `ended_at`          TIMESTAMP      NULL DEFAULT NULL,
+  `duration_seconds`  INT UNSIGNED   NOT NULL DEFAULT 0,
+  `bytes_down`        BIGINT UNSIGNED NOT NULL DEFAULT 0,
+  `bytes_up`          BIGINT UNSIGNED NOT NULL DEFAULT 0,
+  `rssi`              SMALLINT       DEFAULT NULL,
+  `signal_level`      TINYINT UNSIGNED DEFAULT NULL,
+  `is_active`         TINYINT(1)     NOT NULL DEFAULT 1,
+  KEY `idx_sess_token` (`access_token_id`),
+  KEY `idx_sess_client` (`client_id`),
+  KEY `idx_sess_device` (`device_id`),
+  KEY `idx_sess_mac` (`client_mac`),
+  KEY `idx_sess_active` (`is_active`, `client_id`),
+  KEY `idx_sess_time` (`started_at`),
+  CONSTRAINT `fk_sess_token` FOREIGN KEY (`access_token_id`) REFERENCES `access_tokens`(`id`),
+  CONSTRAINT `fk_sess_client` FOREIGN KEY (`client_id`) REFERENCES `clients`(`id`),
+  CONSTRAINT `fk_sess_device` FOREIGN KEY (`device_id`) REFERENCES `devices`(`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TABLE 10: payouts
+-- =============================================
+DROP TABLE IF EXISTS `payouts`;
+CREATE TABLE `payouts` (
+  `id`                    BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  `client_id`             INT UNSIGNED   NOT NULL,
+  `amount`                DECIMAL(10,2)  NOT NULL,
+  `payout_fee`            DECIMAL(10,2)  NOT NULL DEFAULT 0.00,
+  `net_amount`            DECIMAL(10,2)  NOT NULL DEFAULT 0.00,
+  `destination_phone`     VARCHAR(20)    NOT NULL,
+  `destination_provider`  ENUM('mpesa','airtel','tigo','halopesa') NOT NULL DEFAULT 'mpesa',
+  `status`                ENUM('pending','processing','completed','failed') NOT NULL DEFAULT 'pending',
+  `snippe_disbursement_id` VARCHAR(100)  DEFAULT NULL,
+  `failure_reason`        VARCHAR(255)   DEFAULT NULL,
+  `created_at`            TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `completed_at`          TIMESTAMP      NULL DEFAULT NULL,
+  KEY `idx_payout_client` (`client_id`),
+  KEY `idx_payout_status` (`status`),
+  CONSTRAINT `fk_payout_client` FOREIGN KEY (`client_id`) REFERENCES `clients`(`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TABLE 11: balance_ledger
+-- =============================================
+DROP TABLE IF EXISTS `balance_ledger`;
+CREATE TABLE `balance_ledger` (
+  `id`            BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  `client_id`     INT UNSIGNED   NOT NULL,
+  `type`          ENUM('wifi_sale','payout','payout_reversal','adjustment','refund') NOT NULL,
+  `amount`        DECIMAL(10,2)  NOT NULL,
+  `balance_after` DECIMAL(12,2)  NOT NULL,
+  `reference_type` ENUM('payment','payout','manual') NOT NULL,
+  `reference_id`  BIGINT UNSIGNED NOT NULL,
+  `description`   VARCHAR(255)   DEFAULT NULL,
+  `created_at`    TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  KEY `idx_ledger_client` (`client_id`),
+  KEY `idx_ledger_time` (`created_at`),
+  KEY `idx_ledger_ref` (`reference_type`, `reference_id`),
+  CONSTRAINT `fk_ledger_client` FOREIGN KEY (`client_id`) REFERENCES `clients`(`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TABLE 12: omada_alerts
+-- =============================================
+DROP TABLE IF EXISTS `omada_alerts`;
+CREATE TABLE `omada_alerts` (
+  `id`              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  `client_id`       INT UNSIGNED   NOT NULL,
+  `device_id`       INT UNSIGNED   DEFAULT NULL,
+  `omada_alert_id`  VARCHAR(64)    NOT NULL,
+  `alert_key`       VARCHAR(50)    NOT NULL,
+  `module`          VARCHAR(50)    DEFAULT NULL,
+  `level`           ENUM('info','warning','error','critical') NOT NULL DEFAULT 'info',
+  `content`         TEXT           NOT NULL,
+  `device_mac`      VARCHAR(17)    DEFAULT NULL,
+  `resolved`        TINYINT(1)     NOT NULL DEFAULT 0,
+  `alert_time`      TIMESTAMP      NOT NULL,
+  `fetched_at`      TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE KEY `uk_omada_alert` (`omada_alert_id`),
+  KEY `idx_alert_client` (`client_id`),
+  KEY `idx_alert_device` (`device_id`),
+  KEY `idx_alert_unresolved` (`client_id`, `resolved`),
+  CONSTRAINT `fk_alert_client` FOREIGN KEY (`client_id`) REFERENCES `clients`(`id`),
+  CONSTRAINT `fk_alert_device` FOREIGN KEY (`device_id`) REFERENCES `devices`(`id`) ON DELETE SET NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TABLE 13: sms_log
+-- =============================================
+DROP TABLE IF EXISTS `sms_log`;
+CREATE TABLE `sms_log` (
+  `id`          BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  `phone`       VARCHAR(20)    NOT NULL,
+  `message`     VARCHAR(320)   NOT NULL,
+  `status`      ENUM('sent','delivered','failed') NOT NULL,
+  `gateway_id`  VARCHAR(100)   DEFAULT NULL,
+  `error`       VARCHAR(255)   DEFAULT NULL,
+  `created_at`  TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `delivered_at` TIMESTAMP     NULL DEFAULT NULL,
+  KEY `idx_sms_phone` (`phone`),
+  KEY `idx_sms_status` (`status`),
+  KEY `idx_sms_time` (`created_at`),
+  KEY `idx_sms_gateway` (`gateway_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TRIGGERS
+-- =============================================
+
+DROP TRIGGER IF EXISTS `trg_payment_completed`;
+DELIMITER $$
+CREATE TRIGGER `trg_payment_completed`
+BEFORE UPDATE ON `payments`
+FOR EACH ROW
+BEGIN
+  DECLARE v_new_balance DECIMAL(12,2);
+
+  IF OLD.status = 'pending' AND NEW.status = 'completed' THEN
+    SET NEW.snippe_fee        = ROUND(NEW.gross_amount * 0.005, 2);
+    SET NEW.commission_amount = ROUND(NEW.gross_amount * NEW.commission_rate, 2);
+    SET NEW.client_credit     = NEW.gross_amount - NEW.snippe_fee - NEW.commission_amount;
+    SET NEW.completed_at      = CURRENT_TIMESTAMP;
+
+    UPDATE `clients`
+    SET `balance`      = `balance` + NEW.client_credit,
+        `total_earned` = `total_earned` + NEW.client_credit
+    WHERE `id` = NEW.client_id;
+
+    SET v_new_balance = (SELECT `balance` FROM `clients` WHERE `id` = NEW.client_id);
+
+    INSERT INTO `balance_ledger`
+      (`client_id`, `type`, `amount`, `balance_after`, `reference_type`, `reference_id`, `description`)
+    VALUES
+      (NEW.client_id, 'wifi_sale', NEW.client_credit, v_new_balance, 'payment', NEW.id,
+       CONCAT('WiFi sale: ', NEW.gross_amount, ' TZS (fee: ', NEW.snippe_fee, ', comm: ', NEW.commission_amount, ')'));
+  END IF;
+END$$
+DELIMITER ;
+
+
+DROP TRIGGER IF EXISTS `trg_payout_requested`;
+DELIMITER $$
+CREATE TRIGGER `trg_payout_requested`
+AFTER INSERT ON `payouts`
+FOR EACH ROW
+BEGIN
+  DECLARE v_new_balance DECIMAL(12,2);
+
+  IF NEW.status = 'pending' THEN
+    UPDATE `clients`
+    SET `balance` = `balance` - NEW.amount
+    WHERE `id` = NEW.client_id;
+
+    SET v_new_balance = (SELECT `balance` FROM `clients` WHERE `id` = NEW.client_id);
+
+    INSERT INTO `balance_ledger`
+      (`client_id`, `type`, `amount`, `balance_after`, `reference_type`, `reference_id`, `description`)
+    VALUES
+      (NEW.client_id, 'payout', -NEW.amount, v_new_balance, 'payout', NEW.id,
+       CONCAT('Payout request: ', NEW.amount, ' TZS to ', NEW.destination_phone));
+  END IF;
+END$$
+DELIMITER ;
+
+
+DROP TRIGGER IF EXISTS `trg_payout_failed`;
+DELIMITER $$
+CREATE TRIGGER `trg_payout_failed`
+BEFORE UPDATE ON `payouts`
+FOR EACH ROW
+BEGIN
+  DECLARE v_new_balance DECIMAL(12,2);
+
+  IF OLD.status = 'pending' AND NEW.status = 'failed' THEN
+    UPDATE `clients`
+    SET `balance` = `balance` + OLD.amount
+    WHERE `id` = OLD.client_id;
+
+    SET v_new_balance = (SELECT `balance` FROM `clients` WHERE `id` = OLD.client_id);
+
+    INSERT INTO `balance_ledger`
+      (`client_id`, `type`, `amount`, `balance_after`, `reference_type`, `reference_id`, `description`)
+    VALUES
+      (OLD.client_id, 'payout_reversal', OLD.amount, v_new_balance, 'payout', OLD.id,
+       CONCAT('Payout failed: ', IFNULL(NEW.failure_reason, 'unknown')));
+  END IF;
+END$$
+DELIMITER ;
+
+
+DROP TRIGGER IF EXISTS `trg_payout_completed`;
+DELIMITER $$
+CREATE TRIGGER `trg_payout_completed`
+BEFORE UPDATE ON `payouts`
+FOR EACH ROW
+BEGIN
+  IF OLD.status IN ('pending','processing') AND NEW.status = 'completed' THEN
+    SET NEW.completed_at = CURRENT_TIMESTAMP;
+
+    UPDATE `clients`
+    SET `total_withdrawn` = `total_withdrawn` + OLD.amount
+    WHERE `id` = OLD.client_id;
+  END IF;
+END$$
+DELIMITER ;
+
+
+-- =============================================
+-- TABLE 14: device_portal_settings
+-- =============================================
+DROP TABLE IF EXISTS `device_portal_settings`;
+CREATE TABLE `device_portal_settings` (
+  `device_id`     INT UNSIGNED  NOT NULL PRIMARY KEY,
+  `display_name`  VARCHAR(100)  DEFAULT NULL COMMENT 'Overrides business_name on the portal',
+  `welcome_text`  VARCHAR(255)  DEFAULT NULL COMMENT 'Tagline shown under the name',
+  `logo_url`      VARCHAR(500)  DEFAULT NULL COMMENT 'Full URL to logo image',
+  `support_phone` VARCHAR(20)   DEFAULT NULL COMMENT 'Support number shown to guests',
+  `primary_color` VARCHAR(7)    NOT NULL DEFAULT '#4361ee' COMMENT 'Buttons and accents',
+  `bg_color`      VARCHAR(7)    NOT NULL DEFAULT '#1a1a2e' COMMENT 'Page background',
+  `updated_at`    TIMESTAMP     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  CONSTRAINT `fk_portal_settings_device`
+    FOREIGN KEY (`device_id`) REFERENCES `devices`(`id`) ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TABLE 15: password_resets
+-- =============================================
+DROP TABLE IF EXISTS `password_resets`;
+CREATE TABLE `password_resets` (
+  `id`         BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  `phone`      VARCHAR(20)  NOT NULL,
+  `otp`        VARCHAR(6)   NOT NULL,
+  `expires_at` TIMESTAMP    NOT NULL,
+  `used`       TINYINT(1)   NOT NULL DEFAULT 0,
+  `created_at` TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  KEY `idx_reset_phone` (`phone`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+
+-- =============================================
+-- TABLE 15: system_config
+-- =============================================
+DROP TABLE IF EXISTS `system_config`;
+CREATE TABLE `system_config` (
+  `key`         VARCHAR(64)   NOT NULL PRIMARY KEY,
+  `value`       VARCHAR(255)  NOT NULL,
+  `description` VARCHAR(255)  DEFAULT NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+INSERT INTO `system_config` (`key`, `value`, `description`) VALUES
+  ('admin_phone', '+255769590766', 'System admin phone — receives critical error alerts');
+
+
+SET FOREIGN_KEY_CHECKS = 1;

src/app.js

@@ -0,0 +1,53 @@
+const express = require('express');
+const cors    = require('cors');
+const path    = require('path');
+
+const app = express();
+
+// ── View engine ───────────────────────────────────────────────────────────────
+app.set('view engine', 'ejs');
+app.set('views', path.join(__dirname, 'views', 'screens'));
+
+// ── Static files ──────────────────────────────────────────────────────────────
+app.use(express.static(path.join(__dirname, '..', 'public')));
+
+// ── Middleware ────────────────────────────────────────────────────────────────
+app.use(cors());
+
+// NOTE: /api/webhooks/snippe needs raw body — mount it BEFORE json middleware
+app.use('/api/webhooks', require('./routes/webhooks.routes'));
+
+// JSON body parser for everything else
+app.use(express.json());
+app.use(express.urlencoded({ extended: false }));
+
+// ── Routes ────────────────────────────────────────────────────────────────────
+
+// Public captive portal
+app.use('/portal', require('./routes/portal.routes'));
+
+// Tenant API
+app.use('/api/auth',      require('./routes/auth.routes'));
+app.use('/api/devices',   require('./routes/devices.routes'));
+app.use('/api/plans',     require('./routes/plans.routes'));
+app.use('/api/dashboard', require('./routes/dashboard.routes'));
+app.use('/api/payouts',   require('./routes/payouts.routes'));
+app.use('/api/sessions',  require('./routes/sessions.routes'));
+app.use('/api/alerts',    require('./routes/alerts.routes'));
+
+// Admin API
+app.use('/api/admin', require('./routes/admin.routes'));
+
+// ── Health check ──────────────────────────────────────────────────────────────
+app.get('/health', (req, res) => res.json({ status: 'ok', ts: new Date() }));
+
+// ── 404 ───────────────────────────────────────────────────────────────────────
+app.use((req, res) => res.status(404).json({ error: 'Not found' }));
+
+// ── Error handler ─────────────────────────────────────────────────────────────
+app.use((err, req, res, next) => {
+  console.error('[Unhandled]', err.message);
+  res.status(500).json({ error: 'Internal server error' });
+});
+
+module.exports = app;

src/config/db.js

@@ -0,0 +1,25 @@
+const mysql = require('mysql2/promise');
+
+const pool = mysql.createPool({
+  host:             process.env.DB_HOST || 'localhost',
+  port:             parseInt(process.env.DB_PORT) || 3306,
+  user:             process.env.DB_USER || 'wifiuser',
+  password:         process.env.DB_PASS || 'wifipass',
+  database:         process.env.DB_NAME || 'wifiplatform',
+  waitForConnections: true,
+  connectionLimit:  20,
+  charset:          'utf8mb4',
+  timezone:         '+00:00',
+});
+
+async function query(sql, params = []) {
+  const [rows] = await pool.execute(sql, params);
+  return rows;
+}
+
+async function queryOne(sql, params = []) {
+  const rows = await query(sql, params);
+  return rows[0] || null;
+}
+
+module.exports = { pool, query, queryOne };

src/jobs/adoptDevices.job.js

@@ -0,0 +1,70 @@
+const db    = require('../config/db');
+const omada = require('../services/omada');
+
+async function adoptDevices() {
+  try {
+    const pending = await db.query(`
+      SELECT id, mac, omada_site_id, device_username, device_password
+      FROM devices
+      WHERE status = 'pending' AND omada_site_id IS NOT NULL
+    `);
+
+    if (!pending.length) return;
+
+    // Fetch sites once to get deviceAccount credentials
+    let siteMap = {};
+    try {
+      const sites = await omada.getSites();
+      siteMap = Object.fromEntries(sites.map(s => [s.id, s]));
+    } catch (err) {
+      console.error('[adoptDevices] getSites failed:', err.message);
+      return;
+    }
+
+    for (const device of pending) {
+      const site = siteMap[device.omada_site_id];
+      if (!site) continue;
+
+      let omadaDevices;
+      try {
+        omadaDevices = await omada.getSiteDevices(device.omada_site_id);
+      } catch { continue; }
+
+      // Normalize MACs by stripping separators before comparing
+      // (DB may store colons/dashes; Omada always returns dashes)
+      const stripMac = m => m.toUpperCase().replace(/[:\-]/g, '');
+      const normalMac = stripMac(device.mac);
+      const found = omadaDevices.find(d => d.mac && stripMac(d.mac) === normalMac);
+
+      if (!found) continue;                  // AP not visible yet
+      if (found.statusCategory !== 0) {
+        // Already adopted or connected — advance status
+        if (found.statusCategory === 1) {
+          await db.query(
+            `UPDATE devices SET status = 'online', adopted_at = NOW() WHERE id = ?`,
+            [device.id]
+          );
+        }
+        continue;
+      }
+
+      const username = device.device_username || site.deviceAccount?.username || 'admin';
+      const password = device.device_password || site.deviceAccount?.password || 'Admin@123';
+
+      try {
+        await omada.adoptDevice(device.omada_site_id, device.mac, username, password);
+        await db.query(
+          `UPDATE devices SET status = 'adopting', adopted_at = NOW() WHERE id = ?`,
+          [device.id]
+        );
+        console.log(`[adoptDevices] Adopting ${device.mac}`);
+      } catch (err) {
+        console.error(`[adoptDevices] Adopt ${device.mac} failed:`, err.message);
+      }
+    }
+  } catch (err) {
+    console.error('[adoptDevices]', err.message);
+  }
+}
+
+module.exports = adoptDevices;

src/jobs/billingReminders.job.js

@@ -0,0 +1,33 @@
+const db       = require('../config/db');
+const sms      = require('../services/sms');
+const messages = require('../utils/messages');
+
+async function billingReminders() {
+  try {
+    // Devices expiring in the next 3 days that haven't been reminded today
+    const expiring = await db.query(`
+      SELECT d.id, d.name AS device_name,
+             d.billing_expires_at, d.monthly_fee,
+             c.phone AS client_phone, c.business_name
+      FROM devices d
+      JOIN clients c ON c.id = d.client_id
+      WHERE d.billing_status IN ('trial', 'active')
+        AND d.billing_expires_at BETWEEN NOW() AND DATE_ADD(NOW(), INTERVAL 3 DAY)
+    `);
+
+    for (const device of expiring) {
+      const expiresAt = new Date(device.billing_expires_at);
+      const daysLeft  = Math.ceil((expiresAt - Date.now()) / 86400000);
+
+      await sms.sendSMS(device.client_phone,
+        messages.billingReminder(device.device_name, daysLeft, device.monthly_fee)
+      );
+    }
+
+    if (expiring.length) console.log(`[billingReminders] Sent ${expiring.length} reminder(s)`);
+  } catch (err) {
+    console.error('[billingReminders]', err.message);
+  }
+}
+
+module.exports = billingReminders;

src/jobs/expireTokens.job.js

@@ -0,0 +1,68 @@
+const db    = require('../config/db');
+const omada = require('../services/omada');
+
+async function expireTokens() {
+  try {
+    // ── 1. Expire active tokens that have passed their expiry time ─────────────
+    const expired = await db.query(`
+      SELECT t.id, t.code, t.locked_mac, d.omada_site_id
+      FROM access_tokens t
+      JOIN devices d ON d.id = t.device_id
+      WHERE t.status = 'active' AND t.expires_at < NOW()
+    `);
+
+    for (const token of expired) {
+      // Mark expired first — prevents reconnect even if deauth fails
+      await db.query(`UPDATE access_tokens SET status = 'expired' WHERE id = ?`, [token.id]);
+
+      // Deauth on Omada; if it fails the session stays is_active=1 as a retry flag
+      if (token.locked_mac && token.omada_site_id) {
+        try {
+          await omada.deauthorizeClient(token.omada_site_id, token.locked_mac);
+          await db.query(`
+            UPDATE sessions SET is_active = 0, ended_at = NOW()
+            WHERE access_token_id = ? AND is_active = 1
+          `, [token.id]);
+        } catch (err) {
+          console.error(`[expireTokens] Deauth ${token.code} failed (will retry):`, err.message);
+          // Session left is_active=1 intentionally — picked up by retry pass below
+        }
+      } else {
+        await db.query(`
+          UPDATE sessions SET is_active = 0, ended_at = NOW()
+          WHERE access_token_id = ? AND is_active = 1
+        `, [token.id]);
+      }
+    }
+
+    if (expired.length > 0) console.log(`[expireTokens] Expired ${expired.length} token(s)`);
+
+    // ── 2. Retry deauth for expired/revoked tokens whose sessions are still open ─
+    const pendingDeauth = await db.query(`
+      SELECT t.id, t.code, t.locked_mac, d.omada_site_id
+      FROM access_tokens t
+      JOIN sessions s ON s.access_token_id = t.id
+      JOIN devices d ON d.id = t.device_id
+      WHERE t.status IN ('expired', 'revoked')
+        AND s.is_active = 1
+        AND t.locked_mac IS NOT NULL
+    `);
+
+    for (const token of pendingDeauth) {
+      try {
+        await omada.deauthorizeClient(token.omada_site_id, token.locked_mac);
+        await db.query(`
+          UPDATE sessions SET is_active = 0, ended_at = NOW()
+          WHERE access_token_id = ? AND is_active = 1
+        `, [token.id]);
+        console.log(`[expireTokens] Retry deauth succeeded for ${token.code}`);
+      } catch (err) {
+        // Still down — will try again next tick
+      }
+    }
+  } catch (err) {
+    console.error('[expireTokens]', err.message);
+  }
+}
+
+module.exports = expireTokens;

src/jobs/index.js

@@ -0,0 +1,34 @@
+const cron = require('node-cron');
+
+const expireTokens    = require('./expireTokens.job');
+const adoptDevices    = require('./adoptDevices.job');
+const pollDevices     = require('./pollDevices.job');
+const pollSessions    = require('./pollSessions.job');
+const pollAlerts      = require('./pollAlerts.job');
+const suspendDevices  = require('./suspendDevices.job');
+const billingReminders = require('./billingReminders.job');
+
+function initJobs() {
+  // Every 30 seconds
+  cron.schedule('*/30 * * * * *', expireTokens);
+  cron.schedule('*/30 * * * * *', adoptDevices);
+
+  // Every 60 seconds
+  cron.schedule('*/60 * * * * *', pollSessions);
+
+  // Every 5 minutes
+  cron.schedule('*/5 * * * *', pollDevices);
+
+  // Every 15 minutes
+  cron.schedule('*/15 * * * *', pollAlerts);
+
+  // Daily at midnight
+  cron.schedule('0 0 * * *', suspendDevices);
+
+  // Daily at 9am
+  cron.schedule('0 9 * * *', billingReminders);
+
+  console.log('[Jobs] All cron jobs started');
+}
+
+module.exports = { initJobs };

src/jobs/pollAlerts.job.js

@@ -0,0 +1,60 @@
+const db    = require('../config/db');
+const omada = require('../services/omada');
+
+const LEVEL_MAP = {
+  Error:       'error',
+  Warning:     'warning',
+  Information: 'info',
+  Critical:    'critical',
+};
+
+async function pollAlerts() {
+  try {
+    const devices = await db.query(`
+      SELECT DISTINCT d.client_id, d.omada_site_id, d.id AS device_id, d.mac
+      FROM devices d
+      WHERE d.status IN ('online','offline')
+        AND d.omada_site_id IS NOT NULL
+    `);
+
+    for (const device of devices) {
+      try {
+        const alerts = await omada.getSiteAlerts(device.omada_site_id);
+
+        for (const alert of alerts) {
+          // Find matching device_id by alert MAC
+          let deviceId = device.device_id;
+          if (alert.device?.mac && alert.device.mac.toUpperCase() !== device.mac.toUpperCase()) {
+            const match = await db.query(
+              `SELECT id FROM devices WHERE mac = ? LIMIT 1`,
+              [alert.device.mac.toUpperCase()]
+            );
+            if (match.length) deviceId = match[0].id;
+          }
+
+          await db.query(`
+            INSERT IGNORE INTO omada_alerts
+              (client_id, device_id, omada_alert_id, alert_key, module, level, content, device_mac, alert_time)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, FROM_UNIXTIME(? / 1000))
+          `, [
+            device.client_id,
+            deviceId,
+            alert.id,
+            alert.key       || '',
+            alert.module    || null,
+            LEVEL_MAP[alert.level] || 'info',
+            alert.content   || '',
+            alert.device?.mac || null,
+            alert.time,
+          ]);
+        }
+      } catch (err) {
+        // ignore per-site errors
+      }
+    }
+  } catch (err) {
+    console.error('[pollAlerts]', err.message);
+  }
+}
+
+module.exports = pollAlerts;

src/jobs/pollDevices.job.js

@@ -0,0 +1,93 @@
+const db       = require('../config/db');
+const omada    = require('../services/omada');
+const sms      = require('../services/sms');
+const messages = require('../utils/messages');
+
+async function pollDevices() {
+  try {
+    const devices = await db.query(`
+      SELECT d.id, d.omada_site_id, d.status AS old_status,
+             d.name AS device_name, c.phone AS client_phone
+      FROM devices d
+      JOIN clients c ON c.id = d.client_id
+      WHERE d.status NOT IN ('pending', 'removed')
+        AND d.omada_site_id IS NOT NULL
+        AND d.billing_status != 'cancelled'
+    `);
+
+    for (const device of devices) {
+      try {
+        const omadaDevs = await omada.getSiteDevices(device.omada_site_id);
+        if (!omadaDevs.length) continue;
+
+        const stripMac = m => m.toUpperCase().replace(/[:\-]/g, '');
+        const ap = omadaDevs.find(d => d.mac && stripMac(d.mac) === stripMac(device.mac));
+        if (!ap) continue;
+
+        let newStatus;
+        if      (ap.statusCategory === 1) newStatus = 'online';
+        else if (ap.statusCategory === 2) newStatus = 'offline';
+        else if (ap.statusCategory === 0) newStatus = 'adopting';
+        else continue;
+
+        await db.query(`
+          UPDATE devices SET
+            status           = ?,
+            model            = COALESCE(?, model),
+            firmware_version = COALESCE(?, firmware_version),
+            ip               = ?,
+            public_ip        = ?,
+            cpu_util         = ?,
+            mem_util         = ?,
+            client_count     = ?,
+            guest_count      = ?,
+            uptime_seconds   = ?,
+            download_bytes   = ?,
+            upload_bytes     = ?,
+            needs_upgrade    = ?,
+            last_seen_at     = NOW()
+          WHERE id = ?
+        `, [
+          newStatus,
+          ap.model || null,
+          ap.firmwareVersion || null,
+          ap.ip || null,
+          ap.publicIp || null,
+          ap.cpuUtil ?? null,
+          ap.memUtil ?? null,
+          ap.clientNum || 0,
+          ap.guestNum  || 0,
+          ap.uptimeLong || 0,
+          ap.download  || 0,
+          ap.upload    || 0,
+          ap.needUpgrade ? 1 : 0,
+          device.id,
+        ]);
+
+        if (newStatus !== device.old_status) {
+          await db.query(
+            `INSERT INTO device_status_log (device_id, old_status, new_status) VALUES (?, ?, ?)`,
+            [device.id, device.old_status, newStatus]
+          );
+
+          if (newStatus === 'online' && device.old_status === 'adopting') {
+            sms.sendSMS(device.client_phone, messages.deviceOnline(device.device_name)).catch(() => {});
+          } else if (newStatus === 'offline' && device.old_status === 'online') {
+            sms.sendSMS(device.client_phone, messages.deviceOffline(device.device_name)).catch(() => {});
+          }
+
+          console.log(`[pollDevices] Device ${device.id}: ${device.old_status} → ${newStatus}`);
+        }
+      } catch (err) {
+        // Don't let one failure stop others
+        if (!['timeout', 'ECONNREFUSED', 'ENOTFOUND'].some(s => err.message?.includes(s))) {
+          console.error(`[pollDevices] Device ${device.id}:`, err.message);
+        }
+      }
+    }
+  } catch (err) {
+    console.error('[pollDevices]', err.message);
+  }
+}
+
+module.exports = pollDevices;

src/jobs/pollSessions.job.js

@@ -0,0 +1,106 @@
+const db         = require('../config/db');
+const omada      = require('../services/omada');
+const { alertAdmin } = require('../utils/adminAlert');
+
+async function pollSessions() {
+  try {
+    const devices = await db.query(`
+      SELECT id, client_id, omada_site_id
+      FROM devices
+      WHERE status = 'online' AND omada_site_id IS NOT NULL
+    `);
+
+    for (const device of devices) {
+      try {
+        const clients = await omada.getSiteClients(device.omada_site_id);
+
+        const activeMacs = new Set(clients.map(c => c.mac?.toUpperCase()).filter(Boolean));
+
+        // Mark sessions inactive for clients no longer visible on Omada
+        await db.query(`
+          UPDATE sessions SET is_active = 0, ended_at = NOW()
+          WHERE device_id = ? AND is_active = 1
+            AND client_mac NOT IN (${activeMacs.size ? [...activeMacs].map(() => '?').join(',') : "''"})
+        `, [device.id, ...activeMacs]);
+
+        if (!clients.length) continue;
+
+        const macs = [...activeMacs];
+
+        // ── Batch fetch tokens and sessions in 2 queries instead of 2×N ────────
+        const tokens = await db.query(
+          `SELECT id, locked_mac FROM access_tokens
+           WHERE device_id = ? AND status = 'active'
+             AND locked_mac IN (${macs.map(() => '?').join(',')})`,
+          [device.id, ...macs]
+        );
+        const tokenByMac = Object.fromEntries(tokens.map(t => [t.locked_mac, t]));
+
+        const sessions = await db.query(
+          `SELECT id, client_mac FROM sessions
+           WHERE device_id = ? AND is_active = 1
+             AND client_mac IN (${macs.map(() => '?').join(',')})`,
+          [device.id, ...macs]
+        );
+        const sessionByMac = Object.fromEntries(sessions.map(s => [s.client_mac, s]));
+
+        // ── Upsert sessions ───────────────────────────────────────────────────
+        for (const c of clients) {
+          if (!c.mac) continue;
+          const mac             = c.mac.toUpperCase();
+          const token           = tokenByMac[mac] || null;
+          const existingSession = sessionByMac[mac] || null;
+
+          if (existingSession) {
+            await db.query(`
+              UPDATE sessions SET
+                last_seen_at     = NOW(),
+                duration_seconds = TIMESTAMPDIFF(SECOND, started_at, NOW()),
+                bytes_down       = ?,
+                bytes_up         = ?,
+                rssi             = ?,
+                signal_level     = ?
+              WHERE id = ?
+            `, [
+              c.trafficDown || 0,
+              c.trafficUp   || 0,
+              c.rssi        || null,
+              c.signalLevel || null,
+              existingSession.id,
+            ]);
+          } else {
+            await db.query(`
+              INSERT IGNORE INTO sessions
+                (access_token_id, client_id, device_id, client_mac, client_ip, client_name, ssid,
+                 bytes_down, bytes_up, rssi, signal_level)
+              VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            `, [
+              token?.id || null,
+              device.client_id,
+              device.id,
+              mac,
+              c.ip   || null,
+              c.name || null,
+              c.ssid || null,
+              c.trafficDown || 0,
+              c.trafficUp   || 0,
+              c.rssi        || null,
+              c.signalLevel || null,
+            ]);
+          }
+        }
+      } catch (err) {
+        console.error(`[pollSessions] Device ${device.id} (site ${device.omada_site_id}):`, err.message);
+        alertAdmin(
+          `pollSessions:${device.id}`,
+          `Session sync failed for device ${device.id} (site ${device.omada_site_id}): ${err.message}`
+        );
+      }
+    }
+  } catch (err) {
+    console.error('[pollSessions] Fatal:', err.message);
+    alertAdmin('pollSessions:fatal', `pollSessions job crashed: ${err.message}`);
+  }
+}
+
+module.exports = pollSessions;

src/jobs/suspendDevices.job.js

@@ -0,0 +1,62 @@
+const db       = require('../config/db');
+const sms      = require('../services/sms');
+const omada    = require('../services/omada');
+const messages = require('../utils/messages');
+
+async function suspendDevices() {
+  try {
+    // Find expired trial/active devices
+    const expired = await db.query(`
+      SELECT d.id, d.name AS device_name, d.monthly_fee, d.omada_site_id, c.phone AS client_phone
+      FROM devices d
+      JOIN clients c ON c.id = d.client_id
+      WHERE d.billing_status IN ('trial', 'active')
+        AND d.billing_expires_at < NOW()
+        AND d.billing_status != 'suspended'
+    `);
+
+    for (const device of expired) {
+      await db.query(
+        `UPDATE devices SET billing_status = 'suspended' WHERE id = ?`,
+        [device.id]
+      );
+
+      // Revoke all active tokens and kick connected guests off Omada
+      const activeTokens = await db.query(
+        `SELECT id, locked_mac FROM access_tokens
+         WHERE device_id = ? AND status = 'active'`,
+        [device.id]
+      );
+
+      for (const token of activeTokens) {
+        if (token.locked_mac && device.omada_site_id) {
+          try {
+            await omada.deauthorizeClient(device.omada_site_id, token.locked_mac);
+          } catch (err) {
+            console.error(`[suspendDevices] Deauth ${token.locked_mac} failed:`, err.message);
+          }
+        }
+        await db.query(
+          `UPDATE access_tokens SET status = 'revoked' WHERE id = ?`,
+          [token.id]
+        );
+        await db.query(
+          `UPDATE sessions SET is_active = 0, ended_at = NOW()
+           WHERE access_token_id = ? AND is_active = 1`,
+          [token.id]
+        );
+      }
+
+      const fee = parseInt(device.monthly_fee || 20000).toLocaleString();
+      sms.sendSMS(device.client_phone, messages.deviceSuspended(device.device_name, fee)).catch(() => {});
+
+      console.log(`[suspendDevices] Suspended device ${device.id} (${device.device_name}), revoked ${activeTokens.length} token(s)`);
+    }
+
+    if (expired.length) console.log(`[suspendDevices] Suspended ${expired.length} device(s)`);
+  } catch (err) {
+    console.error('[suspendDevices]', err.message);
+  }
+}
+
+module.exports = suspendDevices;

src/middleware/auth.js

@@ -0,0 +1,49 @@
+const jwt = require('jsonwebtoken');
+const db  = require('../config/db');
+
+async function requireAuth(req, res, next) {
+  const header = req.headers.authorization;
+  if (!header?.startsWith('Bearer ')) {
+    return res.status(401).json({ error: 'Authentication required' });
+  }
+  try {
+    const payload = jwt.verify(header.slice(7), process.env.JWT_SECRET);
+
+    // Confirm account is still active — catches deactivated tenants mid-session
+    const client = await db.queryOne(
+      'SELECT id, is_active FROM clients WHERE id = ? LIMIT 1',
+      [payload.id]
+    );
+    if (!client || !client.is_active) {
+      return res.status(401).json({ error: 'Account is inactive' });
+    }
+
+    req.client = payload;
+    next();
+  } catch {
+    return res.status(401).json({ error: 'Invalid or expired token' });
+  }
+}
+
+function requireAdmin(req, res, next) {
+  const header = req.headers.authorization;
+  if (!header?.startsWith('Bearer ')) {
+    return res.status(401).json({ error: 'Admin authentication required' });
+  }
+  const token = header.slice(7);
+  if (token === process.env.ADMIN_TOKEN) {
+    req.isAdmin = true;
+    return next();
+  }
+  return res.status(401).json({ error: 'Invalid admin token' });
+}
+
+function signToken(client) {
+  return jwt.sign(
+    { id: client.id, email: client.email, business_name: client.business_name },
+    process.env.JWT_SECRET,
+    { expiresIn: '30d' }
+  );
+}
+
+module.exports = { requireAuth, requireAdmin, signToken };

src/middleware/rateLimiter.js

@@ -0,0 +1,49 @@
+const rateLimit = require('express-rate-limit');
+
+// Tenant login — 5 failed attempts per 15 min per IP
+const loginLimiter = rateLimit({
+  windowMs:         15 * 60 * 1000,
+  max:              5,
+  skipSuccessfulRequests: true,
+  standardHeaders: true,
+  legacyHeaders:   false,
+  message: { error: 'Too many login attempts. Try again in 15 minutes.' },
+});
+
+// Tenant registration — 3 accounts per hour per IP
+const registerLimiter = rateLimit({
+  windowMs: 60 * 60 * 1000,
+  max:      3,
+  standardHeaders: true,
+  legacyHeaders:   false,
+  message: { error: 'Too many registration attempts. Try again in an hour.' },
+});
+
+// Portal purchase — 5 per 10 min per IP (prevents M-Pesa spam to any phone)
+const purchaseLimiter = rateLimit({
+  windowMs: 10 * 60 * 1000,
+  max:      5,
+  standardHeaders: true,
+  legacyHeaders:   false,
+  message: { error: 'Too many purchase attempts. Please wait before trying again.' },
+});
+
+// Forgot password — 3 OTP requests per 15 min per IP (prevents SMS bombing)
+const forgotPasswordLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max:      3,
+  standardHeaders: true,
+  legacyHeaders:   false,
+  message: { error: 'Too many reset requests. Try again in 15 minutes.' },
+});
+
+// Portal auth / code entry — 10 per 15 min per IP (prevents code brute force)
+const portalAuthLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max:      10,
+  standardHeaders: true,
+  legacyHeaders:   false,
+  message: { error: 'Too many authorization attempts. Try again in 15 minutes.' },
+});
+
+module.exports = { loginLimiter, registerLimiter, forgotPasswordLimiter, purchaseLimiter, portalAuthLimiter };

src/routes/admin.routes.js

@@ -0,0 +1,130 @@
+const router = require('express').Router();
+const db     = require('../config/db');
+const omada  = require('../services/omada');
+const { requireAdmin } = require('../middleware/auth');
+
+router.use(requireAdmin);
+
+// GET /api/admin/overview
+router.get('/overview', async (req, res) => {
+  try {
+    const [[stats]]        = await Promise.all([
+      db.query(`
+        SELECT
+          (SELECT COUNT(*) FROM clients WHERE is_active = 1) AS tenants,
+          (SELECT COUNT(*) FROM devices WHERE status = 'online') AS devices_online,
+          (SELECT COUNT(*) FROM devices WHERE status = 'offline') AS devices_offline,
+          (SELECT COUNT(*) FROM devices WHERE billing_status = 'suspended') AS devices_suspended,
+          (SELECT COUNT(*) FROM sessions WHERE is_active = 1) AS guests_online,
+          (SELECT COUNT(*) FROM payments WHERE status = 'completed' AND DATE(completed_at) = CURDATE()) AS sales_today,
+          (SELECT COALESCE(SUM(gross_amount),0) FROM payments WHERE status = 'completed' AND DATE(completed_at) = CURDATE()) AS gross_today,
+          (SELECT COALESCE(SUM(commission_amount),0) FROM payments WHERE status = 'completed' AND DATE(completed_at) = CURDATE()) AS commission_today,
+          (SELECT COALESCE(SUM(snippe_fee),0) FROM payments WHERE status = 'completed' AND DATE(completed_at) = CURDATE()) AS snippe_fees_today,
+          (SELECT COUNT(*) FROM payouts WHERE status = 'pending') AS pending_payouts,
+          (SELECT COALESCE(SUM(amount),0) FROM payouts WHERE status = 'pending') AS pending_payout_total
+      `)
+    ]);
+
+    res.json(stats[0]);
+  } catch (err) {
+    console.error('[admin/overview]', err.message);
+    res.status(500).json({ error: 'Failed to load overview' });
+  }
+});
+
+// GET /api/admin/tenants
+router.get('/tenants', async (req, res) => {
+  try {
+    const tenants = await db.query(`
+      SELECT c.id, c.business_name, c.contact_name, c.email, c.phone,
+             c.balance, c.total_earned, c.total_withdrawn, c.is_active, c.created_at,
+             COUNT(d.id) AS device_count,
+             SUM(CASE WHEN d.status = 'online' THEN 1 ELSE 0 END) AS devices_online
+      FROM clients c
+      LEFT JOIN devices d ON d.client_id = c.id AND d.billing_status != 'cancelled'
+      GROUP BY c.id
+      ORDER BY c.created_at DESC
+    `);
+    res.json(tenants);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to fetch tenants' });
+  }
+});
+
+// GET /api/admin/devices
+router.get('/devices', async (req, res) => {
+  try {
+    const devices = await db.query(`
+      SELECT d.id, d.name, d.location, d.mac, d.model, d.status, d.billing_status,
+             d.billing_expires_at, d.monthly_fee, d.cpu_util, d.mem_util,
+             d.guest_count, d.last_seen_at,
+             c.business_name, c.phone AS client_phone
+      FROM devices d
+      JOIN clients c ON c.id = d.client_id
+      WHERE d.billing_status != 'cancelled'
+      ORDER BY d.status ASC, d.registered_at DESC
+    `);
+    res.json(devices);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to fetch devices' });
+  }
+});
+
+// GET /api/admin/payouts/pending
+router.get('/payouts/pending', async (req, res) => {
+  try {
+    const payouts = await db.query(`
+      SELECT po.id, po.amount, po.payout_fee, po.net_amount,
+             po.destination_phone, po.destination_provider, po.status, po.created_at,
+             c.business_name, c.contact_name
+      FROM payouts po
+      JOIN clients c ON c.id = po.client_id
+      WHERE po.status IN ('pending', 'processing')
+      ORDER BY po.created_at ASC
+    `);
+    res.json(payouts);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to fetch pending payouts' });
+  }
+});
+
+// GET /api/admin/revenue/daily?days=30
+router.get('/revenue/daily', async (req, res) => {
+  const days = parseInt(req.query.days) || 30;
+  try {
+    const rows = await db.query(`
+      SELECT DATE(completed_at) AS day,
+             COUNT(*) AS sales,
+             SUM(gross_amount) AS gross,
+             SUM(commission_amount) AS commission,
+             SUM(client_credit) AS tenant_credit
+      FROM payments
+      WHERE status = 'completed'
+        AND completed_at >= DATE_SUB(CURDATE(), INTERVAL ? DAY)
+      GROUP BY DATE(completed_at)
+      ORDER BY day DESC
+    `, [days]);
+    res.json(rows);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to fetch revenue' });
+  }
+});
+
+// POST /api/admin/devices/:id/reboot
+router.post('/devices/:id/reboot', async (req, res) => {
+  try {
+    const device = await db.query(
+      'SELECT omada_site_id, mac FROM devices WHERE id = ? LIMIT 1',
+      [req.params.id]
+    ).then(r => r[0]);
+
+    if (!device?.omada_site_id) return res.status(404).json({ error: 'Device not found or not adopted' });
+
+    await omada.rebootDevice(device.omada_site_id, device.mac);
+    res.json({ message: 'Reboot command sent' });
+  } catch (err) {
+    res.status(500).json({ error: 'Reboot failed: ' + err.message });
+  }
+});
+
+module.exports = router;

src/routes/alerts.routes.js

@@ -0,0 +1,39 @@
+const router = require('express').Router();
+const db     = require('../config/db');
+const { requireAuth } = require('../middleware/auth');
+
+router.use(requireAuth);
+
+// GET /api/alerts/unresolved
+router.get('/unresolved', async (req, res) => {
+  try {
+    const alerts = await db.query(
+      `SELECT a.id, a.alert_key, a.level, a.content, a.device_mac,
+              a.alert_time, a.fetched_at,
+              d.name AS device_name
+       FROM omada_alerts a
+       LEFT JOIN devices d ON d.id = a.device_id
+       WHERE a.client_id = ? AND a.resolved = 0
+       ORDER BY a.alert_time DESC LIMIT 50`,
+      [req.client.id]
+    );
+    res.json(alerts);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to fetch alerts' });
+  }
+});
+
+// PATCH /api/alerts/:id/resolve
+router.patch('/:id/resolve', async (req, res) => {
+  try {
+    await db.query(
+      'UPDATE omada_alerts SET resolved = 1 WHERE id = ? AND client_id = ?',
+      [req.params.id, req.client.id]
+    );
+    res.json({ message: 'Alert resolved' });
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to resolve alert' });
+  }
+});
+
+module.exports = router;

src/routes/auth.routes.js

@@ -0,0 +1,161 @@
+const router   = require('express').Router();
+const bcrypt   = require('bcryptjs');
+const db       = require('../config/db');
+const sms      = require('../services/sms');
+const messages = require('../utils/messages');
+const { requireAuth, signToken } = require('../middleware/auth');
+const { loginLimiter, registerLimiter, forgotPasswordLimiter } = require('../middleware/rateLimiter');
+
+// POST /api/auth/register
+router.post('/register', registerLimiter, async (req, res) => {
+  const { business_name, contact_name, email, phone, password } = req.body;
+
+  if (!business_name || !contact_name || !email || !phone || !password) {
+    return res.status(400).json({ error: 'All fields are required' });
+  }
+  if (password.length < 8) {
+    return res.status(400).json({ error: 'Password must be at least 8 characters' });
+  }
+
+  try {
+    const existing = await db.query(
+      'SELECT id FROM clients WHERE email = ? OR phone = ? LIMIT 1',
+      [email.toLowerCase(), phone]
+    );
+    if (existing.length) {
+      return res.status(409).json({ error: 'Email or phone already registered' });
+    }
+
+    const hash = await bcrypt.hash(password, 10);
+    const result = await db.query(
+      `INSERT INTO clients (business_name, contact_name, email, phone, password_hash)
+       VALUES (?, ?, ?, ?, ?)`,
+      [business_name, contact_name, email.toLowerCase(), phone, hash]
+    );
+
+    const client = await db.query('SELECT * FROM clients WHERE id = ?', [result.insertId])
+      .then(r => r[0]);
+
+    // Welcome SMS (fire-and-forget)
+    sms.sendSMS(phone, messages.welcome()).catch(() => {});
+
+    const token = signToken(client);
+    const { password_hash, ...safe } = client;
+    res.status(201).json({ token, client: safe });
+  } catch (err) {
+    console.error('[auth/register]', err.message);
+    res.status(500).json({ error: 'Registration failed' });
+  }
+});
+
+// POST /api/auth/login
+router.post('/login', loginLimiter, async (req, res) => {
+  const { email, password } = req.body;
+  if (!email || !password) {
+    return res.status(400).json({ error: 'Email and password required' });
+  }
+
+  try {
+    const client = await db.query(
+      'SELECT * FROM clients WHERE email = ? AND is_active = 1 LIMIT 1',
+      [email.toLowerCase()]
+    ).then(r => r[0]);
+
+    if (!client || !(await bcrypt.compare(password, client.password_hash))) {
+      return res.status(401).json({ error: 'Invalid credentials' });
+    }
+
+    const token = signToken(client);
+    const { password_hash, ...safe } = client;
+    res.json({ token, client: safe });
+  } catch (err) {
+    console.error('[auth/login]', err.message);
+    res.status(500).json({ error: 'Login failed' });
+  }
+});
+
+// POST /api/auth/forgot-password
+router.post('/forgot-password', forgotPasswordLimiter, async (req, res) => {
+  const { phone } = req.body;
+  if (!phone) return res.status(400).json({ error: 'phone required' });
+
+  try {
+    const client = await db.queryOne(
+      'SELECT id FROM clients WHERE phone = ? AND is_active = 1 LIMIT 1',
+      [phone]
+    );
+
+    // Always respond 200 — don't reveal whether phone is registered
+    if (!client) return res.json({ message: 'If that number is registered, an OTP has been sent.' });
+
+    const otp       = String(Math.floor(100000 + Math.random() * 900000));
+    const expiresAt = new Date(Date.now() + 10 * 60 * 1000);
+
+    // Invalidate any previous unused OTPs for this phone
+    await db.query(`UPDATE password_resets SET used = 1 WHERE phone = ? AND used = 0`, [phone]);
+
+    await db.query(
+      `INSERT INTO password_resets (phone, otp, expires_at) VALUES (?, ?, ?)`,
+      [phone, otp, expiresAt]
+    );
+
+    sms.sendSMS(phone, messages.passwordResetOtp(otp)).catch(() => {});
+
+    res.json({ message: 'If that number is registered, an OTP has been sent.' });
+  } catch (err) {
+    console.error('[auth/forgot-password]', err.message);
+    res.status(500).json({ error: 'Request failed' });
+  }
+});
+
+// POST /api/auth/reset-password
+router.post('/reset-password', async (req, res) => {
+  const { phone, otp, new_password } = req.body;
+
+  if (!phone || !otp || !new_password) {
+    return res.status(400).json({ error: 'phone, otp, and new_password required' });
+  }
+  if (new_password.length < 8) {
+    return res.status(400).json({ error: 'Password must be at least 8 characters' });
+  }
+
+  try {
+    const reset = await db.queryOne(
+      `SELECT id FROM password_resets
+       WHERE phone = ? AND otp = ? AND used = 0 AND expires_at > NOW()
+       ORDER BY created_at DESC LIMIT 1`,
+      [phone, otp]
+    );
+
+    if (!reset) {
+      return res.status(400).json({ error: 'Invalid or expired OTP' });
+    }
+
+    const hash = await bcrypt.hash(new_password, 10);
+
+    await db.query(`UPDATE clients SET password_hash = ? WHERE phone = ?`, [hash, phone]);
+    await db.query(`UPDATE password_resets SET used = 1 WHERE id = ?`, [reset.id]);
+
+    res.json({ message: 'Password reset successfully. Please log in.' });
+  } catch (err) {
+    console.error('[auth/reset-password]', err.message);
+    res.status(500).json({ error: 'Reset failed' });
+  }
+});
+
+// GET /api/auth/me
+router.get('/me', requireAuth, async (req, res) => {
+  try {
+    const client = await db.query(
+      'SELECT id, business_name, contact_name, email, phone, balance, total_earned, total_withdrawn, created_at FROM clients WHERE id = ?',
+      [req.client.id]
+    ).then(r => r[0]);
+
+    if (!client) return res.status(404).json({ error: 'Account not found' });
+    res.json(client);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to fetch profile' });
+  }
+});
+
+module.exports = router;

src/routes/dashboard.routes.js

@@ -0,0 +1,77 @@
+const router = require('express').Router();
+const db     = require('../config/db');
+const { requireAuth } = require('../middleware/auth');
+
+router.use(requireAuth);
+
+// GET /api/dashboard/summary
+router.get('/summary', async (req, res) => {
+  const clientId = req.client.id;
+  try {
+    // Balance
+    const client = await db.query(
+      'SELECT balance, total_earned, total_withdrawn FROM clients WHERE id = ?',
+      [clientId]
+    ).then(r => r[0]);
+
+    // Devices with today's stats
+    const devices = await db.query(
+      `SELECT d.id, d.name, d.location, d.status, d.billing_status, d.billing_expires_at,
+              d.model, d.cpu_util, d.mem_util, d.guest_count, d.last_seen_at,
+              (SELECT COUNT(*) FROM payments
+               WHERE device_id = d.id AND status = 'completed' AND DATE(completed_at) = CURDATE()
+              ) AS sales_today,
+              (SELECT COALESCE(SUM(client_credit),0) FROM payments
+               WHERE device_id = d.id AND status = 'completed' AND DATE(completed_at) = CURDATE()
+              ) AS earned_today,
+              (SELECT COUNT(*) FROM sessions
+               WHERE device_id = d.id AND is_active = 1
+              ) AS guests_online
+       FROM devices d
+       WHERE d.client_id = ? AND d.billing_status != 'cancelled'
+       ORDER BY d.registered_at ASC`,
+      [clientId]
+    );
+
+    // Unresolved alerts count
+    const alertCount = await db.query(
+      'SELECT COUNT(*) AS cnt FROM omada_alerts WHERE client_id = ? AND resolved = 0',
+      [clientId]
+    ).then(r => r[0].cnt);
+
+    res.json({
+      balance:         parseFloat(client.balance),
+      total_earned:    parseFloat(client.total_earned),
+      total_withdrawn: parseFloat(client.total_withdrawn),
+      devices,
+      alert_count:     alertCount,
+    });
+  } catch (err) {
+    console.error('[dashboard/summary]', err.message);
+    res.status(500).json({ error: 'Failed to load dashboard' });
+  }
+});
+
+// GET /api/dashboard/revenue/weekly
+router.get('/revenue/weekly', async (req, res) => {
+  const clientId = req.client.id;
+  try {
+    const rows = await db.query(
+      `SELECT DATE(completed_at) AS day,
+              COUNT(*) AS sales,
+              SUM(gross_amount) AS gross,
+              SUM(client_credit) AS net
+       FROM payments
+       WHERE client_id = ? AND status = 'completed'
+         AND completed_at >= DATE_SUB(CURDATE(), INTERVAL 7 DAY)
+       GROUP BY DATE(completed_at)
+       ORDER BY day ASC`,
+      [clientId]
+    );
+    res.json(rows);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to load revenue data' });
+  }
+});
+
+module.exports = router;

src/routes/devices.routes.js

@@ -0,0 +1,326 @@
+const router   = require('express').Router();
+const db       = require('../config/db');
+const omada    = require('../services/omada');
+const snippe   = require('../services/snippe');
+const sms      = require('../services/sms');
+const messages = require('../utils/messages');
+const { requireAuth } = require('../middleware/auth');
+const { v4: uuidv4 } = require('uuid');
+
+router.use(requireAuth);
+
+// GET /api/devices
+router.get('/', async (req, res) => {
+  try {
+    const devices = await db.query(
+      `SELECT id, name, location, mac, model, ip, status, billing_status,
+              billing_expires_at, monthly_fee, cpu_util, mem_util, guest_count,
+              client_count, last_seen_at, registered_at, omada_site_id
+       FROM devices WHERE client_id = ? AND billing_status != 'cancelled'
+       ORDER BY registered_at ASC`,
+      [req.client.id]
+    );
+    res.json(devices);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to fetch devices' });
+  }
+});
+
+// POST /api/devices
+router.post('/', async (req, res) => {
+  const { name, location, mac, device_username, device_password } = req.body;
+
+  if (!name || !mac) {
+    return res.status(400).json({ error: 'name and mac are required' });
+  }
+
+  // Normalize MAC: uppercase with dashes
+  const normalMac = mac.trim().toUpperCase()
+    .replace(/[:\-]/g, '-')
+    .replace(/(.{2})(?=.)/g, '$1-')
+    .slice(0, 17);
+
+  if (!/^([0-9A-F]{2}-){5}[0-9A-F]{2}$/.test(normalMac)) {
+    return res.status(400).json({ error: 'Invalid MAC address format (use AA-BB-CC-DD-EE-FF)' });
+  }
+
+  // Check MAC not already registered
+  const existing = await db.query('SELECT id FROM devices WHERE mac = ? LIMIT 1', [normalMac]);
+  if (existing.length) {
+    return res.status(409).json({ error: 'This MAC address is already registered' });
+  }
+
+  try {
+    const client = await db.query('SELECT * FROM clients WHERE id = ? LIMIT 1', [req.client.id])
+      .then(r => r[0]);
+
+    // 1. Create Omada site
+    const siteName = `${client.business_name} - ${name}`;
+    let siteId, portalId, deviceUsername, devicePassword;
+
+    try {
+      siteId = await omada.createSite(siteName);
+
+      // Tenant-supplied credentials take priority; fall back to Omada site defaults
+      const siteInfo = await omada.getSiteById(siteId);
+      deviceUsername = device_username || siteInfo?.deviceAccount?.username || 'admin';
+      devicePassword = device_password || siteInfo?.deviceAccount?.password || 'Admin@123';
+
+      // 2. Create captive portal on this site
+      portalId = await omada.createPortal(siteId, `${name} Portal`, []);
+    } catch (omadaErr) {
+      console.error('[devices/POST] Omada setup failed:', omadaErr.message);
+      // Continue — device can still be registered, Omada setup retried later
+      siteId   = null;
+      portalId = null;
+    }
+
+    // 3. Calculate trial expiry
+    const trialDays = parseInt(process.env.DEVICE_TRIAL_DAYS) || 14;
+    const expiresAt = new Date(Date.now() + trialDays * 24 * 60 * 60 * 1000);
+
+    // 4. Insert device
+    const result = await db.query(
+      `INSERT INTO devices
+         (client_id, name, location, mac, omada_site_id, omada_portal_id,
+          device_username, device_password, billing_status, billing_expires_at, monthly_fee)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'trial', ?, ?)`,
+      [
+        req.client.id,
+        name,
+        location || null,
+        normalMac,
+        siteId,
+        portalId,
+        deviceUsername || null,
+        devicePassword || null,
+        expiresAt,
+        parseFloat(process.env.DEVICE_MONTHLY_FEE) || 20000,
+      ]
+    );
+
+    const device = await db.query('SELECT * FROM devices WHERE id = ?', [result.insertId])
+      .then(r => r[0]);
+
+    res.status(201).json({
+      device,
+      message: siteId
+        ? 'Device registered. Plug in your AP and wait for it to come online.'
+        : 'Device registered (Omada setup pending). Contact support if the AP does not come online.',
+    });
+  } catch (err) {
+    console.error('[devices/POST]', err.message);
+    res.status(500).json({ error: 'Failed to register device' });
+  }
+});
+
+// GET /api/devices/:id
+router.get('/:id', async (req, res) => {
+  try {
+    const device = await db.query(
+      `SELECT d.*,
+              (SELECT COUNT(*) FROM payments WHERE device_id = d.id AND status = 'completed' AND DATE(completed_at) = CURDATE()) AS sales_today,
+              (SELECT COALESCE(SUM(client_credit),0) FROM payments WHERE device_id = d.id AND status = 'completed' AND DATE(completed_at) = CURDATE()) AS earned_today
+       FROM devices d
+       WHERE d.id = ? AND d.client_id = ?`,
+      [req.params.id, req.client.id]
+    ).then(r => r[0]);
+
+    if (!device) return res.status(404).json({ error: 'Device not found' });
+
+    // Active guests from DB
+    const activeSessions = await db.query(
+      `SELECT s.client_mac, s.started_at, s.bytes_down, s.bytes_up,
+              t.expires_at, t.code, wp.name AS plan_name
+       FROM sessions s
+       LEFT JOIN access_tokens t ON t.id = s.access_token_id
+       LEFT JOIN wifi_plans wp ON wp.id = t.plan_id
+       WHERE s.device_id = ? AND s.is_active = 1`,
+      [device.id]
+    );
+
+    res.json({ ...device, active_sessions: activeSessions });
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to fetch device' });
+  }
+});
+
+// GET /api/devices/:id/portal  — get portal customization settings
+router.get('/:id/portal', async (req, res) => {
+  try {
+    const device = await db.queryOne(
+      'SELECT id FROM devices WHERE id = ? AND client_id = ? LIMIT 1',
+      [req.params.id, req.client.id]
+    );
+    if (!device) return res.status(404).json({ error: 'Device not found' });
+
+    const settings = await db.queryOne(
+      'SELECT * FROM device_portal_settings WHERE device_id = ?',
+      [req.params.id]
+    );
+
+    // Return settings or defaults if not yet customized
+    res.json(settings || {
+      device_id:     parseInt(req.params.id),
+      display_name:  null,
+      welcome_text:  null,
+      logo_url:      null,
+      support_phone: null,
+      primary_color: '#4361ee',
+      bg_color:      '#1a1a2e',
+    });
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to fetch portal settings' });
+  }
+});
+
+// PATCH /api/devices/:id/portal  — update portal customization settings
+router.patch('/:id/portal', async (req, res) => {
+  const { display_name, welcome_text, logo_url, support_phone, primary_color, bg_color } = req.body;
+
+  const hexColor = v => !v || /^#[0-9A-Fa-f]{6}$/.test(v);
+  if (!hexColor(primary_color) || !hexColor(bg_color)) {
+    return res.status(400).json({ error: 'Colors must be a valid hex value (e.g. #4361ee)' });
+  }
+
+  try {
+    const device = await db.queryOne(
+      'SELECT id FROM devices WHERE id = ? AND client_id = ? LIMIT 1',
+      [req.params.id, req.client.id]
+    );
+    if (!device) return res.status(404).json({ error: 'Device not found' });
+
+    await db.query(
+      `INSERT INTO device_portal_settings
+         (device_id, display_name, welcome_text, logo_url, support_phone, primary_color, bg_color)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON DUPLICATE KEY UPDATE
+         display_name  = COALESCE(VALUES(display_name),  display_name),
+         welcome_text  = COALESCE(VALUES(welcome_text),  welcome_text),
+         logo_url      = COALESCE(VALUES(logo_url),      logo_url),
+         support_phone = COALESCE(VALUES(support_phone), support_phone),
+         primary_color = COALESCE(VALUES(primary_color), primary_color),
+         bg_color      = COALESCE(VALUES(bg_color),      bg_color)`,
+      [
+        req.params.id,
+        display_name  ?? null,
+        welcome_text  ?? null,
+        logo_url      ?? null,
+        support_phone ?? null,
+        primary_color ?? null,
+        bg_color      ?? null,
+      ]
+    );
+
+    const updated = await db.queryOne(
+      'SELECT * FROM device_portal_settings WHERE device_id = ?',
+      [req.params.id]
+    );
+    res.json(updated);
+  } catch (err) {
+    console.error('[devices/portal PATCH]', err.message);
+    res.status(500).json({ error: 'Failed to update portal settings' });
+  }
+});
+
+// DELETE /api/devices/:id  (pause device — reversible via renewal)
+router.delete('/:id', async (req, res) => {
+  try {
+    const device = await db.query(
+      `SELECT d.*, c.phone AS client_phone
+       FROM devices d JOIN clients c ON c.id = d.client_id
+       WHERE d.id = ? AND d.client_id = ? LIMIT 1`,
+      [req.params.id, req.client.id]
+    ).then(r => r[0]);
+
+    if (!device) return res.status(404).json({ error: 'Device not found' });
+    if (device.billing_status === 'suspended') {
+      return res.status(400).json({ error: 'Device is already suspended' });
+    }
+
+    // Suspend billing
+    await db.query(
+      `UPDATE devices SET billing_status = 'suspended' WHERE id = ?`,
+      [device.id]
+    );
+
+    // Revoke active tokens and kick guests off Omada
+    const activeTokens = await db.query(
+      `SELECT id, locked_mac FROM access_tokens WHERE device_id = ? AND status = 'active'`,
+      [device.id]
+    );
+
+    for (const token of activeTokens) {
+      if (token.locked_mac && device.omada_site_id) {
+        try {
+          await omada.deauthorizeClient(device.omada_site_id, token.locked_mac);
+        } catch (err) {
+          console.error(`[devices/DELETE] Deauth ${token.locked_mac} failed:`, err.message);
+        }
+      }
+      await db.query(`UPDATE access_tokens SET status = 'revoked' WHERE id = ?`, [token.id]);
+      await db.query(
+        `UPDATE sessions SET is_active = 0, ended_at = NOW() WHERE access_token_id = ? AND is_active = 1`,
+        [token.id]
+      );
+    }
+
+    // Notify tenant to renew
+    const fee = parseInt(device.monthly_fee || 20000).toLocaleString();
+    sms.sendSMS(device.client_phone, messages.devicePaused(device.name, fee)).catch(() => {});
+
+    res.json({ message: 'Device paused. Renew your subscription to reactivate.' });
+  } catch (err) {
+    console.error('[devices/DELETE]', err.message);
+    res.status(500).json({ error: 'Failed to pause device' });
+  }
+});
+
+// POST /api/devices/:id/renew  — initiate monthly billing payment
+router.post('/:id/renew', async (req, res) => {
+  try {
+    const device = await db.query(
+      `SELECT d.*, c.phone AS client_phone, c.contact_name
+       FROM devices d JOIN clients c ON c.id = d.client_id
+       WHERE d.id = ? AND d.client_id = ? LIMIT 1`,
+      [req.params.id, req.client.id]
+    ).then(r => r[0]);
+
+    if (!device) return res.status(404).json({ error: 'Device not found' });
+    if (device.billing_status === 'cancelled') {
+      return res.status(400).json({ error: 'Device is cancelled' });
+    }
+
+    const reference = uuidv4().replace(/-/g, '').slice(0, 20);
+    const now       = new Date();
+    const start     = device.billing_expires_at ? new Date(device.billing_expires_at) : now;
+    const end       = new Date(start.getTime() + 30 * 24 * 60 * 60 * 1000);
+
+    await db.query(
+      `INSERT INTO device_payments (client_id, device_id, amount, reference, period_start, period_end, status)
+       VALUES (?, ?, ?, ?, ?, ?, 'pending')`,
+      [req.client.id, device.id, device.monthly_fee, reference, start, end]
+    );
+
+    // Initiate Snippe payment to tenant's phone
+    const webhookBase = `${process.env.PORTAL_SCHEME || 'http'}://${process.env.PORTAL_HOST}`;
+    try {
+      await snippe.createPayment({
+        reference,
+        amount:     device.monthly_fee,
+        phone:      device.client_phone,
+        webhookUrl: `${webhookBase}/api/webhooks/snippe`,
+        metadata:   { type: 'device_renewal', device_id: String(device.id) },
+      });
+    } catch (payErr) {
+      console.error('[devices/renew] Snippe error:', payErr.message);
+    }
+
+    res.json({ reference, amount: device.monthly_fee, message: 'Check your phone for M-Pesa prompt' });
+  } catch (err) {
+    console.error('[devices/renew]', err.message);
+    res.status(500).json({ error: 'Failed to initiate renewal' });
+  }
+});
+
+module.exports = router;

src/routes/payouts.routes.js

@@ -0,0 +1,114 @@
+const router = require('express').Router();
+const db     = require('../config/db');
+const snippe = require('../services/snippe');
+const { requireAuth } = require('../middleware/auth');
+
+router.use(requireAuth);
+
+// GET /api/payouts
+router.get('/', async (req, res) => {
+  try {
+    const payouts = await db.query(
+      `SELECT id, amount, payout_fee, net_amount, destination_phone,
+              destination_provider, status, failure_reason, created_at, completed_at
+       FROM payouts WHERE client_id = ?
+       ORDER BY created_at DESC LIMIT 50`,
+      [req.client.id]
+    );
+    res.json(payouts);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to fetch payouts' });
+  }
+});
+
+// POST /api/payouts
+router.post('/', async (req, res) => {
+  const { amount, phone, provider = 'mpesa' } = req.body;
+
+  if (!amount || !phone) {
+    return res.status(400).json({ error: 'amount and phone required' });
+  }
+
+  const amountNum = parseFloat(amount);
+  if (amountNum < 5000) {
+    return res.status(400).json({ error: 'Minimum payout is 5,000 TZS' });
+  }
+
+  try {
+    // Check balance
+    const client = await db.query(
+      'SELECT balance, contact_name FROM clients WHERE id = ? FOR UPDATE',
+      [req.client.id]
+    ).then(r => r[0]);
+
+    if (parseFloat(client.balance) < amountNum) {
+      return res.status(400).json({
+        error:   'Insufficient balance',
+        balance: parseFloat(client.balance),
+      });
+    }
+
+    // Calculate fee
+    let feeAmount = 1500;
+    try {
+      const feeData = await snippe.getPayoutFee(amountNum);
+      feeAmount = feeData?.fee_amount || 1500;
+    } catch { /* use default */ }
+
+    const netAmount = amountNum - feeAmount;
+
+    // Insert payout (trg_payout_requested fires — deducts balance)
+    const result = await db.query(
+      `INSERT INTO payouts
+         (client_id, amount, payout_fee, net_amount, destination_phone, destination_provider, status)
+       VALUES (?, ?, ?, ?, ?, ?, 'pending')`,
+      [req.client.id, amountNum, feeAmount, netAmount, phone, provider]
+    );
+
+    const payoutId  = result.insertId;
+    const webhookBase = `${process.env.PORTAL_SCHEME || 'http'}://${process.env.PORTAL_HOST}`;
+
+    // Call Snippe disbursement
+    try {
+      const disbResult = await snippe.createPayout({
+        payoutId,
+        amount:        amountNum,
+        phone,
+        recipientName: client.contact_name,
+        narration:     'WiFi platform payout',
+        webhookUrl:    `${webhookBase}/api/webhooks/snippe`,
+      });
+
+      // Save disbursement reference
+      const disbRef = disbResult?.data?.reference || disbResult?.reference || null;
+      if (disbRef) {
+        await db.query(
+          `UPDATE payouts SET status = 'processing', snippe_disbursement_id = ? WHERE id = ?`,
+          [disbRef, payoutId]
+        );
+      }
+    } catch (disbErr) {
+      console.error('[payouts/POST] Snippe disbursement error:', disbErr.message);
+      // Mark failed — trigger restores balance
+      await db.query(
+        `UPDATE payouts SET status = 'failed', failure_reason = ? WHERE id = ?`,
+        [disbErr.message.slice(0, 255), payoutId]
+      );
+      return res.status(502).json({ error: 'Payout failed. Balance restored. Try again.' });
+    }
+
+    res.status(201).json({
+      id:        payoutId,
+      amount:    amountNum,
+      payout_fee: feeAmount,
+      net_amount: netAmount,
+      status:    'processing',
+      message:   'Payout initiated. Funds will arrive shortly.',
+    });
+  } catch (err) {
+    console.error('[payouts/POST]', err.message);
+    res.status(500).json({ error: 'Payout failed' });
+  }
+});
+
+module.exports = router;

src/routes/plans.routes.js

@@ -0,0 +1,122 @@
+const router = require('express').Router();
+const db     = require('../config/db');
+const { requireAuth } = require('../middleware/auth');
+
+router.use(requireAuth);
+
+// GET /api/plans?deviceId=
+router.get('/', async (req, res) => {
+  const { deviceId } = req.query;
+  if (!deviceId) return res.status(400).json({ error: 'deviceId required' });
+
+  try {
+    // Verify device belongs to client
+    const device = await db.query(
+      'SELECT id FROM devices WHERE id = ? AND client_id = ? LIMIT 1',
+      [deviceId, req.client.id]
+    ).then(r => r[0]);
+    if (!device) return res.status(404).json({ error: 'Device not found' });
+
+    const plans = await db.query(
+      `SELECT * FROM wifi_plans WHERE device_id = ? ORDER BY display_order ASC`,
+      [deviceId]
+    );
+    res.json(plans);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to fetch plans' });
+  }
+});
+
+// POST /api/plans
+router.post('/', async (req, res) => {
+  const { device_id, name, duration_seconds, price, down_limit, down_unit, up_limit, up_unit, display_order } = req.body;
+
+  if (!device_id || !name || !duration_seconds || !price) {
+    return res.status(400).json({ error: 'device_id, name, duration_seconds, price required' });
+  }
+
+  try {
+    const device = await db.query(
+      'SELECT id FROM devices WHERE id = ? AND client_id = ? LIMIT 1',
+      [device_id, req.client.id]
+    ).then(r => r[0]);
+    if (!device) return res.status(404).json({ error: 'Device not found' });
+
+    const result = await db.query(
+      `INSERT INTO wifi_plans
+         (client_id, device_id, name, duration_seconds, price,
+          down_limit, down_unit, up_limit, up_unit, display_order)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        req.client.id, device_id, name,
+        parseInt(duration_seconds), parseFloat(price),
+        down_limit || 2, down_unit || 2,
+        up_limit   || 2, up_unit   || 2,
+        display_order || 0,
+      ]
+    );
+
+    const plan = await db.query('SELECT * FROM wifi_plans WHERE id = ?', [result.insertId]).then(r => r[0]);
+    res.status(201).json(plan);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to create plan' });
+  }
+});
+
+// PUT /api/plans/:id
+router.put('/:id', async (req, res) => {
+  const { name, duration_seconds, price, down_limit, down_unit, up_limit, up_unit, display_order, is_active } = req.body;
+
+  try {
+    const plan = await db.query(
+      'SELECT p.* FROM wifi_plans p JOIN devices d ON d.id = p.device_id WHERE p.id = ? AND d.client_id = ? LIMIT 1',
+      [req.params.id, req.client.id]
+    ).then(r => r[0]);
+    if (!plan) return res.status(404).json({ error: 'Plan not found' });
+
+    await db.query(
+      `UPDATE wifi_plans SET
+         name             = COALESCE(?, name),
+         duration_seconds = COALESCE(?, duration_seconds),
+         price            = COALESCE(?, price),
+         down_limit       = COALESCE(?, down_limit),
+         down_unit        = COALESCE(?, down_unit),
+         up_limit         = COALESCE(?, up_limit),
+         up_unit          = COALESCE(?, up_unit),
+         display_order    = COALESCE(?, display_order),
+         is_active        = COALESCE(?, is_active)
+       WHERE id = ?`,
+      [
+        name || null, duration_seconds || null, price || null,
+        down_limit || null, down_unit || null,
+        up_limit || null, up_unit || null,
+        display_order !== undefined ? display_order : null,
+        is_active !== undefined ? is_active : null,
+        req.params.id,
+      ]
+    );
+
+    const updated = await db.query('SELECT * FROM wifi_plans WHERE id = ?', [req.params.id]).then(r => r[0]);
+    res.json(updated);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to update plan' });
+  }
+});
+
+// DELETE /api/plans/:id  (soft delete — deactivate)
+router.delete('/:id', async (req, res) => {
+  try {
+    const plan = await db.query(
+      'SELECT p.id FROM wifi_plans p JOIN devices d ON d.id = p.device_id WHERE p.id = ? AND d.client_id = ? LIMIT 1',
+      [req.params.id, req.client.id]
+    ).then(r => r[0]);
+    if (!plan) return res.status(404).json({ error: 'Plan not found' });
+
+    await db.query('UPDATE wifi_plans SET is_active = 0 WHERE id = ?', [req.params.id]);
+    res.json({ message: 'Plan deactivated' });
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to delete plan' });
+  }
+});
+
+module.exports = router;

src/routes/portal.routes.js

@@ -0,0 +1,326 @@
+const router = require('express').Router();
+const path   = require('path');
+const fs     = require('fs');
+const db     = require('../config/db');
+const omada  = require('../services/omada');
+const snippe = require('../services/snippe');
+const sms    = require('../services/sms');
+const { generateCode } = require('../utils/generateCode');
+const { v4: uuidv4 } = require('uuid');
+const { purchaseLimiter, portalAuthLimiter } = require('../middleware/rateLimiter');
+
+// ── GET /portal/:siteId  — render captive portal page ────────────────────────
+router.get('/:siteId', async (req, res) => {
+  const { siteId } = req.params;
+  const { clientMac = '', apMac = '', ssidName = '' } = req.query;
+
+  try {
+    const device = await db.query(
+      `SELECT d.*, c.business_name, c.commission_rate
+       FROM devices d JOIN clients c ON c.id = d.client_id
+       WHERE d.omada_site_id = ? LIMIT 1`,
+      [siteId]
+    ).then(r => r[0]);
+
+    if (!device) {
+      return res.status(404).send('<h2>Portal not found</h2>');
+    }
+
+    // Suspended device
+    if (!['trial', 'active'].includes(device.billing_status)) {
+      return res.render('suspended', { businessName: device.business_name });
+    }
+
+    // Auto-reconnect: if this MAC has an active, non-expired token, re-authorize silently
+    if (clientMac) {
+      const mac = clientMac.toUpperCase().replace(/:/g, '-');
+      const activeToken = await db.query(
+        `SELECT * FROM access_tokens
+         WHERE device_id = ? AND locked_mac = ? AND status = 'active'
+           AND expires_at > NOW()
+         ORDER BY expires_at DESC LIMIT 1`,
+        [device.id, mac]
+      ).then(r => r[0]);
+
+      if (activeToken) {
+        try {
+          await omada.authorizeClient(siteId, mac);
+          await omada.applyRateLimit(siteId, mac, {
+            downLimit: activeToken.down_limit,
+            downUnit:  activeToken.down_unit,
+            upLimit:   activeToken.up_limit,
+            upUnit:    activeToken.up_unit,
+            name:      `Guest-${activeToken.code}`,
+          });
+        } catch (omadaErr) {
+          console.error('[portal/GET] Auto-reconnect Omada error:', omadaErr.message);
+          // Fall through to normal portal render if Omada fails
+        }
+
+        const secsLeft = Math.floor((new Date(activeToken.expires_at) - Date.now()) / 1000);
+        const unitLabel = (v, u) => `${v}${u === 2 ? 'Mbps' : 'Kbps'}`;
+        return res.render('reconnected', {
+          businessName: device.business_name,
+          code:         activeToken.code,
+          expiresIn:    secsLeft,
+          speedDown:    unitLabel(activeToken.down_limit, activeToken.down_unit),
+          speedUp:      unitLabel(activeToken.up_limit,   activeToken.up_unit),
+        });
+      }
+    }
+
+    // Get active plans
+    const plans = await db.query(
+      `SELECT id, name, duration_seconds, price, down_limit, down_unit, up_limit, up_unit
+       FROM wifi_plans
+       WHERE device_id = ? AND is_active = 1
+       ORDER BY display_order ASC`,
+      [device.id]
+    );
+
+    // Portal customization settings (use defaults if not set)
+    const portalSettings = await db.queryOne(
+      'SELECT * FROM device_portal_settings WHERE device_id = ?',
+      [device.id]
+    );
+    const customize = {
+      displayName:   portalSettings?.display_name  || device.business_name,
+      welcomeText:   portalSettings?.welcome_text  || 'Get online instantly',
+      logoUrl:       portalSettings?.logo_url      || null,
+      supportPhone:  portalSettings?.support_phone || null,
+      primaryColor:  portalSettings?.primary_color || '#4361ee',
+      bgColor:       portalSettings?.bg_color      || '#1a1a2e',
+    };
+
+    const portalData = {
+      siteId,
+      clientMac,
+      apMac,
+      ssidName,
+      plans,
+      businessName: device.business_name,
+      deviceName:   device.name,
+      customize,
+    };
+
+    // Custom portal HTML?
+    if (device.portal_html_path) {
+      const htmlPath = path.resolve('./portals', device.portal_html_path);
+      if (fs.existsSync(htmlPath)) {
+        let html = fs.readFileSync(htmlPath, 'utf8');
+        const inject =
+          `<script>window.PORTAL=${JSON.stringify(portalData)};</script>` +
+          `<script src="/engine.js"></script>`;
+        html = html.replace('</body>', inject + '</body>');
+        return res.send(html);
+      }
+    }
+
+    // Default EJS template
+    return res.render('portal', { portal: portalData });
+  } catch (err) {
+    console.error('[portal/GET]', err.message);
+    res.status(500).send('<h2>Service error. Please try again.</h2>');
+  }
+});
+
+// ── POST /portal/:siteId/purchase  — initiate payment ────────────────────────
+router.post('/:siteId/purchase', purchaseLimiter, async (req, res) => {
+  const { siteId } = req.params;
+  const { planId, phone } = req.body;
+
+  if (!planId || !phone) {
+    return res.status(400).json({ error: 'planId and phone required' });
+  }
+
+  try {
+    const device = await db.query(
+      `SELECT d.*, c.commission_rate
+       FROM devices d JOIN clients c ON c.id = d.client_id
+       WHERE d.omada_site_id = ? AND d.status = 'online' LIMIT 1`,
+      [siteId]
+    ).then(r => r[0]);
+
+    if (!device) return res.status(404).json({ error: 'Device not found or offline' });
+    if (!['trial', 'active'].includes(device.billing_status)) {
+      return res.status(403).json({ error: 'WiFi service unavailable — billing suspended' });
+    }
+
+    const plan = await db.query(
+      'SELECT * FROM wifi_plans WHERE id = ? AND device_id = ? AND is_active = 1 LIMIT 1',
+      [planId, device.id]
+    ).then(r => r[0]);
+
+    if (!plan) return res.status(404).json({ error: 'Plan not found' });
+
+    const reference = uuidv4().replace(/-/g, '').slice(0, 24);
+
+    await db.query(
+      `INSERT INTO payments
+         (reference, client_id, device_id, plan_id, phone, phone_provider,
+          gross_amount, commission_rate, status)
+       VALUES (?, ?, ?, ?, ?, 'mpesa', ?, ?, 'pending')`,
+      [reference, device.client_id, device.id, plan.id, phone, plan.price, device.commission_rate]
+    );
+
+    const webhookBase = `${process.env.PORTAL_SCHEME || 'http'}://${process.env.PORTAL_HOST}`;
+    try {
+      await snippe.createPayment({
+        reference,
+        amount:     plan.price,
+        phone,
+        webhookUrl: `${webhookBase}/api/webhooks/snippe`,
+        metadata:   {
+          payment_type: 'wifi_purchase',
+          device_id:    String(device.id),
+          plan_id:      String(plan.id),
+        },
+      });
+    } catch (payErr) {
+      console.error('[portal/purchase] Snippe error:', payErr.message);
+      // Don't fail — webhook will confirm; guest can poll
+    }
+
+    res.json({ reference, status: 'pending' });
+  } catch (err) {
+    console.error('[portal/purchase]', err.message);
+    res.status(500).json({ error: 'Purchase failed. Please try again.' });
+  }
+});
+
+// ── GET /portal/:siteId/check/:reference  — poll payment status ───────────────
+router.get('/:siteId/check/:reference', async (req, res) => {
+  try {
+    const payment = await db.query(
+      `SELECT p.status, p.access_token_code, p.gross_amount,
+              wp.name AS plan_name, wp.duration_seconds,
+              wp.down_limit, wp.down_unit, wp.up_limit, wp.up_unit
+       FROM payments p
+       JOIN wifi_plans wp ON wp.id = p.plan_id
+       WHERE p.reference = ? LIMIT 1`,
+      [req.params.reference]
+    ).then(r => r[0]);
+
+    if (!payment) return res.status(404).json({ error: 'Payment not found' });
+
+    if (payment.status === 'completed' && payment.access_token_code) {
+      return res.json({
+        status:    'paid',
+        code:      payment.access_token_code,
+        plan_name: payment.plan_name,
+      });
+    }
+
+    if (payment.status === 'failed') {
+      return res.json({ status: 'failed' });
+    }
+
+    res.json({ status: 'pending' });
+  } catch (err) {
+    res.status(500).json({ error: 'Check failed' });
+  }
+});
+
+// ── POST /portal/:siteId/auth  — authorize guest on WiFi ──────────────────────
+router.post('/:siteId/auth', portalAuthLimiter, async (req, res) => {
+  const { siteId } = req.params;
+  const { code, clientMac } = req.body;
+
+  if (!code || !clientMac) {
+    return res.status(400).json({ error: 'code and clientMac required' });
+  }
+
+  const mac = clientMac.toUpperCase().replace(/:/g, '-');
+
+  try {
+    const token = await db.query(
+      `SELECT t.*, d.omada_site_id
+       FROM access_tokens t
+       JOIN devices d ON d.id = t.device_id
+       WHERE t.code = ? AND d.omada_site_id = ? LIMIT 1`,
+      [code.toUpperCase(), siteId]
+    ).then(r => r[0]);
+
+    if (!token) return res.status(404).json({ error: 'Invalid code' });
+
+    if (token.status === 'expired' || token.status === 'revoked') {
+      return res.status(410).json({ error: 'Code has expired' });
+    }
+
+    if (token.status === 'active') {
+      // Reconnect — verify same MAC
+      if (token.locked_mac && token.locked_mac.toUpperCase() !== mac) {
+        return res.status(403).json({ error: 'Code is locked to another device' });
+      }
+      // Check not expired
+      if (token.expires_at && new Date(token.expires_at) < new Date()) {
+        await db.query(`UPDATE access_tokens SET status = 'expired' WHERE id = ?`, [token.id]);
+        return res.status(410).json({ error: 'Code has expired' });
+      }
+    }
+
+    if (token.status !== 'unused' && token.status !== 'active') {
+      return res.status(400).json({ error: 'Code cannot be used' });
+    }
+
+    // Authorize on Omada
+    try {
+      await omada.authorizeClient(siteId, mac);
+      await omada.applyRateLimit(siteId, mac, {
+        downLimit: token.down_limit,
+        downUnit:  token.down_unit,
+        upLimit:   token.up_limit,
+        upUnit:    token.up_unit,
+        name:      `Guest-${token.code}`,
+      });
+    } catch (omadaErr) {
+      console.error('[portal/auth] Omada auth failed:', omadaErr.message);
+      return res.status(503).json({ error: 'Authorization failed. The AP may be offline.' });
+    }
+
+    // Activate token
+    const now       = new Date();
+    const expiresAt = new Date(now.getTime() + token.duration_seconds * 1000);
+
+    await db.query(
+      `UPDATE access_tokens SET
+         status       = 'active',
+         locked_mac   = ?,
+         activated_at = ?,
+         expires_at   = ?
+       WHERE id = ?`,
+      [mac, now, expiresAt, token.id]
+    );
+
+    // Upsert session
+    const existingSession = await db.query(
+      'SELECT id FROM sessions WHERE access_token_id = ? AND client_mac = ? LIMIT 1',
+      [token.id, mac]
+    ).then(r => r[0]);
+
+    if (!existingSession) {
+      await db.query(
+        `INSERT INTO sessions (access_token_id, client_id, device_id, client_mac)
+         VALUES (?, ?, ?, ?)`,
+        [token.id, token.client_id, token.device_id, mac]
+      );
+    }
+
+    const unitLabel = (v, u) => `${v}${u === 2 ? 'Mbps' : 'Kbps'}`;
+    const secsLeft  = Math.floor((expiresAt - now) / 1000);
+
+    res.json({
+      success:    true,
+      code:       token.code,
+      expiresIn:  secsLeft,
+      expiresAt:  expiresAt.toISOString(),
+      speedDown:  unitLabel(token.down_limit, token.down_unit),
+      speedUp:    unitLabel(token.up_limit,   token.up_unit),
+    });
+  } catch (err) {
+    console.error('[portal/auth]', err.message);
+    res.status(500).json({ error: 'Authorization failed' });
+  }
+});
+
+module.exports = router;

src/routes/sessions.routes.js

@@ -0,0 +1,62 @@
+const router = require('express').Router();
+const db     = require('../config/db');
+const { requireAuth } = require('../middleware/auth');
+
+router.use(requireAuth);
+
+// GET /api/sessions/active
+router.get('/active', async (req, res) => {
+  try {
+    const sessions = await db.query(
+      `SELECT s.id, s.client_mac, s.client_ip, s.ssid, s.started_at,
+              s.last_seen_at, s.bytes_down, s.bytes_up, s.duration_seconds,
+              s.rssi, s.signal_level,
+              d.name AS device_name,
+              t.code AS token_code, t.expires_at,
+              wp.name AS plan_name
+       FROM sessions s
+       JOIN devices d ON d.id = s.device_id
+       LEFT JOIN access_tokens t ON t.id = s.access_token_id
+       LEFT JOIN wifi_plans wp ON wp.id = t.plan_id
+       WHERE s.client_id = ? AND s.is_active = 1
+       ORDER BY s.started_at DESC`,
+      [req.client.id]
+    );
+    res.json(sessions);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to fetch sessions' });
+  }
+});
+
+// GET /api/sessions?deviceId=&limit=
+router.get('/', async (req, res) => {
+  const { deviceId, limit = 50 } = req.query;
+  try {
+    let sql = `
+      SELECT s.id, s.client_mac, s.started_at, s.ended_at,
+             s.bytes_down, s.bytes_up, s.duration_seconds, s.is_active,
+             d.name AS device_name,
+             t.code AS token_code, wp.name AS plan_name, wp.price AS plan_price
+      FROM sessions s
+      JOIN devices d ON d.id = s.device_id
+      LEFT JOIN access_tokens t ON t.id = s.access_token_id
+      LEFT JOIN wifi_plans wp ON wp.id = t.plan_id
+      WHERE s.client_id = ?`;
+    const params = [req.client.id];
+
+    if (deviceId) {
+      sql += ' AND s.device_id = ?';
+      params.push(deviceId);
+    }
+
+    sql += ` ORDER BY s.started_at DESC LIMIT ?`;
+    params.push(parseInt(limit) || 50);
+
+    const sessions = await db.query(sql, params);
+    res.json(sessions);
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to fetch sessions' });
+  }
+});
+
+module.exports = router;

src/routes/webhooks.routes.js

@@ -0,0 +1,215 @@
+const router   = require('express').Router();
+const db       = require('../config/db');
+const snippe   = require('../services/snippe');
+const sms      = require('../services/sms');
+const messages = require('../utils/messages');
+const { generateCode } = require('../utils/generateCode');
+
+// Raw body needed for signature verification
+router.use(require('express').raw({ type: 'application/json' }));
+
+// POST /api/webhooks/snippe
+router.post('/snippe', async (req, res) => {
+  let event;
+  try {
+    event = snippe.verifyWebhookSignature(req.body.toString(), req.headers);
+  } catch (err) {
+    console.error('[webhook/snippe] Signature invalid:', err.message);
+    return res.status(400).json({ error: 'Invalid signature' });
+  }
+
+  // Respond immediately
+  res.status(200).json({ received: true });
+
+  // Process async
+  processSnippeEvent(event).catch(err =>
+    console.error('[webhook/snippe] Processing error:', err.message)
+  );
+});
+
+async function processSnippeEvent(event) {
+  const { type, data } = event;
+
+  switch (type) {
+    case 'payment.completed':
+      await handlePaymentCompleted(data);
+      break;
+    case 'payment.failed':
+      await handlePaymentFailed(data);
+      break;
+    case 'payout.completed':
+      await handlePayoutCompleted(data);
+      break;
+    case 'payout.failed':
+      await handlePayoutFailed(data);
+      break;
+    default:
+      console.log(`[webhook/snippe] Unhandled event: ${type}`);
+  }
+}
+
+async function handlePaymentCompleted(data) {
+  const reference = data.reference || data.external_reference;
+  if (!reference) return;
+
+  // ── WiFi guest purchase ────────────────────────────────────────────────────
+  // Atomically claim the payment — only one concurrent webhook can advance it
+  const claim = await db.query(
+    `UPDATE payments SET status = 'processing' WHERE reference = ? AND status = 'pending'`,
+    [reference]
+  );
+
+  if (claim.affectedRows === 1) {
+    const payment = await db.query(
+      `SELECT p.*, wp.duration_seconds,
+              wp.down_limit, wp.down_unit, wp.up_limit, wp.up_unit, wp.name AS plan_name,
+              d.name AS device_name, c.phone AS client_phone
+       FROM payments p
+       JOIN wifi_plans wp ON wp.id = p.plan_id
+       JOIN devices d ON d.id = p.device_id
+       JOIN clients c ON c.id = p.client_id
+       WHERE p.reference = ? LIMIT 1`,
+      [reference]
+    ).then(r => r[0]);
+
+    const code = generateCode();
+
+    // Create access token
+    const tokenResult = await db.query(
+      `INSERT INTO access_tokens
+         (client_id, device_id, plan_id, payment_id, code, duration_seconds,
+          down_limit, down_unit, up_limit, up_unit, status)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'unused')`,
+      [
+        payment.client_id, payment.device_id, payment.plan_id, payment.id,
+        code, payment.duration_seconds,
+        payment.down_limit, payment.down_unit, payment.up_limit, payment.up_unit,
+      ]
+    );
+
+    // Mark payment completed (trigger fires here — credits client balance)
+    await db.query(
+      `UPDATE payments SET
+         status = 'completed',
+         access_token_code = ?,
+         snippe_payment_id = ?
+       WHERE id = ?`,
+      [code, data.external_reference || null, payment.id]
+    );
+
+    // SMS to guest with code
+    const secs = payment.duration_seconds;
+    const duration = secs >= 86400
+      ? `${Math.round(secs / 86400)}d`
+      : secs >= 3600
+        ? `${Math.round(secs / 3600)}h`
+        : `${Math.round(secs / 60)}min`;
+    sms.sendSMS(payment.phone, messages.wifiCode(code, payment.plan_name, duration, payment.device_name)).catch(() => {});
+
+    console.log(`[webhook] WiFi payment completed: ${reference} → code ${code}`);
+    return;
+  }
+
+  // ── Device subscription renewal ───────────────────────────────────────────
+  const devPayment = await db.query(
+    `SELECT dp.*, d.billing_expires_at, d.name AS device_name, c.phone AS client_phone
+     FROM device_payments dp
+     JOIN devices d ON d.id = dp.device_id
+     JOIN clients c ON c.id = dp.client_id
+     WHERE dp.reference = ? AND dp.status = 'pending' LIMIT 1`,
+    [reference]
+  ).then(r => r[0]);
+
+  if (devPayment) {
+    // Extend billing by 30 days from current expiry (or now if suspended)
+    const base     = devPayment.billing_expires_at
+      ? new Date(devPayment.billing_expires_at)
+      : new Date();
+    const newExpiry = new Date(base.getTime() + 30 * 24 * 60 * 60 * 1000);
+
+    await db.query(
+      `UPDATE devices SET billing_status = 'active', billing_expires_at = ? WHERE id = ?`,
+      [newExpiry, devPayment.device_id]
+    );
+
+    await db.query(
+      `UPDATE device_payments SET status = 'completed', completed_at = NOW(),
+         snippe_payment_id = ? WHERE id = ?`,
+      [data.external_reference || null, devPayment.id]
+    );
+
+    sms.sendSMS(devPayment.client_phone,
+      messages.deviceRenewal(devPayment.device_name, newExpiry.toLocaleDateString('en-TZ'))
+    ).catch(() => {});
+
+    console.log(`[webhook] Device renewal completed: ${reference}`);
+  }
+}
+
+async function handlePaymentFailed(data) {
+  const reference = data.reference;
+  if (!reference) return;
+
+  await db.query(
+    `UPDATE payments SET status = 'failed' WHERE reference = ? AND status = 'pending'`,
+    [reference]
+  );
+  await db.query(
+    `UPDATE device_payments SET status = 'failed' WHERE reference = ? AND status = 'pending'`,
+    [reference]
+  );
+
+  console.log(`[webhook] Payment failed: ${reference}`);
+}
+
+async function handlePayoutCompleted(data) {
+  const reference = data.reference;
+  if (!reference) return;
+
+  // trg_payout_completed trigger updates total_withdrawn
+  await db.query(
+    `UPDATE payouts SET status = 'completed', snippe_disbursement_id = ?, completed_at = NOW()
+     WHERE snippe_disbursement_id = ? OR id = ?
+     AND status IN ('pending','processing')`,
+    [reference, reference, 0]
+  );
+
+  // Better: find by disbursement id
+  const payout = await db.query(
+    `SELECT po.*, c.phone AS client_phone
+     FROM payouts po JOIN clients c ON c.id = po.client_id
+     WHERE po.snippe_disbursement_id = ? LIMIT 1`,
+    [reference]
+  ).then(r => r[0]);
+
+  if (payout) {
+    await db.query(
+      `UPDATE payouts SET status = 'completed', completed_at = NOW() WHERE id = ?`,
+      [payout.id]
+    );
+    sms.sendSMS(payout.client_phone, messages.payoutCompleted(payout.net_amount)).catch(() => {});
+    console.log(`[webhook] Payout completed: ${reference}`);
+  }
+}
+
+async function handlePayoutFailed(data) {
+  const reference = data.reference;
+  const payout = await db.query(
+    `SELECT po.*, c.phone AS client_phone
+     FROM payouts po JOIN clients c ON c.id = po.client_id
+     WHERE po.snippe_disbursement_id = ? LIMIT 1`,
+    [reference]
+  ).then(r => r[0]);
+
+  if (payout) {
+    // trg_payout_failed trigger restores balance
+    await db.query(
+      `UPDATE payouts SET status = 'failed', failure_reason = ? WHERE id = ?`,
+      [data.failure_reason || 'Provider error', payout.id]
+    );
+    sms.sendSMS(payout.client_phone, messages.payoutFailed(payout.amount)).catch(() => {});
+    console.log(`[webhook] Payout failed: ${reference}`);
+  }
+}
+
+module.exports = router;

src/server.js

@@ -0,0 +1,31 @@
+require('dotenv').config();
+
+const app    = require('./app');
+const omada  = require('./services/omada');
+const { initJobs } = require('./jobs');
+
+const PORT = process.env.PORT || 3000;
+
+async function start() {
+  // 1. Boot Omada connection
+  try {
+    await omada.initOmada();
+  } catch (err) {
+    console.error('[Boot] Omada init failed:', err.message);
+    console.warn('[Boot] Continuing without Omada — check OMADA_URL / credentials');
+  }
+
+  // 2. Start background jobs
+  initJobs();
+
+  // 3. Listen
+  app.listen(PORT, () => {
+    console.log(`[Server] Listening on http://0.0.0.0:${PORT}`);
+    console.log(`[Server] Portal base: ${process.env.PORTAL_SCHEME}://${process.env.PORTAL_HOST}`);
+  });
+}
+
+start().catch(err => {
+  console.error('[Boot] Fatal error:', err.message);
+  process.exit(1);
+});

src/services/omada.js

@@ -0,0 +1,240 @@
+const axios = require('axios');
+const https = require('https');
+
+// Omada uses self-signed certs on the controller
+const httpsAgent = new https.Agent({ rejectUnauthorized: false });
+
+let controllerId = null;
+let csrfToken    = null;
+let sessionCookies = '';
+
+const client = axios.create({
+  httpsAgent,
+  timeout: 20000,
+});
+
+// ── Init ──────────────────────────────────────────────────────────────────────
+
+async function initOmada() {
+  // 1. Fetch controller ID
+  const infoRes = await client.get(`${process.env.OMADA_URL}/api/info`);
+  controllerId = infoRes.data.result.omadacId;
+
+  // 2. Login
+  await omadaLogin();
+
+  // 3. 25-min keepalive
+  setInterval(keepAlive, 25 * 60 * 1000);
+
+  console.log(`[Omada] Ready. controllerId=${controllerId}`);
+}
+
+async function omadaLogin() {
+  const res = await client.post(
+    `${process.env.OMADA_URL}/${controllerId}/api/v2/login`,
+    { username: process.env.OMADA_USER, password: process.env.OMADA_PASS }
+  );
+  csrfToken = res.data.result.token;
+  const setCookie = res.headers['set-cookie'] || [];
+  sessionCookies = setCookie.map(c => c.split(';')[0]).join('; ');
+}
+
+async function keepAlive() {
+  try {
+    await omadaRequest('GET', '/current/users');
+  } catch (err) {
+    console.error('[Omada] Keepalive failed:', err.message);
+  }
+}
+
+// ── Core request helper ───────────────────────────────────────────────────────
+
+async function omadaRequest(method, path, data = null, retried = false) {
+  if (!csrfToken) await omadaLogin();
+
+  try {
+    const res = await client({
+      method,
+      url: `${process.env.OMADA_URL}/${controllerId}/api/v2${path}`,
+      headers: {
+        'Csrf-Token':   csrfToken,
+        Cookie:         sessionCookies,
+        'Content-Type': 'application/json',
+      },
+      data: data ?? undefined,
+    });
+
+    // Omada returns errorCode 0 on success; -1000 = session expired
+    if (res.data.errorCode === -1000 && !retried) {
+      await omadaLogin();
+      return omadaRequest(method, path, data, true);
+    }
+
+    if (res.data.errorCode !== 0) {
+      const err = new Error(res.data.msg || `Omada error ${res.data.errorCode}`);
+      err.errorCode = res.data.errorCode;
+      err.result    = res.data.result;
+      throw err;
+    }
+
+    return res.data;
+  } catch (err) {
+    if (err.response?.status === 401 && !retried) {
+      await omadaLogin();
+      return omadaRequest(method, path, data, true);
+    }
+    throw err;
+  }
+}
+
+// ── Sites ─────────────────────────────────────────────────────────────────────
+
+async function createSite(name, scenario = 'Hotel') {
+  const res = await omadaRequest('POST', '/sites', {
+    name,
+    scenario,
+    region:   'Tanzania',
+    timeZone: 'Africa/Dar_es_Salaam',
+  });
+  return res.result; // siteId string
+}
+
+async function getSites() {
+  const res = await omadaRequest('GET', '/sites?currentPageSize=200&currentPage=1');
+  return res.result?.data || [];
+}
+
+async function getSiteById(siteId) {
+  const sites = await getSites();
+  return sites.find(s => s.id === siteId) || null;
+}
+
+// ── Portal ────────────────────────────────────────────────────────────────────
+
+async function createPortal(siteId, portalName, ssidList = []) {
+  const serverUrl = `${process.env.PORTAL_HOST}/portal/${siteId}`;
+  const res = await omadaRequest('POST', `/sites/${siteId}/setting/portals`, {
+    name:                portalName,
+    enable:              true,
+    httpsRedirectEnable: false,
+    landingPage:         1,
+    authType:            4,
+    externalPortal: {
+      hostType:        2,
+      serverUrlScheme: process.env.PORTAL_SCHEME || 'http',
+      serverUrl,
+      logout:          false,
+    },
+    ssidList,
+    networkList: [],
+    pageType:    1,
+    portalCustomize: {
+      defaultLanguage:        1,
+      background:             2,
+      logoDisplay:            true,
+      welcomeEnable:          false,
+      termsOfServiceEnable:   false,
+      copyrightEnable:        false,
+      redirectionCountDownEnable: true,
+      advertisement: { enable: false, pictureIds: [] },
+      buttonText: 'Log In',
+    },
+  });
+  return res.result; // portalId string
+}
+
+// ── Devices ───────────────────────────────────────────────────────────────────
+
+async function getSiteDevices(siteId) {
+  const res = await omadaRequest('GET',
+    `/sites/${siteId}/grid/devices?currentPage=1&currentPageSize=50`
+  );
+  return res.result?.data || [];
+}
+
+async function getAllAdoptedDevices() {
+  const res = await omadaRequest('GET',
+    '/grid/devices/adopted?currentPage=1&currentPageSize=200'
+  );
+  return res.result?.data || [];
+}
+
+async function adoptDevice(siteId, mac, username, password) {
+  return omadaRequest('POST', `/sites/${siteId}/cmd/devices/adopt`, {
+    mac, username, password,
+  });
+}
+
+async function rebootDevice(siteId, mac) {
+  return omadaRequest('POST', `/sites/${siteId}/cmd/devices/${mac}/reboot`, { mac });
+}
+
+// ── Clients (guests) ──────────────────────────────────────────────────────────
+
+async function getClient(siteId, mac) {
+  const res = await omadaRequest('GET', `/sites/${siteId}/clients/${mac}`);
+  return res.result;
+}
+
+async function getSiteClients(siteId) {
+  const res = await omadaRequest('GET',
+    `/sites/${siteId}/clients?currentPage=1&currentPageSize=200&filters.active=true`
+  );
+  return res.result?.data || [];
+}
+
+async function authorizeClient(siteId, mac) {
+  return omadaRequest('POST', `/sites/${siteId}/cmd/clients/${mac}/auth`, {});
+}
+
+async function deauthorizeClient(siteId, mac) {
+  return omadaRequest('POST', `/sites/${siteId}/cmd/clients/${mac}/unauthorize`, {});
+}
+
+async function applyRateLimit(siteId, mac, { downLimit, downUnit, upLimit, upUnit, name = 'Guest' }) {
+  return omadaRequest('PATCH', `/sites/${siteId}/clients/${mac}`, {
+    name,
+    rateLimit: {
+      enable:     true,
+      downEnable: true,
+      downLimit,
+      downUnit,
+      upEnable:   true,
+      upLimit,
+      upUnit,
+    },
+    clientLockToApSetting: { enable: false },
+    ipSetting:             { useFixedAddr: false },
+  });
+}
+
+// ── Alerts ────────────────────────────────────────────────────────────────────
+
+async function getSiteAlerts(siteId) {
+  const now           = Date.now();
+  const thirtyDaysAgo = now - 30 * 24 * 60 * 60 * 1000;
+  const res = await omadaRequest('GET',
+    `/sites/${siteId}/logs/alerts` +
+    `?filters.timeStart=${thirtyDaysAgo}&filters.timeEnd=${now}` +
+    `&filters.resolved=false&currentPage=1&currentPageSize=50`
+  );
+  return res.result?.data || [];
+}
+
+module.exports = {
+  initOmada,
+  createSite,
+  getSites,
+  getSiteById,
+  createPortal,
+  getSiteDevices,
+  getAllAdoptedDevices,
+  adoptDevice,
+  rebootDevice,
+  getClient,
+  getSiteClients,
+  authorizeClient,
+  deauthorizeClient,
+  applyRateLimit,
+  getSiteAlerts,
+};

src/services/sms.js

@@ -0,0 +1,50 @@
+const axios = require('axios');
+const db    = require('../config/db');
+
+function normalizePhone(phone) {
+  const d = phone.replace(/\D/g, '');
+  if (d.startsWith('255')) return '+' + d;
+  if (d.startsWith('0'))   return '+255' + d.slice(1);
+  return '+255' + d;
+}
+
+async function sendSMS(phone, message) {
+  const to     = normalizePhone(phone);
+  let status   = 'sent';
+  let gatewayId = null;
+  let error    = null;
+
+  try {
+    const res = await axios.post(
+      process.env.SMS_GATEWAY_URL,
+      {
+        textMessage:        { text: message },
+        phoneNumbers:       [to],
+        withDeliveryReport: false,
+      },
+      {
+        auth: {
+          username: process.env.SMS_GATEWAY_USER,
+          password: process.env.SMS_GATEWAY_PASS,
+        },
+        timeout: 10000,
+      }
+    );
+    gatewayId = res.data?.id || null;
+    console.log(`[SMS] Sent to ${to}: "${message.slice(0, 40)}..."`);
+  } catch (err) {
+    status = 'failed';
+    error  = err.message;
+    console.error(`[SMS] Failed to ${to}:`, err.message);
+  }
+
+  // Fire-and-forget log
+  db.query(
+    'INSERT INTO sms_log (phone, message, status, gateway_id, error) VALUES (?, ?, ?, ?, ?)',
+    [to, message, status, gatewayId, error]
+  ).catch(() => {});
+
+  return status === 'sent';
+}
+
+module.exports = { sendSMS };

src/services/snippe.js

@@ -0,0 +1,111 @@
+const crypto = require('crypto');
+const axios  = require('axios');
+
+const BASE_URL = 'https://api.snippe.sh';
+
+function ikey(prefix, id) {
+  return `${prefix}-${id}`.slice(0, 30);
+}
+
+function normalizePhone(phone) {
+  const d = phone.replace(/\D/g, '');
+  if (d.startsWith('255')) return d;
+  if (d.startsWith('0'))   return '255' + d.slice(1);
+  return '255' + d;
+}
+
+async function snippeRequest(method, path, body = null, idempotencyKey = null) {
+  const headers = {
+    Authorization:  `Bearer ${process.env.SNIPPE_API_KEY}`,
+    'Content-Type': 'application/json',
+  };
+  if (idempotencyKey) {
+    if (idempotencyKey.length > 30) {
+      throw new Error(`Idempotency key too long (${idempotencyKey.length} chars, max 30)`);
+    }
+    headers['Idempotency-Key'] = idempotencyKey;
+  }
+
+  const res = await axios({
+    method,
+    url:     `${BASE_URL}${path}`,
+    headers,
+    data:    body ?? undefined,
+    timeout: 30000,
+  });
+  return res.data;
+}
+
+// ── Collection ────────────────────────────────────────────────────────────────
+
+async function createPayment({ reference, amount, phone, webhookUrl, metadata = {} }) {
+  return snippeRequest('POST', '/v1/payments', {
+    payment_type: 'mobile',
+    details:      { amount, currency: 'TZS' },
+    phone_number: normalizePhone(phone),
+    customer: {
+      firstname: metadata.firstname || 'Guest',
+      lastname:  metadata.lastname  || 'User',
+      email:     metadata.email     || 'guest@wifi.local',
+    },
+    webhook_url: webhookUrl,
+    metadata,
+  }, ikey('pay', reference));
+}
+
+async function getPayment(reference) {
+  return snippeRequest('GET', `/v1/payments/${reference}`);
+}
+
+// ── Disbursements ─────────────────────────────────────────────────────────────
+
+async function getPayoutFee(amount) {
+  const res = await snippeRequest('GET', `/v1/payouts/fee?amount=${amount}`);
+  return res.data; // { amount, fee_amount, total_amount, currency }
+}
+
+async function createPayout({ payoutId, amount, phone, recipientName, narration, webhookUrl }) {
+  const feeData = await getPayoutFee(amount);
+  const res = await snippeRequest('POST', '/v1/payouts/send', {
+    amount,
+    channel:        'mobile',
+    recipient_phone: normalizePhone(phone),
+    recipient_name:  recipientName,
+    narration:       narration || 'WiFi platform payout',
+    webhook_url:     webhookUrl,
+    metadata: { payout_id: String(payoutId) },
+  }, ikey('po', payoutId));
+  return { ...res, feeData };
+}
+
+// ── Webhook verification ──────────────────────────────────────────────────────
+
+function verifyWebhookSignature(rawBody, headers) {
+  const timestamp   = headers['x-webhook-timestamp'];
+  const receivedSig = headers['x-webhook-signature'];
+
+  if (!timestamp || !receivedSig) throw new Error('Missing webhook signature headers');
+
+  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10);
+  if (age > 300) throw new Error('Webhook timestamp too old (possible replay attack)');
+
+  const expected = crypto
+    .createHmac('sha256', process.env.SNIPPE_WEBHOOK_SECRET)
+    .update(`${timestamp}.${rawBody}`)
+    .digest('hex');
+
+  if (!crypto.timingSafeEqual(Buffer.from(receivedSig), Buffer.from(expected))) {
+    throw new Error('Invalid webhook signature');
+  }
+
+  return JSON.parse(rawBody);
+}
+
+module.exports = {
+  createPayment,
+  getPayment,
+  getPayoutFee,
+  createPayout,
+  verifyWebhookSignature,
+  normalizePhone,
+};

src/utils/adminAlert.js

@@ -0,0 +1,24 @@
+const db  = require('../config/db');
+const sms = require('../services/sms');
+
+// In-memory cooldown — don't spam the same alert key more than once per 10 min
+const lastSent = {};
+const COOLDOWN_MS = 10 * 60 * 1000;
+
+async function alertAdmin(key, message) {
+  const now = Date.now();
+  if (lastSent[key] && now - lastSent[key] < COOLDOWN_MS) return;
+  lastSent[key] = now;
+
+  try {
+    const row = await db.queryOne(
+      `SELECT value FROM system_config WHERE \`key\` = 'admin_phone'`
+    );
+    if (!row) return;
+    await sms.sendSMS(row.value, `[SYSTEM ALERT] ${message}`);
+  } catch (err) {
+    console.error('[adminAlert] Failed to send alert:', err.message);
+  }
+}
+
+module.exports = { alertAdmin };

src/utils/generateCode.js

@@ -0,0 +1,10 @@
+// Readable code chars — no 0/O, 1/I confusion
+const CHARS = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+
+function generateCode() {
+  const part = (n) =>
+    Array.from({ length: n }, () => CHARS[Math.floor(Math.random() * CHARS.length)]).join('');
+  return `${part(4)}-${part(4)}`;  // e.g. AB3K-9X2M
+}
+
+module.exports = { generateCode };

src/utils/messages.js

@@ -0,0 +1,49 @@
+/**
+ * SMS message templates.
+ * All outbound SMS text lives here — edit copy in one place.
+ */
+
+module.exports = {
+  // Guest receives this after paying for WiFi
+  wifiCode: (code, planName, duration, deviceName) =>
+    `WiFi Code: ${code}\nPlan: ${planName} (${duration})\nDevice: ${deviceName}\nEnter this code on the WiFi login page. Valid for ${duration} after connecting.`,
+
+  // Tenant receives this after their device subscription renews
+  deviceRenewal: (deviceName, expiryDate) =>
+    `"${deviceName}" renewed until ${expiryDate}. Keep selling!`,
+
+  // Tenant receives this when their AP comes online for the first time
+  deviceOnline: (deviceName) =>
+    `Your device "${deviceName}" is now online! Create WiFi plans to start selling.`,
+
+  // Tenant receives this when their AP goes offline
+  deviceOffline: (deviceName) =>
+    `Alert: Your device "${deviceName}" went offline. Check the AP.`,
+
+  // Tenant receives this when billing expires and device is auto-suspended
+  deviceSuspended: (deviceName, fee) =>
+    `Your device "${deviceName}" has been suspended (billing expired). Pay ${fee} TZS to reactivate.`,
+
+  // Tenant receives this when they manually pause their device
+  devicePaused: (deviceName, fee) =>
+    `Your device "${deviceName}" has been paused. Pay ${fee} TZS to reactivate and resume WiFi service.`,
+
+  // Tenant receives this on successful registration
+  welcome: () =>
+    `Welcome to WiFi Platform! Add your first device on the dashboard to start selling WiFi.`,
+
+  // Tenant receives this 1–3 days before billing expires
+  billingReminder: (deviceName, daysLeft, fee) =>
+    `Reminder: Your WiFi device "${deviceName}" expires in ${daysLeft} day(s). Pay ${parseInt(fee).toLocaleString()} TZS to keep it active.`,
+
+  // Tenant receives this when requesting a password reset
+  passwordResetOtp: (otp) => `Token  is: ${otp}\n.`,
+
+  // Tenant receives this when a payout completes
+  payoutCompleted: (amount) =>
+    `Payout of ${parseInt(amount).toLocaleString()} TZS sent to your M-Pesa.`,
+
+  // Tenant receives this when a payout fails
+  payoutFailed: (amount) =>
+    `Payout of ${parseInt(amount).toLocaleString()} TZS failed. Your balance has been restored.`,
+};

src/views/portal.ejs

@@ -0,0 +1,245 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title><%= portal.businessName %> — WiFi</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 16px;
+    }
+    .card {
+      background: #fff;
+      border-radius: 20px;
+      padding: 32px 24px;
+      width: 100%;
+      max-width: 380px;
+      box-shadow: 0 20px 60px rgba(0,0,0,0.4);
+    }
+    .header {
+      text-align: center;
+      margin-bottom: 28px;
+    }
+    .header h1 {
+      font-size: 22px;
+      font-weight: 700;
+      color: #1a1a2e;
+      margin-bottom: 4px;
+    }
+    .header p {
+      color: #666;
+      font-size: 14px;
+    }
+    .wifi-icon {
+      font-size: 40px;
+      margin-bottom: 12px;
+    }
+    /* Screens */
+    .screen { display: none; }
+    .screen.active { display: block; }
+    /* Plans */
+    .plan-btn {
+      display: block;
+      width: 100%;
+      padding: 14px 16px;
+      margin-bottom: 10px;
+      background: #f8f9ff;
+      border: 2px solid #e8ecff;
+      border-radius: 12px;
+      cursor: pointer;
+      text-align: left;
+      transition: all 0.2s;
+      position: relative;
+    }
+    .plan-btn:hover, .plan-btn.selected {
+      border-color: #4361ee;
+      background: #eef0ff;
+    }
+    .plan-btn .plan-name { font-weight: 600; color: #1a1a2e; font-size: 15px; }
+    .plan-btn .plan-price { float: right; font-weight: 700; color: #4361ee; font-size: 16px; }
+    .plan-btn .plan-speed { font-size: 12px; color: #888; margin-top: 2px; }
+    /* Phone input */
+    .input-group { margin-top: 16px; }
+    .input-group label { font-size: 13px; color: #555; margin-bottom: 6px; display: block; }
+    .input-group input {
+      width: 100%;
+      padding: 12px 14px;
+      border: 2px solid #e0e0e0;
+      border-radius: 10px;
+      font-size: 16px;
+      outline: none;
+      transition: border-color 0.2s;
+    }
+    .input-group input:focus { border-color: #4361ee; }
+    /* Primary button */
+    .btn-primary {
+      display: block;
+      width: 100%;
+      padding: 15px;
+      margin-top: 16px;
+      background: #4361ee;
+      color: #fff;
+      border: none;
+      border-radius: 12px;
+      font-size: 16px;
+      font-weight: 600;
+      cursor: pointer;
+      transition: background 0.2s;
+    }
+    .btn-primary:hover { background: #3451d1; }
+    .btn-primary:disabled { background: #aaa; cursor: not-allowed; }
+    /* Secondary link */
+    .link-btn {
+      display: block;
+      text-align: center;
+      margin-top: 14px;
+      color: #4361ee;
+      font-size: 14px;
+      cursor: pointer;
+      text-decoration: underline;
+    }
+    /* Spinner */
+    .spinner {
+      text-align: center;
+      padding: 20px 0;
+    }
+    .spinner-ring {
+      width: 48px; height: 48px;
+      border: 4px solid #e8ecff;
+      border-top-color: #4361ee;
+      border-radius: 50%;
+      animation: spin 0.8s linear infinite;
+      margin: 0 auto 12px;
+    }
+    @keyframes spin { to { transform: rotate(360deg); } }
+    .spinner p { color: #555; font-size: 14px; }
+    /* Success */
+    .success-icon { font-size: 56px; text-align: center; margin-bottom: 12px; }
+    .code-box {
+      background: #f8f9ff;
+      border: 2px solid #4361ee;
+      border-radius: 12px;
+      padding: 16px;
+      text-align: center;
+      margin: 16px 0;
+    }
+    .code-box .code-label { font-size: 12px; color: #888; margin-bottom: 4px; }
+    .code-box .code-value {
+      font-size: 28px;
+      font-weight: 700;
+      color: #1a1a2e;
+      letter-spacing: 3px;
+      font-family: monospace;
+    }
+    .meta-row {
+      display: flex;
+      justify-content: space-between;
+      font-size: 13px;
+      color: #555;
+      padding: 6px 0;
+      border-bottom: 1px solid #f0f0f0;
+    }
+    .meta-row:last-child { border-bottom: none; }
+    .meta-row strong { color: #1a1a2e; }
+    /* Error */
+    .error-msg {
+      background: #fff0f0;
+      border: 1px solid #ffcccc;
+      color: #cc0000;
+      border-radius: 8px;
+      padding: 10px 14px;
+      font-size: 13px;
+      margin-top: 12px;
+      display: none;
+    }
+    .error-msg.show { display: block; }
+    .divider { text-align: center; color: #bbb; font-size: 13px; margin: 16px 0; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="header">
+      <div class="wifi-icon">📶</div>
+      <h1><%= portal.businessName %></h1>
+      <p>Get online instantly</p>
+    </div>
+
+    <!-- SCREEN 1: Plan selection & phone -->
+    <div id="screen-select" class="screen active">
+      <% if (portal.plans.length === 0) { %>
+        <p style="text-align:center;color:#888;padding:20px 0;">No WiFi plans available yet.<br>Check back soon.</p>
+      <% } else { %>
+        <% portal.plans.forEach(function(plan) {
+          const unit = plan.down_unit === 2 ? 'Mbps' : 'Kbps';
+          const speed = plan.down_limit + unit + ' ↓ / ' + plan.up_limit + unit + ' ↑';
+          const hours = Math.floor(plan.duration_seconds / 3600);
+          const days  = Math.floor(plan.duration_seconds / 86400);
+          const dur   = days >= 1 ? days + (days === 1 ? ' Day' : ' Days') : hours + (hours === 1 ? ' Hour' : ' Hours');
+        %>
+          <button class="plan-btn" data-plan-id="<%= plan.id %>" data-plan-price="<%= plan.price %>">
+            <span class="plan-name"><%= plan.name %></span>
+            <span class="plan-price"><%= parseInt(plan.price).toLocaleString() %> TZS</span>
+            <div class="plan-speed"><%= dur %> &bull; <%= speed %></div>
+          </button>
+        <% }); %>
+
+        <div class="input-group">
+          <label for="phone-input">Your M-Pesa / Mobile Money Phone Number</label>
+          <input type="tel" id="phone-input" placeholder="0712 345 678" inputmode="numeric">
+        </div>
+
+        <div class="error-msg" id="select-error"></div>
+        <button class="btn-primary" id="pay-btn" disabled>Select a plan to continue</button>
+
+        <div class="divider">or</div>
+        <span class="link-btn" id="show-code-entry">Have a code? Enter it here</span>
+      <% } %>
+    </div>
+
+    <!-- SCREEN 2: Waiting for payment -->
+    <div id="screen-waiting" class="screen">
+      <div class="spinner">
+        <div class="spinner-ring"></div>
+        <p>Waiting for M-Pesa payment...</p>
+        <p style="font-size:12px;color:#aaa;margin-top:8px;">Check your phone and enter your PIN</p>
+      </div>
+      <div class="error-msg" id="payment-error"></div>
+      <button class="btn-primary" id="cancel-btn" style="background:#eee;color:#555;">Cancel</button>
+    </div>
+
+    <!-- SCREEN 3: Code entry (reconnect) -->
+    <div id="screen-code" class="screen">
+      <div class="input-group">
+        <label for="code-input">Enter your WiFi code</label>
+        <input type="text" id="code-input" placeholder="XXXX-XXXX" maxlength="9" style="text-transform:uppercase;letter-spacing:2px;">
+      </div>
+      <div class="error-msg" id="code-error"></div>
+      <button class="btn-primary" id="code-submit-btn">Connect</button>
+      <span class="link-btn" id="show-plans">Buy a new plan instead</span>
+    </div>
+
+    <!-- SCREEN 4: Connected! -->
+    <div id="screen-success" class="screen">
+      <div class="success-icon">✅</div>
+      <h2 style="text-align:center;color:#1a1a2e;margin-bottom:8px;">Connected!</h2>
+      <div class="code-box">
+        <div class="code-label">Your WiFi Code (save this to reconnect)</div>
+        <div class="code-value" id="success-code">—</div>
+      </div>
+      <div id="success-meta"></div>
+    </div>
+  </div>
+
+  <script>
+    window.PORTAL = <%- JSON.stringify(portal).replace(/<\/script>/gi, '<\\/script>') %>;
+  </script>
+  <script src="/engine.js"></script>
+</body>
+</html>

src/views/screens/portal.ejs

@@ -0,0 +1,267 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title><%= portal.customize.displayName %> — WiFi</title>
+  <style>
+    :root {
+      --primary: <%= portal.customize.primaryColor %>;
+      --primary-dark: <%= portal.customize.primaryColor %>cc;
+      --bg: <%= portal.customize.bgColor %>;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: var(--bg);
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 16px;
+    }
+    .card {
+      background: #fff;
+      border-radius: 20px;
+      padding: 32px 24px;
+      width: 100%;
+      max-width: 380px;
+      box-shadow: 0 20px 60px rgba(0,0,0,0.4);
+    }
+    .header {
+      text-align: center;
+      margin-bottom: 28px;
+    }
+    .header h1 {
+      font-size: 22px;
+      font-weight: 700;
+      color: #1a1a2e;
+      margin-bottom: 4px;
+    }
+    .header p {
+      color: #666;
+      font-size: 14px;
+    }
+    .wifi-icon {
+      font-size: 40px;
+      margin-bottom: 12px;
+    }
+    /* Screens */
+    .screen { display: none; }
+    .screen.active { display: block; }
+    /* Plans */
+    .plan-btn {
+      display: block;
+      width: 100%;
+      padding: 14px 16px;
+      margin-bottom: 10px;
+      background: #f8f9ff;
+      border: 2px solid #e8ecff;
+      border-radius: 12px;
+      cursor: pointer;
+      text-align: left;
+      transition: all 0.2s;
+      position: relative;
+    }
+    .plan-btn:hover, .plan-btn.selected {
+      border-color: var(--primary);
+      background: #eef0ff;
+    }
+    .plan-btn .plan-name { font-weight: 600; color: #1a1a2e; font-size: 15px; }
+    .plan-btn .plan-price { float: right; font-weight: 700; color: var(--primary); font-size: 16px; }
+    .plan-btn .plan-speed { font-size: 12px; color: #888; margin-top: 2px; }
+    /* Phone input */
+    .input-group { margin-top: 16px; }
+    .input-group label { font-size: 13px; color: #555; margin-bottom: 6px; display: block; }
+    .input-group input {
+      width: 100%;
+      padding: 12px 14px;
+      border: 2px solid #e0e0e0;
+      border-radius: 10px;
+      font-size: 16px;
+      outline: none;
+      transition: border-color 0.2s;
+    }
+    .input-group input:focus { border-color: var(--primary); }
+    /* Primary button */
+    .btn-primary {
+      display: block;
+      width: 100%;
+      padding: 15px;
+      margin-top: 16px;
+      background: var(--primary);
+      color: #fff;
+      border: none;
+      border-radius: 12px;
+      font-size: 16px;
+      font-weight: 600;
+      cursor: pointer;
+      transition: filter 0.2s;
+    }
+    .btn-primary:hover { filter: brightness(0.88); }
+    .btn-primary:disabled { background: #aaa; cursor: not-allowed; }
+    /* Secondary link */
+    .link-btn {
+      display: block;
+      text-align: center;
+      margin-top: 14px;
+      color: var(--primary);
+      font-size: 14px;
+      cursor: pointer;
+      text-decoration: underline;
+    }
+    /* Spinner */
+    .spinner {
+      text-align: center;
+      padding: 20px 0;
+    }
+    .spinner-ring {
+      width: 48px; height: 48px;
+      border: 4px solid #e8ecff;
+      border-top-color: var(--primary);
+      border-radius: 50%;
+      animation: spin 0.8s linear infinite;
+      margin: 0 auto 12px;
+    }
+    @keyframes spin { to { transform: rotate(360deg); } }
+    .spinner p { color: #555; font-size: 14px; }
+    /* Success */
+    .success-icon { font-size: 56px; text-align: center; margin-bottom: 12px; }
+    .code-box {
+      background: #f8f9ff;
+      border: 2px solid var(--primary);
+      border-radius: 12px;
+      padding: 16px;
+      text-align: center;
+      margin: 16px 0;
+    }
+    .code-box .code-label { font-size: 12px; color: #888; margin-bottom: 4px; }
+    .code-box .code-value {
+      font-size: 28px;
+      font-weight: 700;
+      color: #1a1a2e;
+      letter-spacing: 3px;
+      font-family: monospace;
+    }
+    .meta-row {
+      display: flex;
+      justify-content: space-between;
+      font-size: 13px;
+      color: #555;
+      padding: 6px 0;
+      border-bottom: 1px solid #f0f0f0;
+    }
+    .meta-row:last-child { border-bottom: none; }
+    .meta-row strong { color: #1a1a2e; }
+    /* Error */
+    .error-msg {
+      background: #fff0f0;
+      border: 1px solid #ffcccc;
+      color: #cc0000;
+      border-radius: 8px;
+      padding: 10px 14px;
+      font-size: 13px;
+      margin-top: 12px;
+      display: none;
+    }
+    .error-msg.show { display: block; }
+    .divider { text-align: center; color: #bbb; font-size: 13px; margin: 16px 0; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="header">
+      <% if (portal.customize.logoUrl) { %>
+        <img src="<%= portal.customize.logoUrl %>" alt="<%= portal.customize.displayName %>" style="max-height:64px;max-width:180px;object-fit:contain;margin-bottom:10px;">
+      <% } else { %>
+        <svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="var(--primary)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="margin-bottom:12px">
+          <path d="M5 12.55a11 11 0 0 1 14.08 0"/>
+          <path d="M1.42 9a16 16 0 0 1 21.16 0"/>
+          <path d="M8.53 16.11a6 6 0 0 1 6.95 0"/>
+          <circle cx="12" cy="20" r="1" fill="var(--primary)" stroke="none"/>
+        </svg>
+      <% } %>
+      <h1><%= portal.customize.displayName %></h1>
+      <p><%= portal.customize.welcomeText %></p>
+    </div>
+
+    <!-- SCREEN 1: Plan selection & phone -->
+    <div id="screen-select" class="screen active">
+      <% if (portal.plans.length === 0) { %>
+        <p style="text-align:center;color:#888;padding:20px 0;">No WiFi plans available yet.<br>Check back soon.</p>
+      <% } else { %>
+        <% portal.plans.forEach(function(plan) {
+          const unit = plan.down_unit === 2 ? 'Mbps' : 'Kbps';
+          const speed = plan.down_limit + unit + ' ↓ / ' + plan.up_limit + unit + ' ↑';
+          const hours = Math.floor(plan.duration_seconds / 3600);
+          const days  = Math.floor(plan.duration_seconds / 86400);
+          const dur   = days >= 1 ? days + (days === 1 ? ' Day' : ' Days') : hours + (hours === 1 ? ' Hour' : ' Hours');
+        %>
+          <button class="plan-btn" data-plan-id="<%= plan.id %>" data-plan-price="<%= plan.price %>">
+            <span class="plan-name"><%= plan.name %></span>
+            <span class="plan-price"><%= parseInt(plan.price).toLocaleString() %> TZS</span>
+            <div class="plan-speed"><%= dur %> &bull; <%= speed %></div>
+          </button>
+        <% }); %>
+
+        <div class="input-group">
+          <label for="phone-input">Your M-Pesa / Mobile Money Phone Number</label>
+          <input type="tel" id="phone-input" placeholder="0712 345 678" inputmode="numeric">
+        </div>
+
+        <div class="error-msg" id="select-error"></div>
+        <button class="btn-primary" id="pay-btn" disabled>Select a plan to continue</button>
+
+        <div class="divider">or</div>
+        <span class="link-btn" id="show-code-entry">Have a code? Enter it here</span>
+      <% } %>
+    </div>
+
+    <!-- SCREEN 2: Waiting for payment -->
+    <div id="screen-waiting" class="screen">
+      <div class="spinner">
+        <div class="spinner-ring"></div>
+        <p>Waiting for M-Pesa payment...</p>
+        <p style="font-size:12px;color:#aaa;margin-top:8px;">Check your phone and enter your PIN</p>
+      </div>
+      <div class="error-msg" id="payment-error"></div>
+      <button class="btn-primary" id="cancel-btn" style="background:#eee;color:#555;">Cancel</button>
+    </div>
+
+    <!-- SCREEN 3: Code entry (reconnect) -->
+    <div id="screen-code" class="screen">
+      <div class="input-group">
+        <label for="code-input">Enter your WiFi code</label>
+        <input type="text" id="code-input" placeholder="XXXX-XXXX" maxlength="9" style="text-transform:uppercase;letter-spacing:2px;">
+      </div>
+      <div class="error-msg" id="code-error"></div>
+      <button class="btn-primary" id="code-submit-btn">Connect</button>
+      <span class="link-btn" id="show-plans">Buy a new plan instead</span>
+    </div>
+
+    <!-- SCREEN 4: Connected! -->
+    <div id="screen-success" class="screen">
+      <svg xmlns="http://www.w3.org/2000/svg" width="56" height="56" viewBox="0 0 24 24" fill="none" stroke="#22c55e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:block;margin:0 auto 12px">
+        <circle cx="12" cy="12" r="10"/>
+        <polyline points="9 12 11 14 15 10"/>
+      </svg>
+      <h2 style="text-align:center;color:#1a1a2e;margin-bottom:8px;">Connected!</h2>
+      <div class="code-box">
+        <div class="code-label">Your WiFi Code (save this to reconnect)</div>
+        <div class="code-value" id="success-code">—</div>
+      </div>
+      <div id="success-meta"></div>
+    </div>
+    <% if (portal.customize.supportPhone) { %>
+      <p style="text-align:center;font-size:12px;color:#aaa;margin-top:20px;">
+        Need help? Call <a href="tel:<%= portal.customize.supportPhone %>" style="color:var(--primary);text-decoration:none;"><%= portal.customize.supportPhone %></a>
+      </p>
+    <% } %>
+  </div>
+
+  <script>
+    window.PORTAL = <%- JSON.stringify(portal).replace(/<\/script>/gi, '<\\/script>') %>;
+  </script>
+  <script src="/engine.js"></script>
+</body>
+</html>

src/views/screens/reconnected.ejs

@@ -0,0 +1,82 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title><%= businessName %> — Reconnected</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
+      min-height: 100vh;
+      display: flex; align-items: center; justify-content: center;
+      padding: 16px;
+    }
+    .card {
+      background: #fff;
+      border-radius: 20px;
+      padding: 40px 24px;
+      width: 100%; max-width: 380px;
+      text-align: center;
+      box-shadow: 0 20px 60px rgba(0,0,0,0.4);
+    }
+    .icon { font-size: 56px; margin-bottom: 12px; }
+    h1 { font-size: 22px; font-weight: 700; color: #1a1a2e; margin-bottom: 6px; }
+    .subtitle { color: #666; font-size: 14px; margin-bottom: 24px; }
+    .code-box {
+      background: #f8f9ff;
+      border: 2px solid #4361ee;
+      border-radius: 12px;
+      padding: 16px;
+      margin-bottom: 20px;
+    }
+    .code-label { font-size: 12px; color: #888; margin-bottom: 4px; }
+    .code-value {
+      font-size: 28px;
+      font-weight: 700;
+      color: #1a1a2e;
+      letter-spacing: 3px;
+      font-family: monospace;
+    }
+    .meta-row {
+      display: flex;
+      justify-content: space-between;
+      font-size: 13px;
+      color: #555;
+      padding: 7px 0;
+      border-bottom: 1px solid #f0f0f0;
+    }
+    .meta-row:last-child { border-bottom: none; }
+    .meta-row strong { color: #1a1a2e; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <svg xmlns="http://www.w3.org/2000/svg" width="56" height="56" viewBox="0 0 24 24" fill="none" stroke="#22c55e" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:block;margin:0 auto 12px">
+      <circle cx="12" cy="12" r="10"/>
+      <polyline points="9 12 11 14 15 10"/>
+    </svg>
+    <h1>Welcome back!</h1>
+    <p class="subtitle"><%= businessName %> — You're connected</p>
+
+    <div class="code-box">
+      <div class="code-label">Your WiFi Code</div>
+      <div class="code-value"><%= code %></div>
+    </div>
+
+    <div class="meta-row">
+      <span>Speed</span>
+      <strong><%= speedDown %> ↓ / <%= speedUp %> ↑</strong>
+    </div>
+    <div class="meta-row">
+      <span>Time remaining</span>
+      <strong><%= expiresIn >= 3600 ? Math.ceil(expiresIn / 3600) + 'h' : Math.ceil(expiresIn / 60) + 'min' %></strong>
+    </div>
+    <div class="meta-row">
+      <span>Reconnect?</span>
+      <strong>Enter code above on login page</strong>
+    </div>
+  </div>
+</body>
+</html>

src/views/screens/suspended.ejs

@@ -0,0 +1,54 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Subscription Required</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+      min-height: 100vh;
+      display: flex; align-items: center; justify-content: center;
+      padding: 16px;
+    }
+    .card {
+      background: #fff;
+      border-radius: 20px;
+      padding: 40px 24px;
+      width: 100%; max-width: 360px;
+      text-align: center;
+    }
+    .icon { font-size: 56px; margin-bottom: 16px; }
+    h1 { font-size: 20px; color: #1a1a2e; margin-bottom: 10px; }
+    .business { font-size: 15px; font-weight: 600; color: #0492eb; margin-bottom: 16px; }
+    p { color: #666; font-size: 14px; line-height: 1.6; }
+    .divider { border: none; border-top: 1px solid #eee; margin: 20px 0; }
+    .notice {
+      background: #fff8e1;
+      border: 1px solid #ffe082;
+      border-radius: 10px;
+      padding: 12px 16px;
+      font-size: 13px;
+      color: #7a6000;
+      line-height: 1.5;
+    }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <svg xmlns="http://www.w3.org/2000/svg" width="56" height="56" viewBox="0 0 24 24" fill="none" stroke="#f59e0b" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:block;margin:0 auto 16px">
+      <rect x="3" y="11" width="18" height="11" rx="2" ry="2"/>
+      <path d="M7 11V7a5 5 0 0 1 10 0v4"/>
+    </svg>
+    <div class="business"><%= businessName %></div>
+    <h1>Subscription Required</h1>
+    <p>WiFi service at this location is temporarily unavailable.</p>
+    <hr class="divider">
+    <div class="notice">
+      If you are the owner of this hotspot, please renew your subscription to restore WiFi service for your customers.
+    </div>
+  </div>
+</body>
+</html>

src/views/suspended.ejs

@@ -0,0 +1,51 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Subscription Required</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+      min-height: 100vh;
+      display: flex; align-items: center; justify-content: center;
+      padding: 16px;
+    }
+    .card {
+      background: #fff;
+      border-radius: 20px;
+      padding: 40px 24px;
+      width: 100%; max-width: 360px;
+      text-align: center;
+    }
+    .icon { font-size: 56px; margin-bottom: 16px; }
+    h1 { font-size: 20px; color: #1a1a2e; margin-bottom: 10px; }
+    .business { font-size: 15px; font-weight: 600; color: #0492eb; margin-bottom: 16px; }
+    p { color: #666; font-size: 14px; line-height: 1.6; }
+    .divider { border: none; border-top: 1px solid #eee; margin: 20px 0; }
+    .notice {
+      background: #fff8e1;
+      border: 1px solid #ffe082;
+      border-radius: 10px;
+      padding: 12px 16px;
+      font-size: 13px;
+      color: #7a6000;
+      line-height: 1.5;
+    }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="icon">🔒</div>
+    <div class="business"><%= businessName %></div>
+    <h1>Subscription Required</h1>
+    <p>WiFi service at this location is temporarily unavailable.</p>
+    <hr class="divider">
+    <div class="notice">
+      If you are the owner of this hotspot, please renew your subscription to restore WiFi service for your customers.
+    </div>
+  </div>
+</body>
+</html>