Energy Disruption Monitor — Western Russia, Siberia & Belarus

An open-source-only dashboard tracking publicly reported degradation of energy infrastructure across Belarus, western Russia and the Siberian Federal District, aggregated to administrative region (80 monitored units, Crimea included), from 2022 to the present.

Every number traces to a public source. Where the data does not support a number, the dashboard says so rather than estimating one. Observed facts, external estimates and modelled assumptions are kept visibly distinct throughout.

Crimea is shown as a separately identified occupied unit — internationally recognised as Ukraine, under Russian occupation, distinct styling and status. Since iteration 4 it contributes to the headline Monitored-Area index (through the sectors where it has qualifying events and a compatible denominator) while never being labelled a Russian region. Surrounding countries and the Black Sea are drawn as display-only context.

Status: iterations 1–12 shipped. For every live figure — as-of date, headline index, sector exposures, coverage ratio, event and recovery counts — see docs/CURRENT_STATE.md, which is regenerated by the build and checked by a test. This README deliberately quotes none of them: it used to, and the numbers here went two iterations stale while the claim "this README quotes no live number" sat a few lines below them.

The newest write-up is the highest-numbered docs/ITERATION_N_REVIEW.md; a test fails the build if the pointers in this file, CLAUDE.md and docs/HANDOFF.md fall behind it.

Live site: https://russian-energy-dashboard.vercel.app · Deployment: static Vite + MapLibre on Vercel, rebuilt daily by a GitHub Action; push-to-main auto-deploys. Zero external runtime requests. See docs/DEPLOYMENT.md. Run locally: .venv\Scripts\python.exe -m pipeline.run then cd web && ..\scripts\npm.cmd run dev.

---

What it is, precisely

The headline figure is the Energy System Disruption Exposure Index (ESDI). It answers one question:

What share of the tracked installed base sits at facilities disrupted recently enough to still be plausibly impaired, weighted by evidence strength, cause, and time elapsed?

It is not a measurement of lost throughput or lost generation. Open reporting almost never states how much capacity a given event removed. Of the 175 region-assigned events currently in the dataset, zero carry a quantified capacity effect — and the dashboard shows that ratio in its top ribbon rather than burying it. An exposure measure is what this data can honestly support; a "capacity offline" figure is not.

Scope boundary

This is a damage-assessment and monitoring tool. It models publicly reported disruption to energy infrastructure, aggregated to administrative region. It contains no current unit positions, no readiness state, no vulnerability or defensive-gap assessment, and no ranking of undamaged assets.

One upstream source (the Wikipedia strike table) publishes a "distance from Ukrainian-controlled territory" column for each facility. The parser deliberately does not read it. It describes reach rather than damage, contributes nothing to a degradation assessment, and is the one field in that table with obvious operational-planning value. tests/test_pipeline.py fails the build if any range-to-target field ever appears in emitted data.

---

Architecture

