Orrery

PRD-006 — Moon Map ​

Status · Draft v0.1 Sources · 02_Project_Concept.md §six-screens · 03_Data_Catalog.md §moon-sites Audiences · curious learner, STEM student (PA §audiences) Promises · real mission data fully attributed, educational at every level (PA §promises) Principles · attribution is design, physics first (PA §principles) Why this is a PRD · The Moon Map is the prologue to the Orrery narrative. It makes the capability ladder from 1966 to today legible — every mission that proved a technique Mars requires. Without this screen, the Mars focus floats without context.

A student rotating the 3D lunar sphere to find Chang'e 4's landing site pauses. The far side. The label reads: "First soft landing on the lunar far side — a hemisphere never visible from Earth, requiring a relay satellite for communications." They click the site. The panel opens. They read about the Queqiao relay. They understand for the first time why the far side is hard. They understand why it matters for Mars.

The problem ​

The Moon is a prologue, not a destination. Orrery's thesis is that every technique Mars requires was proven on the Moon first — soft landing, roving, sample return, south pole operations, far side communications relay. But these connections are invisible when the Moon and Mars are presented as separate programmes.

The experience ​

The default view is the 3D lunar sphere. It rotates slowly. The landing sites are marked as small crosshairs — 16 sites across 5 nations. Clicking a site opens a detail panel: nation, agency, year, mission name, outcome, what it proved.

The user rotates the sphere to see the far side. Chang'e 4 is there. They click it. The panel explains the Yutu-2 rover, the Queqiao relay satellite, the 2019 landing. The capability connection is written into the panel: "Demonstrated far-side communications architecture — the relay satellite approach required for any mission operating beyond line-of-sight from Earth."

The user switches to 2D flat map. The full lunar surface is visible. They can see the clustering of Apollo sites in the equatorial regions and the outlier position of Chandrayaan-3 near the south pole. The label explains: water ice.

The "still on the surface" sidebar in each panel shows what hardware remains — the Apollo descent stages, the Lunokhod rovers, the current active landers and rovers.

Why now ​

The Moon Map is the first screen in the narrative sequence (PA §principles: "the prototype is ground truth" — the narrative order is established in the prototypes). It sets up everything that follows. Without it, the mission library's Moon section has no spatial anchor, and the Mars focus appears unmotivated.

Success looks like ​

A user navigates from Luna 9 to Chandrayaan-3 and can narrate the capability ladder without prompting: "Luna 9 proved soft landing, which was required before you could do anything else. Chandrayaan-3 landed near the south pole where the water ice is — the same reason Artemis III is going there."

A user rotates the 3D sphere to find the far side and discovers that the Moon has a hemisphere they've never seen in photographs.

The south pole water ice context connects the Moon Map directly to the motivation for Artemis and, beyond it, Mars.

Out of scope ​

  • Selenographic features beyond landing sites (craters, mountains, mare by name)
  • Real-time rover positions (static historical landing sites only)
  • Missions that didn't reach the surface (orbiters without landing sites)
  • Landing site accuracy beyond nearest-km resolution

The sharpest threat ​

The "capability ladder" framing only works if the panel text for each mission makes the connection explicit. Luna 9's panel must say "first soft landing" not just describe the mission. Chang'e 4's panel must mention the communications relay, not just the landing. The connections must be in the data, not assumed by the reader.

Open threads ​

  • UXS-006 for full visual contract
  • Moon site data to move from prototype embedded data to data/moon-sites.json
  • RFC-002 adjacent: moon site JSON schema needs the same canonicalisation attention as mission JSON
  • Prototype: docs/prototypes/P06_moon-map.html
  • Concept: docs/concept/02_Project_Concept.md §six-screens

Status · Decided · shipped 2026-05-02

The detail panel that opens when a landing site is clicked now exposes three tabs (OVERVIEW · GALLERY · LEARN):

  • GALLERY — for sites that match a flown mission ID (Apollo 11/17, Luna 9/17/24, Chang'e 4/5/6, Chandrayaan-3, SLIM, Artemis 3) the gallery copies images from images/missions/{id}/ — same photos, different surface, no duplicate downloads. For the four extra Apollo sites in the moon catalogue but not the mission catalogue (Apollo 12/14/15/16) NASA Images API is queried directly. Chang'e 3 uses a Wikimedia fallback. 44 photos total across 16 sites.
  • LEARN — the already-curated links[] in the moon-site base record (intro/core/deep tiers) is now surfaced. Reads from Wikipedia primers (intro), NASA / agency mission pages (core), and peer-reviewed Moon-science papers (deep).

Why it matters: PRD-006's "capability ladder" framing depends on the panel text making each mission's contribution explicit. The GALLERY makes that ladder visceral — the user can see what each landing actually looked like, from the gritty 1966 Luna 9 still photographs to the sharp 2024 Chang'e 6 frames. The LEARN tab makes the next step into the literature obvious.

Honesty rule: sites without photos render no GALLERY tab. Sites without links[] render no LEARN tab.

Orrery — architecture documentation · MIT · No tracking

© Marko Dragoljević and contributors