Utility Customer Domain

Overview#

A severe storm knocks out a substation at 2 a.m. The outage management team needs to know, in seconds, how many customers are affected and whether any life-support equipment users or dialysis centres sit in the affected zone. The Utility Customer domain answers both questions immediately: it links customers to their serving infrastructure, flags critical facility tiers, and surfaces the count and composition of affected accounts so restoration crews can be briefed and dispatched with the right priority sequence from the start.

The domain manages utility customer accounts, customer-submitted outage reports, and estimated time of restoration (ETR) predictions. Customers are linked to utility infrastructure to enable customer impact analysis during outages. Critical facilities and life-support customers receive priority tier assignments. All customer data is stored in PostgreSQL with multi-tenant organisation isolation.

Key Features#

Customer Account Management: Maintain comprehensive customer records including account information, service location, contact details, customer type classification, and service point tracking.
Customer Type Classification: Categorise customers as residential, commercial, industrial, or government to support differentiated service levels and impact analysis.
Critical Facility Flagging: Flag critical facilities and life-support customers with priority tier assignments (1-5) to ensure they receive prioritised attention during outages and service disruptions.
Infrastructure Linking: Connect customer accounts to their serving infrastructure (transformers, feeders, pressure zones) to enable rapid identification of affected customers during infrastructure events.
Customer Impact Analysis: Aggregate affected customer counts by type for specific infrastructure elements, providing instant visibility into the scope and composition of customer impact during outages.
Outage Report Tracking: Accept and track customer-submitted outage reports with status management to capture ground-truth outage information from the customer perspective.
ETR Predictions: Record and track estimated time of restoration predictions with confidence scoring and prediction error tracking to improve forecast accuracy over time.
Smart Meter Integration: Track smart meter enablement status per customer to identify accounts that can provide real-time outage and restoration confirmation.
Customer Search: Search across customer name, account number, and service address for quick account lookup during customer interactions.

Mermaid Diagram#

Use Cases#

Electric Utilities: Quickly determine how many customers and what types are affected by an infrastructure failure for accurate situation reporting and resource prioritisation during storm restoration events.
Water & Gas Utilities: Identify critical facilities and life-support customers in an outage area to guide restoration sequencing decisions and meet regulatory priority restoration obligations.
Customer Operations: Use ETR predictions and outage status information to provide accurate, timely updates to affected customers through automated communication channels.
Infrastructure Planning: Analyse customer distribution and types across infrastructure elements to support capital planning decisions and identify underserved or high-risk service zones.

Integration#

The Utility Customer domain connects with utility operations across the platform:

Utility Infrastructure: Customer accounts link to serving infrastructure assets.
Work Order Management: Customer information provides context for work orders.
Outage Management: Customer outage reports contribute to outage detection.
SLA Tracking: Customer priority tiers influence SLA targets and monitoring.

Open Standards#

GraphQL (June 2018 specification): All customer data queries, impact counts, outage reports, and ETR predictions are exposed through a GraphQL API, enabling typed, self-describing queries and mutations over a single endpoint.
ISO 4217 (Currency Codes): Payment processing uses ISO 4217 three-letter currency codes (USD, JMD, EUR, GBP, CAD, TTD, BBD, XCD) to identify and validate the currency of each utility bill payment transaction.
ISO 8601 (Date and Time): ETR predictions, appointment windows, and all timestamp fields are represented and serialised using ISO 8601 format, ensuring unambiguous date-time interchange across systems.
WGS 84 (EPSG:4326): Customer service locations are stored as decimal latitude and longitude coordinate pairs in the WGS 84 geographic coordinate reference system, enabling spatial queries and infrastructure linkage.
RFC 4122 (UUID): Every customer account, outage report, ETR prediction, and appointment record is assigned a version-4 universally unique identifier (UUID), providing collision-resistant primary keys across multi-tenant data.
HMAC-SHA-256 (RFC 2104 / FIPS 198-1): Payment gateway requests are signed using HMAC-SHA-256 to authenticate message integrity between the platform and third-party payment processors.
JSON Web Token / RS256 (RFC 7519): API access to all customer data endpoints is gated by JWT bearer tokens verified against a JWKS endpoint using RS256, enforcing authenticated and tenant-scoped access control.

Last Reviewed: 2026-02-24 Last Updated: 2026-04-14