Shared calculation engine
EV, electricity-bill, appliance and solar tools all use the same location record and the same base energy-cost operation: energy use in kWh × the active $/kWh rate. Each tool has only one job before that shared step: convert its user inputs into energy use (or annual solar value). Utility tariffs stay typed separately from statewide EIA averages, so fixed charges and TOU caveats are not silently flattened into one number.
Electricity prices
State residential prices come from EIA Electric Power Monthly Table 5.6.A, based on Form EIA-861M. July 2026 values are preliminary. EIA derives average prices from retail sales revenues and volumes; this is a useful state-level proxy, not a utility quote.
Calculator defaults
Defaults are assumptions, not hidden facts. EV efficiency and charging loss, appliance wattage/runtime, solar production and project cost are exposed to the user and can be changed.
Solar incentives
Default federal residential solar credit is $0 for new 2026 expenditures. IRS guidance states the Residential Clean Energy Credit is not available for expenditures made after December 31, 2025.
Brand assets
CalcuRiver does not use AI-redrawn or fake vehicle logos. Official manufacturer sources are recorded in the brand registry. Logo binaries are not bundled until their usage/redistribution terms are reviewed.
State data quality checks
The v0.4.2 build validates all 50 states plus Washington, D.C. for unique state identity, required price fields, cents-to-dollar conversion, year-over-year math, U.S.-average comparison math, rank uniqueness, state-page coverage and EV model × state coverage. The machine-readable result is stored in /data/state-audit.json.
Result UX standard
All four core calculators use the same result explanation order: calculation, active rate source, U.S.-average comparison, and estimate boundary. On mobile, location and the result are prioritized before advanced inputs. Utility rates remain separate from statewide averages and can be selected only when a verified marginal period is encoded.
Central source and freshness registry
CalcuRiver maintains one machine-readable registry for the datasets that can materially change a calculator result. Each family records its source type, effective date when known, last-checked date, freshness threshold, update priority and a controlled data status: verified, modeled, partial, guarded or stale.
An effective date and a source-check date are different facts. Missing dates are not invented. Modeled inputs remain labeled as models rather than being promoted to verified local prices. A critical dataset that ages beyond its configured threshold can pause affected calculated outputs instead of silently using an unverified value. Staleness alone does not automatically noindex a useful page; index guards are reserved for pages whose primary answer becomes unsupported or materially misleading.
The registry is stored in /data/data-freshness-registry.json and is validated during the release QA process.
Tariff versioning and freshness
Every utility profile carries a stable plan ID, immutable rate-version ID, controlled lifecycle status, source trail, tariff effective-date fields and a separate last-verified date. Status is a controlled enum: active, future, expired, incomplete or review_required; explanatory prose belongs in status_note. An unknown effective date is stored as unknown rather than inferred from an undated consumer page.
When a tariff changes, CalcuRiver's data contract is to close the prior version with an effective_to date and append a new snapshot. Historical versions remain in data/tariff-rate-versions.json. effective_from/effective_to describe tariff validity; last_verified only records when CalcuRiver checked the source and is never substituted for an effective date. Freshness therefore does not by itself guarantee legal tariff validity.
Utility-specific rate layer
Starting with v0.3.1, CalcuRiver stores utility tariffs separately from EIA state averages. Time-of-use pages preserve each utility’s own seasons, clock periods, displayed precision, eligibility rules and fixed-charge caveats. A variable-energy example never silently allocates a monthly fixed charge to a single EV charge or appliance run.
CalcuRiver tracks 56 utility profiles in the v0.6.12 core coverage layer: 52 are calculator-ready and 4 remain guarded or profile-only. Only plans with sufficiently verified numerical marginal rates are calculator-ready; guarded utilities remain visible as source/reference records without being flattened into a fake calculator rate. Each profile links to the official plan page and tariff or regulator record used for verification.
EV Catalog v0.4 calculation
For vehicles with combined MPGe, CalcuRiver converts MPGe to vehicle energy use using 33.7 kWh per gasoline-gallon equivalent. EPA MPGe is treated as wall-energy consumption because EPA states MPGe includes charging losses; no extra default loss is added. For battery/range-derived references, wall-energy cost applies the selected loss percentage. Where the selected manufacturer source provides usable battery capacity and EPA-estimated range but no MPGe, CalcuRiver labels a reference efficiency calculated from usable battery divided by range rather than presenting it as an official EPA consumption figure.
Every catalog model is generated for all 50 states and Washington, D.C. The state default is the July 2026 EIA residential average. Utility-specific tariffs remain a distinct layer and are only shown when separately encoded from official utility/regulatory sources.
TOU schedule resolution
For supported utility plans, CalcuRiver first resolves the versioned tariff schedule by season, weekday/weekend or plan-specific holiday treatment, and local clock window. There is no global U.S. holiday fallback; a holiday affects pricing only when the selected plan explicitly encodes it. In v0.5.3, EV charging can also be expressed as a recurring local-time window such as 23:00–07:00. The engine splits each selected session across all applicable TOU periods, including midnight crossings, and calculates a duration-weighted energy rate for the chosen calendar month and day pattern. The weighting assumes constant charging power while plugged in and distributes monthly charging energy across real elapsed minutes in the utility timezone. Spring-forward clock minutes that do not exist are not silently shifted; repeated fall-back clock minutes are counted once per real occurrence. If any selected minute falls outside the verified tariff version or schedule coverage, the profile fails closed rather than guessing.
Tariff Engine v2.1
CalcuRiver resolves a local calculation through utility → rate plan → eligibility metadata → immutable rate version → season/day/plan-specific holiday → TOU period or other energy-pricing model → energy charge. energy_charge is the primary energy contract and carries a controlled pricing_model of flat, TOU or tiered. Fixed charge, minimum charge, demand charge and adjustment remain separate components and are never silently folded into one all-in kWh price.
Component state is explicit: modeled, unsupported, not_applicable or unknown. A zero-dollar line is used only when the modeled rule actually produces zero; unknown data is not converted into $0. EV, appliance and solar tools stay in marginal_energy mode, while the electricity-bill tool uses the separate bill_estimate mode. Tier architecture exists but is user-facing disabled until verified tier plans and required monthly-usage context are regression-tested.
Rate-plan selection is eligibility-aware. EV-specific plans are hidden from unrelated calculators, and known meter/enrollment/service-territory requirements are retained as structured metadata. Unknown requirements are shown as confirmation needs rather than assumed satisfied. Every calculation emits a machine-readable trace containing the plan, version, schedule resolution, kWh, component statuses and applied amounts; the UI shows a short summary with the full trace available in a collapsed debug view.
U.S. EV archive vs. calculator data
The historical catalog and the charging engine are deliberately separate data layers.
Solar utility modeling
See how CalcuRiver separates import tariffs, self-consumption value and export compensation.