Nested Loop Africa — Platform Documentation

Overview

Nested Loop Africa is an Energy-as-a-Service (EaaS) operations platform for managing distributed solar and battery micro-grids across multiple African sites. It provides energy operators with real-time visibility and control over network health, household energy consumption, billing, device telemetry, maintenance scheduling, and carbon credit accounting.

The platform is designed for use by grid operators, field supervisors, and finance teams. It is not a customer-facing product — it is an internal infrastructure management tool.

Core Capabilities

• Multi-site solar/battery micro-grid monitoring across 12+ African deployments
• Household-level energy consumption and billing management
• Device telemetry tracking for inverters, batteries, gateways, and solar controllers
• Predictive load and generation forecasting (AI-assisted)
• Carbon displacement accounting and carbon credit pipeline tracking
• Maintenance scheduling and technician dispatch management
• Network-wide alerting and escalation workflows

Navigation Structure

The app uses a fixed left sidebar with 7 primary sections. A top bar shows real-time network uptime, active alert count, and last telemetry sync time.

Dashboard — Network Operations Centre

The main landing page. Provides a full-network summary at a glance for operators. All figures are network-wide aggregates across all sites.

KPI Cards (Row 1 — Energy)

• Total Sites — count of all deployed sites in the network
• Homes Connected — total household connections across the fleet
• Generated Today — total kWh of solar energy produced today, with day-on-day trend
• Consumed Today — total household kWh consumed today with utilisation %

KPI Cards (Row 2 — Financial & Carbon)

• Revenue Today / Month — USD revenue collected; outstanding balance highlighted in amber
• CO₂ Avoided Today — tonnes of carbon displacement, trees equivalent
• Network Uptime — rolling 30-day uptime % across all gateways

Charts

• Network Energy (14 days) — stacked area chart of solar generation vs consumption. X-axis = date, Y-axis = kWh.
• Energy Sources donut — today's generation mix: Solar / Battery / Grid / Generator as percentages.

Bottom Panels

• Network Status — breakdown of sites by health state (healthy / warning / fault / offline) with a preview of active alerts. Clicking an alert navigates to /alerts.
• Network Capacity — shows sites near capacity (>90%) and sites with spare capacity. Bar charts per site show % household fill rate.
• Data Health — telemetry completeness %, sites missing data count, last sync timestamp.
• Event Timeline — chronological log of significant system events for the day (alerts triggered, payments received, health checks).
• Carbon Impact Snapshot — lifetime CO₂ avoided, trees equivalent, carbon credits generated and available. Links to full Carbon page.

Sites Map

A full-screen interactive Leaflet map rendered on a dark CartoDB tile layer showing all site locations across Africa.

Map Markers

• Each site is represented by a colour-coded circle marker — green = healthy, amber = warning, red = fault, grey = offline
• Marker radius scales with the number of homes connected (larger site = larger circle)
• Clicking a marker opens a popup with: site name, health badge, location, homes, solar capacity, battery, uptime, and a "View Site Detail" button

Site Grid (below map)

A card grid lists all sites with quick stats. Clicking any card navigates to the site detail page.

Sites

A card grid listing all sites with their key specs and health status. Suitable for a quick fleet-level review.

Each card shows: site name, location, health badge, solar capacity (kW), battery storage (kWh), homes connected, capacity utilisation bar, uptime %, and last sync time.

Clicking a card navigates to the Site Detail page at /sites/:id.

Site Detail Page

• Header — site name, health badge, location, install date, last sync. Time range selector (7d / 30d) switches chart data.
• Solar vs Consumption chart — area chart of daily generation vs demand over the selected period
• Battery & Grid chart — bar chart showing daily battery discharge and grid import kWh
• 7-Day Forecast — combined bar/line chart showing AI-predicted solar generation and load forecast. Confidence interval is computed per-day.
• Capacity Utilisation — progress bars for household fill %, solar utilisation %, battery utilisation %
• Financial summary — tariff per kWh, lifetime revenue, outstanding balance
• Device Telemetry — per-device status cards showing model, firmware version, last seen timestamp, and temperature (where available). Devices: inverter, battery, gateway.
• Remote Actions panel — placeholder buttons for Restart Inverter, Restart Gateway, Run Diagnostics, Check Firmware. Currently disabled — requires device pairing firmware (v3.0+).
• Households table — households assigned to this site with monthly kWh, balance, and payment status

