Orrery

The orbital mechanics tools NASA uses to reach Mars, rebuilt for anyone who's curious. Real physics, real missions from Sputnik to Artemis II, in 14 languages. Beautiful, educational, self-hostable.

What it is

A browser-based solar system explorer, mission simulator, encyclopedia, and station explorer rolled into one. It uses the same orbital mechanics behind real mission planning — Keplerian orbits, Lambert solvers, porkchop plots, vis-viva, Tsiolkovsky — and presents them in a way that a curious person can understand by doing.

The name comes from a mechanical model of the solar system. That is exactly what Orrery does, at the scale of a screen.

No backend. No database. No personal data. A static SPA you can self-host, install as a PWA, and use offline after first load. The only telemetry on the live site (orrerylearn.com) is self-hosted, aggregate-only usage analytics via Umami plus crash reports — cookieless, no fingerprinting, no PII, no cross-site tracking, and never used to identify you.

Live

https://chipi.github.io/orrery/ — every screen, fully offline-capable after first load.

First-time visitors land on a 30-second orientation page (/) — what Orrery is, how to use it, and a 11-card grid linking to every primary route. Returning users skip past in one click via the nav.

Available in 14 languages, all at 100% UI parity: English · Español · Français · Deutsch · Português (BR) · Italiano · Nederlands · 中文 · 日本語 · 한국어 · हिन्दी · العربية (RTL) · Русский · Српски (Cyrillic). Browser locale is auto-detected on first visit (per ADR-057, locale picks persist via a small functional cookie — no tracking; see Privacy for the full, non-PII client-state list).

Eleven screens

The full nav (left to right): /explore · /plan · /fly · /missions · /earth · /moon · /mars · /iss · /tiangong · /science · /fleet.

