PowerGuard

Consumer

Original Idea

Local Power Outage Monitor A background service that detects power outages via smart home APIs and notifies you immediately with estimated restoration times.

Product Requirements Document: PowerGuard

1. Executive Summary

PowerGuard is a high-reliability background monitoring service designed to provide property owners with immediate awareness of power disruptions. By integrating with leading smart home ecosystems (Samsung SmartThings, Home Assistant) and utility provider data, PowerGuard detects "silent" failures where devices simply vanish from the network. The app delivers real-time notifications, including Estimated Time of Restoration (ETR), enabling users to protect frozen pipes, food supplies, and sensitive equipment through informed, timely action.

2. Problem Statement

Property owners often discover power outages hours or days after they occur, particularly at vacation homes, rental properties, or businesses during off-hours. This lack of immediate awareness leads to preventable losses:

  • Property Damage: Frozen pipes bursting in winter.
  • Financial Loss: Food spoilage in refrigerators and freezers.
  • Security Risks: Offline cameras and alarm systems.
  • Health Hazards: Failure of medical equipment or climate control for the elderly.

3. Goals & Success Metrics

  • Latency: Detect and notify users within < 120 seconds of a heartbeat failure.
  • Accuracy: Achieve >98% true-positive rate for confirmed outages via utility cross-referencing.
  • Retention: 85% of users remain active after the first "Success Story" notification.
  • Uptime: 99.99% availability for the monitoring engine using multi-region failover.

4. User Personas

  • The Second-Home Owner (Mark): Lives 3 hours away from his cabin. Needs to know if he must drive up to drain pipes or check the freezer.
  • The Small Business Owner (Sarah): Runs a small cafe. Needs to know if the refrigerators are down overnight to save $5,000 in inventory.
  • The Elderly Caregiver (James): Monitors his parents' home to ensure their oxygen concentrator and HVAC are powered.

5. User Stories

  • As a user, I want to link my SmartThings hub so that the app can monitor my home's connectivity.
  • As a user, I want to receive a "Critical Alert" that bypasses my "Do Not Disturb" settings for confirmed outages.
  • As a user, I want to see a Live Activity on my lock screen showing the countdown to power restoration.
  • As a user, I want a log of historical outages to provide to my insurance company for a food loss claim.

6. Functional Requirements

6.1 Device Integration

  • OAuth2 Connection: Support for Samsung SmartThings and Home Assistant Cloud (Nabu Casa).
  • Heartbeat Monitoring: Use of SmartThings healthCheck capability and Home Assistant availability entities.
  • Auto-Detection: Automatically identify "Always-On" devices (Hubs, Bridges) to act as power monitors.

6.2 Monitoring Engine

  • Absence-of-Signal Logic: Trigger alert when a "Dead Man's Switch" timer expires (e.g., 5 minutes of no pings).
  • Utility Cross-Referencing: Scrape local utility maps (ArcGIS/KUBRA) to confirm if the outage is local to the grid or specific to the house.

6.3 Notifications

  • Multi-Channel Alerts: Push notifications, SMS (Twilio), and automated voice calls for high-priority events.
  • Live Status: Persistent lock-screen updates (iOS Live Activities / Android 16 Live Updates).

6.4 Dashboard

  • Multi-Property View: Single map/list view showing status of all monitored locations.
  • ETR Display: Real-time display of restoration times scraped from utility providers.

7. Technical Requirements

7.1 Tech Stack

  • Mobile: React Native 0.83.x (Mandatory New Architecture/Fabric, React 19.2 Integration).
  • Backend: Node.js with NestJS v11.1.12 (Express v5 support, JSON logging).
  • Database: PostgreSQL 18 with TimescaleDB 2.24.0 (Hypertable for heartbeat logs, UUIDv7 support).
  • Infrastructure: AWS Lambda + Amazon EventBridge Global Endpoints (Multi-region failover).
  • Data Ingestion: Amazon Kinesis (for "Thundering Herd" buffering during mass outages).

7.2 Integrations

  • Smart Home: Samsung SmartThings Enterprise API (Subscription-based eventing).
  • Notifications: Firebase Cloud Messaging (HTTP v1 API), Amazon SNS.
  • Scraping: ArcGIS REST JS + chrono-node for ETR extraction.

8. Data Model