Households

Master list of all household connections across all sites. Supports filtering by payment status and site.

Summary Row

Four stat cards showing total households, paid count, due-soon count, and overdue count with total outstanding dollar amount.

Table

Columns: Household ID (monospaced, clickable), Customer Name, Site, Monthly kWh, Avg Daily kWh, Current Balance, Payment Status badge.

Filters available: All / Paid / Due Soon / Overdue, and a site dropdown. Clicking any row navigates to /households/:id.

Household Detail Page

• Header — customer name, household ID, payment status badge, site link
• Stats — monthly kWh, daily average, current balance (green if zero, amber if outstanding), monthly energy cost in USD
• Daily Consumption chart — 30-day area chart of daily kWh (derived from site-level data divided by household count)
• Peak Usage Pattern — bar chart showing typical intraday load profile by hour (hardcoded illustrative data — replace with PAYG meter data)
• Billing History table — monthly billed, paid, balance, and status per billing cycle
• Metrics section — energy source mix, monthly carbon footprint estimate, connection info (site, tariff, plan)

Carbon Impact

Carbon displacement tracking for internal reporting and carbon market participation. Includes device-level data for third-party audit trails.

Key Metrics

• CO₂ Avoided Today / Lifetime (in tonnes)
• Trees Equivalent (lifetime CO₂ / avg tree absorption rate)
• Carbon Credits Generated (total units)

Carbon Credit Pipeline

Three-card display showing the pipeline from Generated → Verified → Available for Sale with a fill bar showing the verification ratio.

Charts

• CO₂ Avoided (30 days) — area chart of daily CO₂ displacement in tonnes
• Energy Source Displacement — stacked bar chart: Solar + Battery + Grid Displaced kWh per day

Per-Site Carbon Table

Rows per site showing estimated monthly solar kWh, grid displaced kWh, CO₂ avoided (tonnes), and carbon credits accrued. Currently calculated from capacity data — replace with actual metered data.

Audit Trail Table

Device-level generation records (site, device ID, timestamp, solar kWh, generator displaced, grid displaced, battery throughput, CO₂ kg, verified status). This is the data structure for MRV (Monitoring, Reporting, Verification) submission to carbon registries.

Alerts

Network-wide alert management. Displays all unresolved alerts with severity classification, root-cause messages, and suggested remediation actions.

Alert Types

• offline — site or device has lost communication entirely
• battery_fault — BMS fault code detected, cell imbalance, thermal runaway risk
• low_generation — solar output significantly below irradiance forecast (soiling, shading, MPPT fault)
• communication_failure — gateway intermittent, data packets dropping
• overload — site consumption approaching or exceeding design capacity
• maintenance_due — scheduled maintenance overdue or approaching

Severity Levels

• critical — immediate action required; potential service disruption or equipment damage
• warning — degraded performance; action required within hours/days
• info — informational; no immediate risk

Alert Cards

Each card shows: site name, severity badge, alert type, time detected, full message, suggested action (highlighted in blue), and buttons to "View Site" (navigates to site detail) or "Mark Resolved".

Maintenance

Scheduled and in-progress maintenance tracking for field teams. Covers inverter servicing, battery checks, panel cleaning, site inspections, firmware updates, and cable checks.

Task States

• scheduled — upcoming, within tolerance
• in_progress — technician currently on-site
• overdue — past scheduled date without completion
• completed — signed off

Priority Levels

Low / Medium / High / Critical — displayed in escalating colour from grey to red. Critical tasks typically correlate with active fault alerts.

Task Cards

Show maintenance type, site, status badge, priority, scheduled date, assigned technician, and notes. Overdue and critical tasks have a highlighted red border. "Mark Complete" button is a UI placeholder pending backend write support.

