Seismograph

A web application for monitoring, analysing and understanding earthquakes.

Research and hobby use only. No advertising, no subscriptions, no accounts, and no running cost.

What it does

• A real Earth. Sentinel-2 imagery streamed down to street level, 3D terrain, city lights on the night side, and a camera that moves like Google Earth. Every earthquake from the live USGS catalogue sits on it; x-ray mode drops each one to its true depth beneath the surface, and subducting slabs and focal mechanisms can be drawn in.
• Time is the primary axis, not a filter. One scrubber drives the whole view, and every state is a shareable URL that restores exactly.
• Event pages built on the full USGS product tree: every agency's solution with its uncertainties, moment tensor, ShakeMap, felt reports, PAGER exposure and ground failure. Each page opens with the earthquake explained in plain words, and takes questions about it.
• Photographs of notable earthquakes, from Wikimedia Commons, each credited to its photographer under its own licence.
• Sequences. Aftershocks gathered and analysed: b-values with their confidence intervals, Omori-Utsu decay with Ogata's residual test, completeness through time, and two declustering methods side by side so their disagreement shows.
• Aftershock forecasts for the whole world. Where USGS publishes one, it is shown and recomputed from USGS's own inputs; elsewhere the same model runs with USGS's generic parameters for the region.
• A public scoreboard. Every forecast is written to a hash-chained ledger before its window opens and scored after it closes, against the region's long-term rate. The misses are shown too. A GitHub Actions runner issues forecasts hourly and scores them daily.
• Waves you can watch and hear. Seismic phases cross the globe at iasp91 speeds while real recordings from stations worldwide play, as sound, on the same clock.
• Comparison with 32 well-studied sequences at the same elapsed time, and what followed in each.
• Depth cross-sections through the nearest subducting slab.
• Export as CSV, TSV, JSON, GeoJSON, QuakeML, KML/KMZ, XLSX or Parquet; every chart as SVG or PNG; an ObsPy snippet for the same query; and a keyless public API at /api/v1.
• Watchlists kept only in your browser, with no alerts: a quiet digest of what was recorded in the places you care about, set against what is usual there.

Photographs on the 2024 Noto earthquake's page	The 2019 Ridgecrest sequence, analysed
Waves from Ridgecrest crossing the planet	The aftershock forecast, recomputed from USGS's inputs
The scoreboard, which says so when the model does not beat the baseline

Plain-language explanations

Event, sequence and comparison pages open with a few paragraphs saying what happened in plain words, and take questions about it. The text is always written first from a fixed template, from the numbers on the page, and appears at once; with no language-model key configured, that is the whole feature.

With a key, a language model may rewrite the template into more natural prose. The rewrite replaces the template only if a verifier passes it. The verifier checks that:

• every number appears in the page's own evidence;
• every name appears in it too;
• no direction is changed;
• no construction implies a prediction.

A failed rewrite is retried once, then the template stays. Questions about prediction or personal safety are answered by a fixed reply before any model is asked.

• Providers, tried in order: OpenRouter's free models (NVIDIA Nemotron), then Google Gemini's free tier, then Anthropic, which is paid and used only if its key is set.
• Cost and privacy. Only public earthquake statistics are ever sent. Verified rewrites are cached by the hash of their evidence, and a spend guard caps model calls per hour.
• Speed. Free endpoints are slow and often busy, so a rewrite can take a minute or two. The page shows the template meanwhile.

Each page marks which it is showing: the template, or a verified rewrite.

What it does not do

It makes no forward-looking claim of any kind. Deterministic earthquake prediction is not scientifically possible, and no part of this application implies otherwise. Aftershock forecasts are probabilities from published statistical models (Reasenberg-Jones, Omori-Utsu), shown on pages you choose to open and never as an alert. An end-to-end test asserts that the globe and event pages contain no forward-looking language.

Running it

npm install
npm run dev

No credentials are needed. Every data source is public and keyless. Language-model keys for the plain-language rewrites are optional; put them in .env.local, using .env.example as the guide.

Or run the published container image:

docker run -p 3000:3000 ghcr.io/novicecoder10/seismograph
# with language-model keys:
docker run -p 3000:3000 --env-file .env.local ghcr.io/novicecoder10/seismograph

The image's scoreboard is a snapshot of the ledger at release; the live ledger is in this repository.

npm test               # unit and component tests
npm run e2e            # browser tests (Playwright starts a dev server)
npm run typecheck      # tsc --noEmit, strict
npm run build
npm run ledger:issue   # issue forecasts for new M5+ earthquakes
npm run ledger:score   # score forecasts whose windows have closed
npm run ledger:verify  # check the ledger's hash chain

Data sources and licences

Source	Use	Licence
USGS earthquake services	Catalogue, event products, aftershock forecasts	Public domain
EMSC	Normalization support	CC BY 4.0
EarthScope and Raspberry Shake	Waveforms	Per each network's terms
Global CMT	Focal mechanisms	Free to use, with citation
Slab2	Subduction surfaces	Public domain
Sentinel-2 cloudless by EOX	Globe imagery	CC BY-NC-SA 4.0
Terrain Tiles on AWS	3D terrain	Open data
NASA GIBS	Blue Marble, Black Marble	Public domain
OpenStreetMap via EOX and Nominatim	Labels, place search	ODbL
Wikidata and Wikimedia Commons	Photographs of notable earthquakes	CC0 (Wikidata); each photograph under its own licence, credited where shown

Full details, including how each file in public/data was built, are in public/data/SOURCES.md. The photographs in docs/screenshots/event-photos.jpg belong to the photographers credited beneath them, under the licences named there.

Architecture

Every read of the catalogue goes through lib/repositories/, so no component knows where events come from. lib/science/ holds every statistic as a pure function over plain data, each tested against published values; the aftershock forecasts reproduce USGS's published numbers to within 0.2% in the unit suite. The forecast ledger is two append-only, SHA-256-chained JSON Lines files in ledger/, committed to this repository.

Licence

The code is MIT-licensed; see LICENSE. Data, imagery and photographs keep their own licences, listed above.

Documents

• docs/design.md — the design, and what each phase built and found.
• docs/research-findings.md — the evidence behind it.
• spikes/FINDINGS.md — what the Phase 0 spike week measured. Two of its findings are load-bearing: the globe never renders continuously, and seisplotjs never reaches the server.