Screen	What it shows
Solar System Explorer (/explore)	Real-time 3D / 2D orrery — 8 planets + 5 dwarf planets + 2 comets + ʻOumuamua, with togglable visibility layers and clickable bodies. Detail panels: OVERVIEW · GALLERY · TECHNICAL · SCIENCE. Live physics overlays behind the Science Lens (gravity, velocity, centripetal, apsides + true anomaly, sphere-of-influence rings, hover info cards).
Mission Configurator (/plan)	11,200-cell Lambert porkchop plot per destination — Earth → 9 destinations (Mercury · Venus · Mars · Jupiter · Saturn · Uranus · Neptune · Pluto · Ceres) with LANDING / FLYBY toggle. Mission Sandbox: pin one cell, click another → ΔDEP / ΔTOF / Δ∆v compare. 13 rockets to choose from, real ∆v budget.
Mission Arc (/fly)	Fly a mission — live telemetry, transfer arc as a true Keplerian two-point ellipse with Sun at focus, fuel model, timeline scrubber. Heliocentric missions auto-zoom across DEPARTURE → CRUISE → APPROACH, with the camera close to Earth at launch, pulled back across cruise, then pulled in toward the destination as it arrives. At each flyby and arrival the camera cuts into a multi-camera cinematic montage (#371) — wide establish → chase → hero → pulled-back "catapult" — with the close passage in slow motion so the gravity-assist swing reads. Moon missions auto-switch into a dedicated cislunar view (ADR-058) anchored at Earth — every mission's per-profile trajectory geometry (Apollo free-return figure-8, Artemis II hybrid free-return at 9,200 km periselene, Chandrayaan-3 multi-burn spiral, Chang'e 5 LOR, etc.), with the camera zooming in as Orion / the lander / the orbiter reaches the Moon. Phase markers mark every mission event (launch, TLI, LOI, descent, EDL, arrival, ...) — click any dot to jump the sim to that moment, with a science chip linking to the matching /science chapter. The same overlay works on Mars + outer-system missions (Mariner 4 → Voyager 2 Grand Tour → New Horizons → Hope Probe) via flight.interplanetary_profile waypoints. Flight Director banner narrates 5 physics phases. CAPCOM panel with mission events. Conic-section side panel detects ellipse / parabola / hyperbola live.
Mission Catalog (/missions)	113 historical, planned, and concept missions across Mars + Moon + inner-planet + outer-system probes — every agency, every outcome, replayable. Timeline navigator (1957 → 2035) above the card grid. Per-mission flight params with caveat banners (RECONSTRUCTED / SPARSE / UNKNOWN). Sub-page — a live upcoming-launch calendar (PRD-020) sourced from Launch Library 2 + GCAT with per-row provenance.

Plus four read-only pages: /credits (per-image provenance manifest + text-source attributions), /library (bill-of-links across the entire app — every outbound LEARN link with native-language priority and freshness gating), /posters (27 original art-print posters in three style families — vintage screen-print, modern comic, photoreal & future — AI-generated, then captioned and ORRERY-wordmarked in-house; click any poster for the full-resolution JPG), and /colophon (the bill-of-materials for Orrery's original content — every hand-made poster, diagram, anatomy plate, and 3D model, with how each was produced).

Explorer	Configurator	Mission Arc (heliocentric)
Mission Arc (cislunar)	Catalog	Earth Orbit
Moon Map	Mars Surface	ISS Explorer
Tiangong Explorer	Science Encyclopedia	Science Lens (live physics)

The Science Lens — turning the simulator into a textbook

Toggle the lens (top-nav icon) and every 3D scene gets a layer of live physics annotations:

• Spheres of influence — translucent rings showing where each body's gravity dominates.
• Hover info cards — live numbers (heliocentric speed, distance, gravity, light-time) on any planet.
• Gravity vectors · Velocity vectors · Centripetal arrows — log-scaled arrows so all are visible at once, with values printed at the tip so you can compare magnitudes across planets.
• Apsides + true anomaly — perihelion / aphelion markers + a live ν = 42° callout that travels with the body.
• Engine-off coast preview — dotted projection of where the spacecraft would drift if the engine cut right now.
• Conic-section family — names the current arc shape (circle / ellipse / parabola / hyperbola) live from specific orbital energy.
• Microgravity axes — zenith/nadir, prograde/retrograde, port/starboard on station scenes.
• Atmosphere shells, tidal-lock indicator, ozone holes — lens-gated atmospheric and rotational layers.

The Flight Director banner on /fly adds 5-phase narration (Departure · Trans-X Injection · Cruise · Approach · Arrival), each phase deep-linking to the corresponding /science section. Why? popovers explain individual numeric labels in context across every panel, and the Mission Sandbox layered onto the porkchop lets you pin one cell and click another to compare ΔDEP / ΔTOF / Δ∆v side-by-side.

Eight of these layers are wired into both /fly scenes — heliocentric for interplanetary, cislunar for Moon missions — so the same physics overlay reads correctly whether you're watching Curiosity coast to Mars or Apollo 17 swing around the far side of the Moon.

Casual users see clean scenes. Curious users opt-in to the entire physics layer.

Try a mission

The 113 missions in the catalog include flown classics, outer-system landmarks, recent flights, and a handful of concept missions. Moon missions open in the cislunar view (Earth at origin, real Earth-Moon scale); everything else stays heliocentric:

Pick	Why
?mission=apollo11	First crewed lunar landing — cislunar view shows the free-return figure-8, parking orbit, lunar orbit, descent + ascent
?mission=apollo13	Aborted lunar landing — free-return flyby + no LOI; closest-approach altitude visible past the Moon's far side
?mission=artemis2	The 2026 lunar flyby that inspired this project — hybrid free-return at 9,200 km periselene
?mission=chandrayaan3	Multi-burn Earth-bound spiral up to TLI, then a lunar spiral down to soft landing
?mission=change5	Lunar-orbit-rendezvous sample-return — orbiter stays in orbit while lander descends, ascends, docks
?mission=curiosity	One-way Mars landing — watch the live Mars dot meet the spacecraft at arrival
?mission=mariner4	First Mars flyby (1964) — short transit, real launch window
?mission=galileo	Outer-system gravity assist via Venus + Earth + Earth en route to Jupiter
?mission=starship-mars-crew	SpaceX's long-term crewed Mars round-trip architecture
?mission=tianwen1	China's first Mars mission

Why it matters

Orrery makes a few claims a screen reader can verify:

• Real physics. Keplerian two-body orbital mechanics. Lagrange-Gauss short-way Lambert solver. Vis-viva for heliocentric velocity. Tsiolkovsky for fuel. KaTeX-rendered formulas in the encyclopedia. All constants from IAU + JPL + agency mission reports — every number cited.
• Real missions. 113 base mission JSON files with editorial overlays in 14 locales. ∆v ledgers from NASA mission reports, JPL trajectory reconstructions, agency press kits. Moon missions carry a flight.cislunar_profile block (parking orbit, TLI ∆v + C3, translunar geometry type, lunar arrival altitude / periselene, return ∆v); Mars + outer-system missions carry a parallel flight.interplanetary_profile block (heliocentric waypoints, transfer type). Both are parsed by the trajectory builders to render each mission's actual flight architecture (ADR-058). Every entry has a data_quality honesty flag (MEASURED / RECONSTRUCTED / SPARSE / UNKNOWN).
• Real images. Agency-first build-time imagery sourcing per ADR-046: NASA / ESA / ISRO / CNSA / JAXA / KARI / Roscosmos before Wikimedia fallback. Per-image provenance manifest. Public /credits page. Lightbox attribution on every gallery thumbnail.
• Real outbound links. Per-link provenance per ADR-051: every external LEARN link is sourced, validated, and freshness-gated. Native-language priority for non-US entities (Roscosmos before NASA's mirror, ISRO before press releases). Public /library bill-of-links.
• Real translation. Each language follows its own space-agency glossary (ESA Spanish, JAXA Japanese, CNSA Mandarin, etc.) — not literal machine translation. See docs/guides/i18n-style-guide.md.
• Real accessibility. Axe-core CI gate across 11 routes at zero critical violations. Screen-reader-only parallel navigation on the 6 canvas routes (every clickable marker reachable as a <button>). prefers-reduced-motion honoured everywhere; full RTL for Arabic. Locale-aware alt-text auto-generated from the image-provenance manifest.

Audio narration (v0.7 ship — en-US)

Every primary route has a Guide-persona screen episode plus, on the high-density routes, additional Atmospheric Moves (/, /moon, /mars, /plan, /missions) and Enthusiast object-level deep-dives. 33 logical episodes, each voiced in two providers (Google Cloud Neural2 + ElevenLabs) so the overlay's A/B switcher lets you compare on the fly.

Open the audio overlay via the waveform icon in the nav (between the menu hamburger and the locale switcher). The overlay surfaces:

• For-this-screen inventory — episodes anchored to the current route, persona-tagged.
• All-episodes inventory — the full 33 with route + duration + heard-state tags.
• Take a tour — two auto-advancing playlists: the Curator Tour (21 episodes, ~66 min) and the longer Curator Extended Tour (31 episodes, ~87 min, interleaving 10 enthusiast deep-dives). Route-by-route auto-navigation, prev / stop / next controls, timed directive banners, and resume-where-you-left-off (the orrery_tour cookie, ADR-075). The complete episode inventory is on /colophon.
• Provider A/B switcher — flip between Google and ElevenLabs mid-playback; position preserved.
• Captions (CC button) — VTT track with auto-on triggers for prefers-reduced-motion, muted-at-start, and slow effectiveType. Transcript .txt download per episode.
• Deep-link share — ?audio={episode-id} opens the overlay + auto-loads the matching episode.

Every episode carries its origin on /credits — text authorship (Claude-drafted / human-authored / etc.) and voice provider per row. Operator-side details: docs/guides/audio-pipeline-setup.md. v0.8 adds Anthropic translation pipeline + 12-locale Curator Tour.

Privacy

Analytics — Umami, self-hosted, aggregate-only. The live site at orrerylearn.com loads a single Umami script.js from our self-hosted Umami at analytics.orrerylearn.com (behind Cloudflare, origin-locked — the data never leaves our own infrastructure to a third party). It records anonymous page-view counts per route and a handful of structured custom events (mission-load, lens-toggle, science-section-view, locale-switch — see src/lib/analytics.ts for the full list). That is the entire collected dataset, and it never identifies individuals — it is aggregate usage only.

Umami is cookieless, does no fingerprinting, captures no PII, has no cross-site tracking, and is GDPR / CCPA-compliant out of the box. Telemetry runs on a three-rung environment ladder so the public prod dataset only ever reflects real visitors: prod (orrerylearn.com) reports to its own Umami site; staging (the chipi.github.io/orrery gh-pages deploy) reports to a separate Umami site tagged environment=staging; and the maintainer's local vite dev reports to a third, dedicated dev site reachable only over our private Tailscale network. vite preview, the screenshot pipeline, and e2e runs stay silent (no baked config). Self-hosters who clone Orrery get zero analytics by default — the prod/staging env vars aren't in their CI, and the dev site's host resolves only on our tailnet, so a fork is silent by construction until they point it at their own Umami (ADR-081).

No IndexedDB, no third-party fonts at runtime (every asset resolved at build time per ADR-016). Client-side state is deliberately minimal and carries no PII: three functional cookies — orrery_locale (1-year, written only when you click a locale chip; auto-detected locales never write it — ADR-057), orrery_tour (30-day, Curator-Tour resume position — ADR-075), and orrery_analytics_optout (1-year, written only if you switch analytics off on /privacy — ADR-092), each written only on a deliberate action (orrery_tour and orrery_analytics_optout are SameSite=Lax; orrery_locale is written by Paraglide, which sets only path + max-age — see the ADR-057 amendment) — plus a few device-local localStorage keys for rendering preferences (orrery.qualityTier, debug mode, offline downloads); settings, no PII. Locale preference also lives in the URL — bookmark ?lang=ja and you have your locale; share it and they have theirs.

Error tracking — Sentry SDK → self-hosted GlitchTip, errors only, no PII, fork-silent. The SDK sends only unhandled JavaScript exceptions and unhandled promise rejections to our self-hosted GlitchTip at telemetry.orrerylearn.com — not a third-party SaaS — on the same three-rung ladder as analytics: prod, staging, and the maintainer's local vite dev each report to a separate GlitchTip project (tagged environment=prod|staging|dev, and in dev also by git worktree), so an error's origin is never ambiguous and dev noise never lands in the prod project. No performance tracing, no Web Vitals, no session replay. sendDefaultPii: false is set explicitly, and a beforeSend hook strips URL query parameters and hash, nulls request headers + cookies, and sets user.ip_address to 0.0.0.0 (the discard sentinel); ui.input breadcrumbs are dropped entirely. Self-hosters who clone Orrery and build their own fork get zero error traffic by default — the prod/staging DSN isn't in their CI secrets, and the dev DSN's host resolves only on our tailnet, so the SDK stays silent by construction before any network request fires (ADR-067). See src/lib/observability/sentry.ts for the full scrubber.

Getting started

Requirements: Node 22+, npm 10+.

git clone https://github.com/chipi/orrery
cd orrery
npm install

Development

npm run dev              # dev server at http://localhost:5273
npm run test             # Vitest unit tests
npm run test:e2e         # Playwright e2e (build runs first)
npm run typecheck        # svelte-check + i18n compile
npm run lint             # prettier + eslint
npm run validate-data    # ajv schema + image provenance + license allowlist + diagram integrity
npm run preflight        # full CI mirror: typecheck + lint + test + validate-data + build (run before pushing)

Build

npm run build            # production SPA in ./build (adapter-static)
npm run preview          # serve ./build at http://localhost:5273
npm run docs:build       # VitePress docs site at docs/.vitepress/dist

Docker (local stack)

A docker-compose.yml stack runs the production-shape artefact locally — an nginx image (ops/docker/Dockerfile.web) serving the built bundle, plus an on-demand pipeline-runner container with the full Node + gdal toolchain. See docs/guides/docker-stack.md for setup, troubleshooting, and the architecture (RFC-024).

npm run docker:e2e       # build, (re)create web, smoke-check, run Playwright (http://localhost:8080 in the primary)
npm run docker:e2e -- --skip-build --smoke-only   # just recreate + check web on the current build/
npm run docker:down      # stop the stack

On-demand pipeline runs without needing system gdal on your host:

npm run docker:fetch-launches      # refresh launches manifest
npm run docker:images:hotspots     # Mars/Moon orbital imagery
npm run docker:validate-data       # ajv + provenance + diagrams

First pipeline invocation builds the runner image (~10-15 min on Apple Silicon — gdal-async source-compile against system gdal); subsequent invocations start in seconds. Web tier production deploy (VPS + Caddy + GHCR) is deferred to a future RFC.

Deploy

Push to main — .github/workflows/preview.yml builds the app + docs and publishes to GitHub Pages. A weekly cron rebuild keeps mission imagery fresh (Mondays 06:00 UTC).

Documentation

The full architecture and concept documentation is published at https://chipi.github.io/orrery/docs/ — VitePress with local search and sidebar navigation.

Document	Read it for
User guide	How each of the eleven screens works — the read-this-first guide for the live app
00 Introduction	What this package is and how to read it
01 Vision	Why Orrery exists — the Moon-to-Mars narrative
02 Project Concept	Full synthesis — what Orrery is, does, and means
03 Data Catalog	Every source, constant, mission schema, credit format
05 Design System	Colour, typography, components, screen patterns
Mission trajectories	Operator guide for adding a new mission's waypoints + phase markers (cislunar + heliocentric)
i18n style guide	Per-language glossary for translators
docs/adr/	75 ADRs (ADR-001 through ADR-077) — locked decisions (Status / Decision / Rationale / Consequences). ADR-058 covers the cislunar /fly view (third amendment extends to Mars + outer-system via interplanetary_profile). See for the single-page architecture map.

If you read one document: read 02 Project Concept. It is the complete synthesis.

If you want to add a mission: read 03 Data Catalog for the JSON schema; then Mission trajectories for the waypoint + phase-marker workflow.

If you want to translate Orrery: read the i18n style guide and follow any locale's overlay tree under static/data/i18n/<code>/ as a template.

Physics

• Keplerian orbital mechanics, J2000 epoch (correct enough to teach, fast enough for a browser)
• Lambert solver: Lagrange-Gauss short-way formulation, 52 iterations, 11,200 cells
• Two-point Keplerian transfer ellipse with Sun at focus (transferEllipse) — both endpoints pin to live planet positions
• Earth-Centred-Inertial cislunar trajectory builder (buildCislunarTrajectory, ADR-058) — parking orbit → TLI coast → lunar-arrival phase (orbit / spiral / flyby / impact / orbit-and-land) → optional TEI coast → re-entry, with the lunar phase rendered in a moon-frame group that tracks the Moon's heliocentric drift each frame
• Vis-viva for heliocentric velocity telemetry
• Tsiolkovsky rocket equation for payload / fuel calculations
• Logarithmic radial scale for Earth orbit: EARTH_VIS_R + LOG_K × log₁₀(1 + alt_km / 100)
• Specific orbital energy ε for live conic-section classification on /fly

All constants documented in 03 Data Catalog with IAU sources. The /science encyclopedia carries the same numbers and derivations with KaTeX-rendered proofs.

Data

Mission data lives in plain JSON files — one per mission — served statically. No database, no backend. Adding a mission is editing a JSON file. Adding a language is adding a folder under static/data/i18n/<code>/.

Image sourcing per ADR-046: agency-first — NASA Images API + ESA + ISRO + CNSA + JAXA + KARI + Roscosmos before Wikimedia Commons fallback. Per-image provenance manifest at static/data/image-provenance.json (auto-generated, AJV-validated). Every credit is accurate. Public /credits page lists every image, every text source, every logo.

Outbound LEARN links per ADR-051: per-link provenance manifest at static/data/link-provenance.json (AJV-validated), agency-portal native-language priority, freshness-checked by scripts/check-learn-links.ts. Public /library page lists every outbound link.

Stack (production)

Concern	Tool	ADR
Framework	SvelteKit (adapter-static)	ADR-012
Language	TypeScript, strict: true	ADR-011
Bundler	Vite	ADR-012
3D rendering	Three.js r128, local bundle	ADR-001
2D rendering	Canvas API
Mission data	Static JSON files	ADR-006
Schema validation	ajv	ADR-019
i18n	Paraglide-js + locale-overlay JSON	ADR-017
Encyclopedia math	KaTeX server-rendered at build	ADR-034
Encyclopedia diagrams	Hand-coded SVG with integrity gate	ADR-035
Lambert solver	Web Worker	ADR-008
External assets	Resolved at build time

Contributing

Orrery is open source. Contributions welcome in three areas:

Data — add a mission, correct a date, update a status. Edit the JSON; no JavaScript required. See 03 Data Catalog.

Translation — add a locale by adding messages/<code>.json plus static/data/i18n/<code>/. The i18n style guide is the binding glossary.

Physics + code — file a correction if a number is wrong (every constant has a source in 03). New screens, performance improvements, accessibility, mobile layout. Read the architecture map and CLAUDE.md before opening a PR.

License

MIT — see LICENSE.

All agency logos, mission imagery, scientific data, and outbound links used in Orrery remain the property of their respective owners. They are used here for educational identification and attribution only, in a non-commercial context. See the /credits page in the live app and 03 Data Catalog for full credit format and licensing details per source.

Bill of materials

Three complete inventories of "what is in this app and where it came from", each maintained as code so they cannot drift from reality:

• Tech BOM — every npm package shipped or used at build time, with version + license. Auto-generated from node_modules by npm run build-tech-bom; license-audited fail-closed in CI (scripts/build-tech-bom.ts).
• Image BOM — every image, with source URL, license, attribution. Generated by npm run build-image-provenance (ADR-047). Browse the human-readable view at /credits.
• Link BOM — every outbound LEARN link, with source agency + locale. Generated by npm run build-link-provenance (ADR-051). Browse at /library.