Schedule Overview

A timeline list at the bottom shows all upcoming scheduled tasks in date order with assigned technician for planning and dispatch coordination.

Data Model

The platform uses 7 Base44 entities. All have built-in id, created_date, updated_date, created_by fields.

Firmware Integration Guide

To replace mock data with live telemetry, field devices must push data to the platform's backend. Below are the integration requirements per device class.

Gateway (NL-GW-200 or compatible)

The gateway is the primary data aggregator at each site. It should periodically POST telemetry bundles to the platform's ingest API.

// Minimum telemetry payload — POST every 15 minutes
{
  "site_id": "site-01",
  "timestamp": "2026-03-14T14:00:00Z",
  "solar_kwh": 12.4,
  "battery_discharge_kwh": 2.1,
  "battery_charge_kwh": 0.0,
  "grid_import_kwh": 0.0,
  "generator_kwh": 0.0,
  "total_consumption_kwh": 14.5,
  "battery_soc_percent": 78.4,
  "devices": [
    {
      "device_type": "inverter",
      "serial_number": "SE50K-001",
      "status": "healthy",
      "temperature_c": 42.1,
      "firmware_version": "v1.4.2"
    }
  ]
}

Inverter Telemetry

• AC output power (W), DC input voltage (V), MPPT channel voltages
• Operating temperature (°C) — critical for fault detection (threshold: >65°C = warning, >80°C = fault)
• Fault codes — map manufacturer fault codes to platform alert types (battery_fault, device_fault)
• Firmware version string — used to detect update candidates

Battery BMS

• State of Charge % (SoC) — used for battery_soc_percent field
• Cell voltages array — imbalance detection threshold: >50mV delta = warning alert
• Pack temperature (°C) — threshold: >45°C = warning, >55°C = fault
• Charge / discharge kWh counters
• BMS fault register — bitmask map to battery_fault alert

Smart Meter (per Household)

• Cumulative kWh consumed — diff per interval to compute energy_consumed_kwh
• PAYG credit balance — maps to billing_balance on the Household entity
• Relay state (on/off) — enables remote disconnection for overdue accounts
• Meter serial maps to household_id

Remote Actions (requires firmware v3.0+)

The Remote Actions panel on Site Detail is currently disabled. To activate it, gateways must implement an MQTT command channel or polling endpoint:

// Platform publishes command to gateway MQTT topic
Topic: nl/sites/{site_id}/commands
Payload:
{
  "command": "restart_inverter" | "restart_gateway" | "run_diagnostics" | "check_firmware",
  "issued_by": "operator@nestedloop.io",
  "issued_at": "2026-03-14T14:32:00Z",
  "nonce": "a1b2c3d4"
}

// Gateway ACKs back to:
Topic: nl/sites/{site_id}/ack
Payload: { "nonce": "a1b2c3d4", "status": "accepted" | "failed", "message": "..." }

Backend Additions Required

The following backend functions need to be built in Base44 to make the platform fully operational. All functions are Deno-based HTTP handlers.

1. Telemetry Ingest Function — ingestTelemetry

Receives POST from field gateways, validates site API key, writes to EnergyData and Device entities, and triggers alert evaluation.

// Input payload: see Firmware section above
// Actions:
// 1. Verify X-Site-Api-Key header against stored secret
// 2. Upsert EnergyData record for the interval
// 3. Update Device records (status, temperature, firmware_version, last_seen)
// 4. Evaluate alert rules (see alertEvaluator function below)
// 5. Update Site.last_sync and Site.system_health

2. Alert Evaluator — evaluateAlerts

Runs on each telemetry ingest. Checks thresholds and creates or resolves Alert records.

// Rule examples:
// - If Site.last_sync > 30 min ago AND !alert(offline) → create offline alert
// - If Device.temperature_c > 65 → create device_fault alert (warning)
// - If Device.temperature_c > 80 → create device_fault alert (critical)
// - If BMS cell delta > 50mV → create battery_fault alert
// - If EnergyData.solar_kwh < forecast * 0.65 → create low_generation alert
// - If Site.homes_connected / max_homes_capacity > 0.90 → create overload alert
// On resolution: set Alert.resolved = true, Alert.resolved_at = now()

