Municipal Utility Billing & Rate Structure Automation
A practitioner-focused knowledge base for building deterministic, audit-grade billing systems in Python.
🌐 Read it live → www.utilitybilling.org
UtilityBilling.org is a deep, practitioner-first reference for the engineers and finance teams who keep public utility revenue accurate, defensible, and auditable. Municipal water, wastewater, and electric billing is not ordinary CRUD — it is a compliance-critical data-engineering discipline where a single mis-rated interval can cascade into a rate dispute, a Public Utility Commission (PUC) finding, or a failed audit.
Every guide on the site treats billing that way: deterministic rate evaluation, validated meter telemetry, and ledger-ready output that survives a PUC audit. The material is grounded in production patterns — decimal.Decimal money math, timezone-aware zoneinfo interval handling, Pydantic v2 boundary validation, idempotent processing, and hash-chained audit trails — with runnable Python 3.11+ throughout.
- Utility billing managers & municipal finance teams who need to understand how automation protects revenue and compliance.
- Public-sector developers modernizing legacy billing systems off manual imports and brittle integrations.
- Python automation builders looking for correct, edge-case-aware reference implementations for metering and rating.
The site is organized into four in-depth areas, each broken down into focused topics and runnable deep-dives:
| Area | What you'll find |
|---|---|
| Billing Architecture & Rate Taxonomy | System boundaries, customer-class and service-tier mapping, step- vs block-rate design, assistance-program eligibility, data governance, and fallback routing for missing rate data. |
| Meter Data Ingestion & Validation | AMI/AMR feed synchronization, schema validation, reading-anomaly detection, time-series interval modeling, async batch processing, and resilient retry workflows. |
| Automated Rate Calculation & Rule Engines | Seasonal calendar logic, surcharge and fee application, proration and billing-period math, and demand-charge & ratchet calculation. |
| Billing Reconciliation & Audit Logging | Double-entry journal manifests, hash-total validation controls, ERP general-ledger posting, and GASB-grade append-only audit trails. |
Every article pairs the why (the billing failure mode it prevents) with the how (annotated, production-quality Python), plus hand-authored diagrams, edge-case inventories, verification snippets, and FAQs.
- Correctness first.
Decimalfor every monetary and metered quantity,zoneinfofor every timestamp, and explicit handling of the cases that break naive pipelines — register rollover, DST boundaries, retroactive PUC orders, duplicate deliveries, and missing reads. - Audit-grade by design. Immutable, effective-date-versioned schedules; idempotency keys; and hash-chained, append-only audit logs aligned with GASB reporting and NIST SP 800-53 controls.
- Genuinely deep. 50+ interlinked pages, each engineered to a consistent blueprint with structured-data markup and original technical diagrams.
- Eleventy (11ty) static site generator
- Hand-authored, theme-aware inline SVG diagrams
- JSON-LD structured data (Article, BreadcrumbList, HowTo, FAQPage) on every page
- Progressive Web App (offline-capable), fast on mobile, and WCAG 2 AA accessible
- Deployed on Cloudflare
npm install
npm run serve # local dev server with live reload
npm run build # static output to _site/Content lives in content/; the build maps each content/<path>/index.md to the clean URL /<path>/.
📖 www.utilitybilling.org — start with the architecture of an auditable billing platform, move through resilient meter-data ingestion, into the rule engines that turn policy into ledger transactions, and finish with reconciliation and audit logging.
© UtilityBilling.org — automating municipal utility billing & rate structures with Python.