8.1 User

  • userId: UUIDv7 (Primary Key)
  • email: String
  • notificationPrefs: JSONB (SMS, Push, Voice toggle)

8.2 Property

  • propertyId: UUIDv7
  • ownerId: UUIDv7 (FK)
  • address: String (Encrypted at rest)
  • utilityProviderId: String (Internal ID for scraper)
  • timezone: String (e.g., "America/New_York")

8.3 SmartDevice (Heartbeat Source)

  • deviceId: String (Platform ID)
  • propertyId: UUIDv7 (FK)
  • platform: Enum (SMARTTHINGS, HOME_ASSISTANT)
  • accessToken: Encrypted String (AES-256-GCM)
  • lastHeartbeat: Timestamp (TimescaleDB Hypertable)

8.4 OutageEvent

  • eventId: UUIDv7
  • propertyId: UUIDv7 (FK)
  • startTime: Timestamp
  • endTime: Timestamp (Nullable)
  • etr: Timestamp (Estimated Time of Restoration)

9. API Specification (Selected Endpoints)

  • POST /v1/auth/link-platform
    • Req: { platform: 'smartthings', code: '...' }
    • Res: { status: 'success', devices: [...] }
  • GET /v1/properties/:id/status
    • Res: { status: 'online' | 'offline', lastSeen: 'ISO-8601', etr: 'ISO-8601' | null }
  • POST /v1/webhooks/smartthings
    • Role: Receives real-time healthCheck events from Samsung.

10. UI/UX Requirements

  • Status Indicator: "Traffic Light" system (Green: Online, Red: Outage, Yellow: Fluctuating/Unstable).
  • Setup Wizard: Guided OAuth flow with clear instructions on which devices to select as "monitors."
  • Live Activity: On iOS, show a lightning bolt icon in the Dynamic Island when power is out, expanding to show ETR.
  • Accessibility: High-contrast mode for emergency visibility and screen-reader support for elderly users.

11. Non-Functional Requirements

  • Security: OAuth tokens must be encrypted using AES-256-GCM with keys managed by AWS KMS.
  • Performance: The ingestion layer must handle 100k "Last Gasp" messages per second via Kinesis buffering.
  • Reliability: Use "Dead-Letter Queues" (SQS) for all notification failures.

12. Out of Scope

  • Smart appliance control (e.g., turning on lights).
  • Electrical panel monitoring (requires hardware installation).
  • Solar power generation analytics.

13. Risks & Mitigations

  • Risk: Utility providers blocking scrapers during storms.
    • Mitigation: Use direct ArcGIS REST API queries instead of browser automation; implement proxy rotation via Crawlee.
  • Risk: OS background task killing.
    • Mitigation: Use "Silent Push" (FCM) to wake the app and "Critical Alerts" entitlement for iOS.
  • Risk: "Thundering Herd" of reconnections crashing the DB.
    • Mitigation: Implement Jittered Exponential Backoff on all client-side pings.

14. Implementation Tasks

Phase 1: Project Setup

  • [ ] Initialize NestJS v11.1.12 project with PostgreSQL 18.
  • [ ] Initialize React Native 0.83.x project with New Architecture enabled.
  • [ ] Set up TimescaleDB 2.24.0 hypertable for heartbeats.
  • [ ] Configure AWS KMS for token encryption logic.

Phase 2: Core Monitoring Engine

  • [ ] Implement SmartThings OAuth2 flow & token storage (AES-256-GCM).
  • [ ] Build the "Dead Man's Switch" logic in NestJS using BullMQ for heartbeat timeouts.
  • [ ] Develop ArcGIS scraper module using axios and chrono-node.
  • [ ] Implement Kinesis ingestion for high-volume status events.

Phase 3: Notifications & Real-Time UI

  • [ ] Integrate FCM HTTP v1 API for high-priority push.
  • [ ] Implement iOS 18+ Live Activities (WidgetKit) and Android 16 Live Updates.
  • [ ] Build the Multi-Property Dashboard in React Native.
  • [ ] Create "Critical Alert" bypass logic for high-priority outages.

Phase 4: Reliability & Launch

  • [ ] Set up EventBridge Global Endpoints for multi-region failover.
  • [ ] Conduct load testing simulating 50k concurrent "offline" events.
  • [ ] Perform security audit of OAuth token rotation and data isolation.
  • [ ] Submit for "Critical Alerts" entitlement on Apple Developer Portal.