Files

T

ci / build-test (push) Successful in 1m24s

Details

Meter chain topology + per-energy-type flow (Sankey) pages

Adds a meter hierarchy and a flow view: a downstream meter is a *subsection*
of an upstream one (not an addition), so you can see where a main meter's flow
divides — e.g. official water → garden, pool, other; grid/battery → all → car.

- MeterLink (schema + migration AddMeterLinks): a directed from→to flow edge.
  Multi-parent allowed (a merge, e.g. grid + solar → house); multi-child is a
  split. Cascade-deletes with either endpoint; unique + distinct-endpoint checks.
- FlowService: per energy type + period, builds a Sankey graph — nodes = meters
  sized by consumption; link value = downstream meter's consumption, split
  proportionally across multiple upstreams; unaccounted remainder under a meter
  becomes a synthetic "Other" node; depth via topological longest-path.
- SankeyChart.razor: hand-rolled inline-SVG Sankey (ApexCharts has no Sankey
  type) — columns by depth, nodes stacked by value, bezier ribbons sized by flow,
  left→right, theme-aware, HTML-encoded labels, tooltips. Built as a MarkupString
  to sidestep Razor's <text> element clash.
- /energy/{id} page (one per energy type): KPIs (consumption + cost), the flow
  Sankey, and the meter list. NavMenu now lists a link per energy type
  (Electricity, Water, Gas, …) loaded from the DB.
- Meters admin: cycle-safe "Sub-meter of (upstream meters)" multi-select
  (descendants excluded to prevent cycles); reconciles meter_link rows on save.
- Reference data seeds a demo chain (Haus → Auto) so electricity flow shows
  Haus dividing into Auto + Other.

Tests: FlowServiceTests (single-parent remainder; two-parent proportional
split); render test now asserts the flow chain + covers /energy/{id}. 69 Core +
47 Integration = 116 green. Live-verified: Haus 95,450 kWh → Auto 51,909 +
Other 43,541 (flow conserved), all 5 energy-type pages render.

Claude-Session: https://claude.ai/code/session_01Lz2RqAsnQhetqWNoCDfexK

2026-07-14 14:02:16 +02:00

5.1 KiB

Raw Blame History

MeterVault

A self-hosted, local-first energy & utility metering platform. MeterVault pulls meter data from Home Assistant, Tasmota and raw MQTT on a schedule, stores every reading timestamped and immutable, normalizes it into consumption, and turns it into cost dashboards. Energy types (electricity, water, heating oil, gas, district heat, …) and meters are user-defined — nothing is hardcoded.

Successor to a hand-maintained Energiebilanz spreadsheet. See docs/SDD.md for the full design.

Features

Automatic ingestion from MQTT/Tasmota (persistent subscriptions) and Home Assistant (REST poll or push), plus manual entry, a REST push API, and CSV import.
Immutable raw readings on a TimescaleDB hypertable; a normalized, append-only consumption layer on top — reproducible, auditable.
Seven measurement modes (cumulative/generation registers, burner runtime, tank/consumable, direct delta, instant rate, virtual). Handles meter swaps, counter resets, tank dip-sticks with calibration, and virtual meters defined by an expression (PV self-consumption, savings, net).
Tariff engine with time-ranged price history (unit/base/feed-in), scoped global / per type / per meter; cost categories decoupled from energy types; meterless manual costs.
Continuous aggregates (daily/monthly/yearly, local timezone) so dashboards never scan raw.
Dashboard: cost KPIs with period-over-period deltas, "what costs most", a "what cost more/ less" difference view, trends, a PV/Solar panel (generation, self-consumption, autarky %, savings), an oil/consumable panel (tank gauge, deliveries, burner runtime, effective L/h, forecast-to-empty) and a per-meter detail view (raw readings, consumption, sources, tariff timeline, events), one-click reference-data load, CSV dry-run.
Per-energy-type flow pages (Electricity, Water, …): a Sankey diagram of the meter chain — a downstream meter is a subsection of an upstream one (main → car, pool, garden, …), arrow thickness ∝ amount, with an auto-computed "Other/unmetered" remainder. Meters can have several upstreams (a merge, e.g. grid + solar → house).
Admin UI: full create/edit/delete for energy types, meters (with consumption recompute on mode/baseline change, and cycle-safe upstream-meter wiring), ingest sources, tariffs, cost categories, and MQTT/Home-Assistant connectors; a "Test connection" for Home Assistant; effective-settings view.
REST API + OpenAPI/Swagger, API-key auth, reverse-proxy trust (Authelia/Traefik).
JSON config export/import for portability; Docker Compose + multi-arch image.

Quick start (Docker)

docker compose -f deploy/docker-compose.yml up -d
# open http://localhost:8080  → Import → "Load reference data" for a populated demo
# ...or start pre-populated:  METERVAULT_SEED=true docker compose -f deploy/docker-compose.yml up -d
# API docs at http://localhost:8080/swagger

Configuration is via environment variables (Section__Key double-underscore mapping), e.g.:

Variable	Purpose
`ConnectionStrings__Default`	PostgreSQL/Timescale connection string
`MeterVault__TimeZone`	Local timezone for buckets/display (default `Europe/Berlin`)
`MeterVault__ApiKeys__0`	An API key accepted on the `X-Api-Key` header
`MeterVault__AllowAnonymousApi`	`true` to open the REST API without a key (trusted LAN only)
`MeterVault__ReverseProxyTrust`	`true` to honour `X-Forwarded-User` behind an auth proxy
`MeterVault__EnableLiveIngestion`	`false` to disable the MQTT/HA workers
`MeterVault__SeedReferenceData`	`true` to load the bundled demo dataset on first start (idempotent)

The REST API is closed by default: with no ApiKeys configured and AllowAnonymousApi off, it returns 401. Set at least one API key (or open it explicitly for a trusted network).

Secrets (broker/HA tokens) are never stored in the database — endpoint configs hold the name of an environment variable, resolved at runtime.

Pushing readings (Home Assistant)

curl -X POST http://localhost:8080/api/v1/readings \
  -H "X-Api-Key: $METERVAULT_API_KEY" -H "Content-Type: application/json" \
  -d '[{"meterId": 1, "time": "2026-01-01T12:00:00Z", "value": 47200}]'

See docs/wiring.md for wiring up Tasmota, MQTT and Home Assistant.

Development

dotnet build
dotnet test                       # integration tests spin a TimescaleDB via Testcontainers (needs Docker)
dotnet test tests/Core.Tests      # fast unit tests, no Docker
dotnet run --project src/App

Architecture, project layout and conventions live in CLAUDE.md.

Releasing

Edit the VERSION file on master; Gitea Actions tags vX.Y.Z and builds/pushes a multi-arch image to the Gitea container registry (.gitea/workflows/). Locally: pwsh deploy/build-and-push.ps1 -Registry git.finalfactory.de -Image finalfactory/metervault -Push. Requires a Docker-capable act_runner; the image build itself is self-contained.

License

Not yet chosen (see SDD §14). Add a LICENSE before the first public tag.

5.1 KiB Raw Blame History