3. Billing Engine — processBilling

Scheduled daily. Reads EnergyData per household, calculates cost at site tariff rate, updates Household.billing_balance, and sets payment_status.

// Schedule: daily at 00:01 UTC
// For each Household:
//   1. Sum EnergyData.total_consumption_kwh for the day (divided by homes_connected)
//      — OR — read from smart meter if available
//   2. cost = kwh * Site.tariff_per_kwh
//   3. Household.billing_balance += cost
//   4. If billing_balance > 0 and within 7 days of cycle end → payment_status = "due_soon"
//   5. If billing_balance > 0 and past cycle end → payment_status = "overdue"
//   6. Update Site.outstanding_balance (sum of household balances)

4. Carbon Accounting — recordCarbonData

Runs after each telemetry ingest. Converts energy data to carbon displacement figures using regional grid emission factors.

// Emission factors (kgCO₂ per kWh) by country:
const EMISSION_FACTORS = {
  Nigeria: 0.431,
  Kenya: 0.512,
  Ghana: 0.374,
  Tanzania: 0.486,
  Uganda: 0.459,
  Senegal: 0.621,
};

// co2_avoided_kg = (solar_kwh + generator_displaced_kwh) * emission_factor
// carbon_credits_generated = co2_avoided_kg / 1000  (1 credit = 1 tonne CO₂)
// Write to CarbonData entity. Mark verified = false initially.

5. Forecast Engine — generateForecast

Scheduled daily. Uses historical EnergyData + weather API to generate 7-day solar generation and load forecasts per site. Writes results to a new Forecast entity (to be created).

// Recommended approach:
// 1. Fetch Open-Meteo or Solcast solar irradiance forecast for site lat/lng
// 2. Apply site-specific yield model (kWh = irradiance * panel_area * efficiency)
// 3. Load forecast = rolling 7-day average consumption + growth trend
// 4. Call base44.integrations.Core.InvokeLLM with historical data
//    to refine load prediction with seasonal and event patterns
// 5. Write forecast records to Forecast entity

6. Notification Dispatcher — sendAlertNotification

Entity automation triggered on Alert create. Sends email/SMS to the responsible site operator and/or field technician.

// Trigger: Alert entity → create event
// Actions:
// 1. Look up site operator contact from User entity (by role = 'site_operator')
// 2. For critical severity → send email immediately
//    await base44.integrations.Core.SendEmail({
//      to: operator.email,
//      subject: `[CRITICAL] ${alert.site_name}: ${alert.alert_type}`,
//      body: `${alert.message}\n\nSuggested: ${alert.suggested_action}`
//    })
// 3. For warning → batch into daily digest (scheduled function)
// 4. Auto-create Maintenance task for battery_fault / offline alerts

7. Site API Key Management — provisionSiteKey

Admin-only function. Called at site commissioning to generate and store a secure API key for the gateway to use when posting telemetry.

// Admin only (check user.role === 'admin')
// 1. Generate cryptographically random 32-byte key
// 2. Store as a secret: SITE_API_KEY_{SITE_ID}
// 3. Return key to admin once (never store in plain text in DB)
// 4. Gateway operator programs key into gateway secure storage at commissioning

8. Scheduled Automations

• processBilling — daily at 00:01 UTC
• generateForecast — daily at 01:00 UTC
• checkMissingTelemetry — every 30 minutes; flag sites with no ingest in last 60 min as offline
• dailyHealthDigest — daily at 07:00 UTC; email summary of network health to all admins

New Entities to Create

• Forecast — site_id, date, solar_forecast_kwh, load_forecast_kwh, confidence_percent, model_version, created_at
• Payment — household_id, amount_usd, method (mobile_money / cash), reference, recorded_at, recorded_by
• SiteOperator — site_id, user_id, role (primary / secondary), phone, notification_preferences
• MeterReading — household_id, meter_serial, cumulative_kwh, soc_kwh, relay_state, timestamp