data/curated/*.csv ──┐
Natural Earth ───────┤
WRI Power Plant DB ──┼──► pipeline/ (Python 3.13, stdlib only) ──► data/processed/*.json
OpenStreetMap ───────┤                                                      │
Wikipedia ───────────┘                                                      │
                                                                web/public/data/ (mirrored)
                                                                            │
                                                    web/ (Vite + React + TS + MapLibre)
                                                                            │
                                                                    Vercel (static)

Three deliberate choices:

No database. The dataset is ~1,980 assets (plus a curated infrastructure supplement) and ~175 events. Static JSON regenerated by a scheduled job is the backend. A Postgres instance here would be infrastructure to maintain in exchange for nothing.

No basemap. The map renders our own GeoJSON on a flat dark ground. Every tile provider worth using needs an API key, a billing relationship, or an attribution banner, and streets and terrain add nothing underneath an administrative choropleth. The deployed page therefore makes zero external network requests and works offline.

Stdlib-only ETL. No pandas, geopandas, shapely or requests. Point-in-polygon, Douglas–Peucker simplification and Wikitext parsing are each a few dozen readable lines. The GitHub Action needs no build toolchain and cannot break on a wheel that stops publishing for Python 3.13.

---

Setup

Requires Python 3.13 and Node 24. Node is vendored under tools/node/ (gitignored) and reached through scripts/node.cmd / scripts/npm.cmd, so nothing touches PATH.

python -m venv .venv
.venv\Scripts\python.exe -m pip install pytest

Build the dataset — this downloads from Natural Earth, WRI, Overpass and Wikipedia, and caches everything under data/raw/ (gitignored):

.venv\Scripts\python.exe -m pipeline.run

Run the dashboard:

cd web && ..\scripts\npm.cmd install && ..\scripts\npm.cmd run dev

Run the tests:

.venv\Scripts\python.exe -m pytest

---

Data flow

Stage	Location	Committed?
Raw downloads	data/raw/	No — large, regenerable, third-party licensed
Analyst-curated events	data/curated/incidents.csv	Yes — this is source truth
Scoring parameters	methodology/scoring.json	Yes
Processed output	data/processed/	Yes — so Vercel can serve it without running Python
Frontend copy	web/public/data/	Yes — mirrored by the pipeline

data/processed/ is a build artifact that is nonetheless committed, because Vercel builds only the frontend. A clean rebuild is deterministic given the same upstream sources. Never hand-edit processed JSON; fix the curated source and rebuild.

---

Sources

Layer	Source	Licence
Administrative boundaries	Natural Earth 10m admin-1	Public domain
Generation (MW, fuel, location)	WRI Global Power Plant Database v1.3	CC BY 4.0
Substations, transmission, pipelines	OpenStreetMap via Overpass	ODbL
Strike events, refinery capacities	English Wikipedia	CC BY-SA 4.0
Everything else	data/curated/incidents.csv	Per-row source URLs

Full detail and per-source caveats: docs/SOURCES.md.

---

Recovery / reconstitution (iteration 1)

Repair is no longer a flat half-life. Each disrupted facility's decay is driven by the strongest available evidence, and the kind travels with every number:

• Observed — a source reported how long restoration actually took (green, solid).
• Estimated — a source gave a reconstitution window (amber, half-filled).
• Modelled — neither exists; a generic per-sector assumption is used (muted, dashed).

Confirmed reconstitution collapses a facility's contribution. Recovery evidence lives in data/curated/recovery.csv (source required per row). The dashboard's Recovery tab shows unresolved counts, median observed restoration (with sample size), impairment age, and the observed/estimated/modelled mix.

The four analytic concepts — exposure, assessed degradation (quantified only), recovery, and confidence/coverage — are kept structurally distinct in the data and across the seven-tab analytical panel (Overview · Rankings · Recent · Recovery · Effects · Repair burden · Sources).

---

Documentation

• docs/CURRENT_STATE.md — every live figure, regenerated by the build. Point here; never re-quote these numbers elsewhere
• docs/HANDOFF.md — durable state between sessions: what shipped, what was deferred, and the non-obvious things
• docs/ITERATION_12_REVIEW.md — refresh-outage post-mortem, publication-freshness safeguard, time-bomb audit, deep-link hardening
• docs/ITERATION_11_REVIEW.md — Evidence Inspector, Build Change Ledger, Data Quality, date A/B comparison, Recovery Lifecycle, Briefing Mode & PNG export
• docs/ITERATION_10_REVIEW.md — GEM ingestion, pipeline registry, network quality
• docs/ITERATION_9_REVIEW.md — relation-based pipeline reconstruction
• docs/ITERATION_8_REVIEW.md — "What changed" tab, contrast audit
• docs/ITERATION_7_REVIEW.md — damage severity, transmission red-team
• docs/ITERATION_6_REVIEW.md — coverage-universe correction
• docs/ITERATION_5_REVIEW.md — analytic/context scope model, network context + rivers, gas/coal depth, data contract

---

Known limits, stated up front

• Coverage is an oil-strike benchmark ≈47%. Iteration 6 corrected a universe mismatch: the old "~57%" divided all energy events by an oil-only 305-strike benchmark. It is now oil-sector strikes ÷ 305. Non-oil sectors get honest descriptive states, never a fabricated %.
• Observed recovery spans refining, oil logistics and gas processing. Iteration 6 demoted the pooled cross-class median to "mixed-infrastructure evidence" and shows a per-class median only at ≥3 episodes within a class; the headline is the national episode count.

Live counts (coverage %, episodes, ESDI, tests) are generated into docs/CURRENT_STATE.md every build and drift-guarded by a test — this README quotes no live number.

• Siberian event coverage is n=1 (Omsk). The region is fully populated structurally but has barely been struck yet.
• Refining and oil logistics dominate. They are the sectors with structured open data. Electric power is split into generation (capacity basis, ≈0 — barely struck) and transmission (an event-burden proxy, never "% offline"). Gas and coal are now inventoried (LNG, gas-processing, coal mines and terminals) but stay uncovered in the composite — incompatible units are never summed, and an inventory is not disruption; their weights are redistributed rather than counted as zero.
• Modelled reconstitution horizons are assumptions, not measurements — the single weakest input where no evidence exists. All live in methodology/scoring.json.
• Four of the nine requested regional effect categories are not modelled and are displayed as such, with reasons, rather than filled with plausible numbers.

These are expanded in docs/ITERATION_1_REVIEW.md.