Orrery

PRD-001 — Solar System Explorer ​

Status · Draft v0.1 Sources · 01_Orrery_Vision.md §solar-system · 02_Project_Concept.md §six-screens Audiences · curious learner, STEM student (PA §audiences) Promises · real physics, educational at every level (PA §promises) Principles · physics first, prototype is ground truth (PA §principles) Why this is a PRD · This screen changes how a person understands the solar system — not just what the planets look like, but how they actually move and why the geometry makes Mars missions hard. It is the educational core of Orrery.

A person who has watched a spacecraft launch but never understood why it took seven months is sitting at home with a browser open. They click EXPLORE. The solar system rotates in front of them. They click Earth. A panel slides in. They switch to the TECHNICAL tab. For the first time they watch a number — orbital velocity in km/s — change as Earth moves along its ellipse. The number is bigger near perihelion. It makes sense.

The problem ​

The geometry of the solar system is almost never shown correctly. Diagrams show circular orbits. Animations show equal-speed planets. The 26-month Mars launch window looks arbitrary. The reason Mars missions take 259 days is invisible — there is no tool that shows the actual elliptical transfer orbit in context, with the actual orbital velocities changing in real time.

Orrery's solar system explorer is that tool.

The experience ​

The default view is 3D. The eight planets orbit the Sun at their correct relative speeds. Inclinations are visible — the Kuiper Belt objects tilt noticeably out of the ecliptic plane. Saturn's rings are there. The Sun is clickable.

The user clicks on Mars. The detail panel opens to OVERVIEW: the editorial description of Mars, its key parameters, what makes it interesting. They switch to TECHNICAL: eccentricity 0.093, inclination 1.85°, orbital velocity updating in real time from the vis-viva equation. They watch the velocity increase as Mars moves toward perihelion. They switch to SIZES: a canvas showing all eight planets at true relative scale. Jupiter is enormous. Earth is a dot.

They switch to 2D. The solar system flattens to a top-down view. They can see the orbital ellipses — Earth's is nearly circular; Mars's is noticeably eccentric. They zoom out with the scroll wheel and see the Kuiper Belt and Planet Nine's hypothetical orbit at the edge.

They click the Sun. The panel opens. The editorial text explains that the Sun contains 99.86% of all mass in the solar system, that it fuses 600 million tonnes of hydrogen per second, that in 5 billion years it will engulf the inner planets. The LEARN tab links to the Milky Way article — because the Sun is also our position in the galaxy, and that context matters.

Why now ​

The solar system explorer is Act 1 of Orrery's narrative. Without it, the mission configurator has no context — the user doesn't understand why launch windows exist or why the trajectory matters. It is the foundation everything else builds on.

Success looks like ​

A user with no physics background can correctly explain why Mars missions can only launch every 26 months after using this screen for 10 minutes.

A STEM student uses the TECHNICAL tab to verify that the vis-viva velocity they computed in class matches what Orrery shows for their planet.

A user zooms out in 2D until they can see Planet Nine's hypothetical orbit and reads the label with genuine curiosity.

The Sun panel is the first place a general user has ever been shown their position in the Milky Way in context of a solar system view.

Out of scope ​

  • Moons of other planets (only Earth's Moon and Saturn's rings are shown)
  • Asteroid belt individual objects (only the belt density cloud is shown)
  • N-body gravitational effects
  • Atmospheric detail on planet spheres

The sharpest threat ​

The TECHNICAL tab shows real numbers. If a curious learner uses it and the numbers feel arbitrary — if the vis-viva velocity is just a number with no intuition attached — the tab fails. The numbers need to be explained in context. "This is why Mars is faster near the Sun" is the experience; the number alone is not.

Open threads ​

  • UXS-001 for full visual contract
  • ADR-001, ADR-011, ADR-012 lock the rendering, language, and framework decisions
  • Prototype: docs/prototypes/P01_solar-system-explorer.html
  • Concept: docs/concept/02_Project_Concept.md §six-screens

Status · Decided · shipped 2026-05-02

PlanetPanel and SunPanel now expose two new tabs alongside OVERVIEW / TECHNICAL / SIZES:

  • GALLERY — photo grid sourced from NASA Images API + Wikimedia Commons. 5 photos per planet (40 total) + 5 for the Sun. Tab is conditional on a non-empty manifest (static/data/planet-galleries.json, sun-gallery.json); hidden if no photos populated. Click a thumbnail → full-screen lightbox.
  • LEARN — tiered intro/core/deep links curated per planet + Sun. Each tier surfaces 1–2 references: Wikipedia primer (intro), NASA mission page (core), peer-reviewed paper (deep). Stored as optional links[] in the planet/sun overlay (ADR-017 convention).

Why it matters: the OVERVIEW + TECHNICAL pair already explains "what is this and how does it move." The GALLERY makes the body feel real (photos earned the click); the LEARN tab gives the learner an explicit next step into authoritative material.

Honesty rule: missing photos → tab simply doesn't render. Missing links → LEARN tab also stays hidden. Never broken thumbnails or generic placeholders.

Orrery — architecture documentation · MIT · No tracking

© Marko Dragoljević and contributors