Home

ngrid-dashboard — Contributor Wiki

A self-hosted dashboard that scrapes your National Grid account and charts your usage, costs (supply vs delivery), effective rates, and weather-normalized usage. This wiki is for contributors; for running the app, see the README.

Read this first — the three golden rules

1. The bill PDF is the source of truth, not the API. Several API fields are plausible but wrong for analysis (details in Data Accuracy). Any change that touches a number must keep the cross-validation green and be backed by hand-calculated tests.
2. Number logic lives in pure, tested functions. Parsing and math go in parsePdf.ts / series.ts / prediction.ts so they can be unit-tested without a browser or DB. Don't bury arithmetic in a React component or an API route.
3. Be a good guest. The scraper hits a third party using a real account. Reuse the session, rate-limit, and never add aggressive polling. Personal use only.

Pages

Core

• Architecture — components, data flow, modules, and the data model.
• Development Setup — run it locally, env vars, hitting the DB, debugging a scrape.
• How the Scraper Works — B2C login, the "intercept-and-widen" technique, endpoints, PDFs.
• Data Accuracy — the requirements that matter most: why we trust PDFs, and what every numeric change must satisfy.
• Testing — hand-calculated unit tests + the real-data cross-validation.
• Contributing — workflow, PR checklist, coding conventions, security & etiquette.
• Releases and CI — image tags, the release-driven publish flow, versioning, CI gates.

Features

• Accounts and Login — encrypted credential store, multi-account, interactive MFA/OTP, lifecycle.
• Notifications — new-bill webhook / ntfy / SMTP, off by default, exactly-once.
• Weather and Degree-Days — Open-Meteo history, HDD/CDD, weather-normalized usage.
• Backups and Migration-Safety — pre-upgrade pg_dump + the CI migration-safety gate.
• Range and Customization — the one range pref, visual picker, paginated/customizable charts.

What this project is (and isn't)

• Is: a single-account, self-hostable dashboard. Region/company are auto-detected, so it works for any National Grid US region with no code changes.
• Isn't: a multi-tenant SaaS. There is no app-level login by design — it's meant to sit on a LAN or behind a reverse proxy/SSO. Don't add a public auth layer or expose it to the internet.