Nested Loop Estate — Product Requirements Document

Overview & Goals

Nested Loop Estate is an Energy-as-a-Service (EaaS) operations platform that gives portfolio managers, executives, finance teams, and field engineers real-time visibility and control over distributed solar and battery micro-grids across residential properties.

The purpose of this document is to define the functional and non-functional requirements for the platform, and to specify the requirements for a new capability: onboarding physical energy devices through the Amps AI unified device connectivity API, replacing today's mocked device data with live, vendor-agnostic device connections.

In Scope

• Portfolio monitoring (Overview, Insights, Properties, Opportunities)
• Financial tracking (Revenue, Financial, ROI reporting)
• Resident/household billing and consumption (Residents)
• Fault and maintenance tracking (Issues)
• Carbon accounting (Carbon)
• A new device onboarding flow backed by Amps AI

Out of Scope

• Tenant-facing mobile app (this is an internal operator tool)
• Direct billing/payment collection (handled by third-party PAYG providers)

Objectives & Success Metrics

• Reduce device integration time — new OEM device types onboarded in days, not months, by using one unified API instead of bespoke vendor integrations.
• Increase telemetry completeness — target 98%+ of connected devices reporting live data, up from today's mocked baseline.
• Reduce mean-time-to-detect faults — real-time webhook-driven alerts instead of periodic polling.
• Self-serve onboarding — a field engineer can connect a new device on-site in under 5 minutes with no engineering support.

Roles & Personas

• Executive / Owner — needs portfolio-level financial and health rollups; not involved in device onboarding.
• Portfolio Manager — oversees property performance and opportunities; may initiate device onboarding for a new property.
• Finance — needs accurate consumption and billing data; depends on device data quality.
• Field Engineer — primary user of the device onboarding flow; physically present at the property connecting new hardware.

Functional Requirements

Overview & Insights

• Network-wide KPIs (revenue, generation, consumption, uptime) must load in under 2 seconds
• Revenue and savings stats must drill down to a per-property breakdown on click

Properties & Opportunities

• Each property must show live device health status once Amps AI is connected
• Opportunities engine must flag properties with under-utilised or missing storage/solar capacity

Financial & Revenue

• ROI table must show investment, monthly revenue, utilisation, and payback period per property
• Homes-connected count must be visible alongside financial figures for context

Residents

• Household-level consumption, balance, and payment status must be filterable by site and status

Issues & Maintenance

• Single tabbed view combining active fault alerts and scheduled maintenance tasks
• Critical faults must be resolvable from the same screen where they are raised

Carbon

• CO₂ avoided and carbon credit pipeline must reconcile with metered generation data

Non-Functional Requirements

• Reliability — device connection status must be accurate within 60 seconds of a real-world change
• Security — all device API credentials stored as backend secrets, never exposed to the frontend
• Auditability — every device connect/disconnect event logged with timestamp and initiating user
• Responsiveness — all screens usable on mobile for field engineers onboarding devices on-site

Page-by-Page Breakdown

Build-ready spec for every page. Each entry lists the route, purpose, entities used, key UI elements, and acceptance criteria a developer can implement and test against directly.

Amps AI Device Onboarding Integration

Amps AI is a unified API platform for Distributed Energy Resources (DERs). It replaces one-off vendor integrations with a single REST contract covering batteries, solar inverters, EV chargers, HVAC systems, and vehicles — directly matching the device types already tracked on the Device entity.

Why Amps AI

• One integration covers every OEM device type instead of a bespoke gateway protocol per manufacturer
• Hosted "Link UI" handles OEM authentication, so the platform never stores end-user OEM credentials
• Sandbox environment allows full onboarding-flow testing with simulated devices before going live
• Webhooks push real-time connection and telemetry events, removing the need for constant polling

New Page: Device Onboarding

A new page, accessible from a property's detail view and from Settings, lets a field engineer connect a device to a site.

• Device list — shows all devices for the selected site with connection status: connected, pending, disconnected
• "Connect New Device" button — requests a Link token from the backend, then opens the Amps AI Link UI (hosted flow) for the user to authenticate with the device's OEM
• Sandbox/Live toggle — visible to admins only, controls which Amps AI environment new connections are created against
• Per-device sync status — last successful data pull timestamp and any connection errors surfaced inline

Onboarding Flow

1. 1Field engineer selects a site and clicks Connect New Device
2. 2Backend function requests a short-lived Link token from Amps AI, scoped to that site
3. 3Frontend opens the Amps AI Link UI with the token; user authenticates with the device OEM
4. 4Amps AI sends a webhook to the platform confirming the device connection
5. 5Backend stores the returned amps_device_id on the Device record and marks it connected
6. 6A scheduled sync pulls current device state (charge level, output, status) into EnergyData/Device records

Backend Functions Required

• createAmpsLinkToken — calls Amps AI to generate a Link token for a given site; returns it to the frontend to launch the Link UI
• handleAmpsWebhook — receives connection-status and device-event webhooks from Amps AI; updates the Device entity
• syncAmpsDeviceState — scheduled function that pulls current state for all connected devices via the unified API and writes to EnergyData/Device

// Example: createAmpsLinkToken request
POST https://api.amps.ai/v1/link-tokens
Headers: { "Authorization": "Bearer {AMPS_AI_API_KEY}" }
Body: { "end_user_id": "site-01", "environment": "sandbox" }

// Example: incoming webhook on device connection
POST /handleAmpsWebhook
{
  "event": "device.connected",
  "end_user_id": "site-01",
  "device_id": "amps_dev_8f2a...",
  "device_type": "battery",
  "oem": "generic-bms"
}

Data Model Additions

The existing Device entity needs the following additional fields to support Amps AI connections:

• amps_device_id — the device identifier returned by Amps AI once connected
• amps_connection_status — connected / pending / disconnected
• amps_environment — sandbox / live
• last_synced_at — timestamp of the last successful data pull from Amps AI

Rollout Plan

• Phase 1 — Build the Device Onboarding page and sandbox connection flow; validate with one pilot property
• Phase 2 — Implement webhook handling and scheduled sync; replace mocked Device data for the pilot property
• Phase 3 — Roll out to all properties; switch sandbox to live per site after field verification
• Phase 4 — Deprecate legacy mock telemetry generation once all sites report live data