Orrery

PRD-008 — Science (in-app encyclopedia) ​

Orrery · Product Requirements · v0.1 · May 2026

Status: Draft Depends on: RFC-011 (open — must close before implementation begins) Slice: v0.4 Screens affected: new /science route, plus a ? chip on every existing screen that surfaces a physics term Principles: physics first, attribution is design, mobile-first (PA §principles) Why this is a PRD · The simulator references Hohmann, Lambert, vis-viva, ∆v, C3, V∞, free-return, Tsiolkovsky — without explaining any of them. Every link out to Wikipedia is a moment we ask the user to leave the app to make sense of the app. This PRD defines an in-app reference companion that closes that loop.

§why ​

Orrery is dense with terminology. A typical /fly HUD shows ∆V HELIO 32.4 km/s · MET DAY 228 · DESDE LA TIERRA 1.52 AU. The /plan porkchop axes are labelled "DEPARTURE WINDOW" and "TIME OF FLIGHT" with a colour bar from 3 to 11+ km/s. The /missions FLIGHT tab surfaces C3 = 12.5 km²/s², V∞ = 2.94 km/s, TLI ∆v = 3.06 km/s. The mission narratives mention free-return, gravity assist, EDL, NRHO.

The expert knows what every one of those means. The curious learner — our primary audience per PA — does not. Today our answer is "click a Wikipedia link in the LEARN tab," which fragments the experience and fails on mobile (modal context-loss).

A companion /science page — short, illustrated, deep-linkable — closes the loop. The simulator becomes its own teaching companion: every term has an explanation reachable in one click without leaving the app.

§audiences ​

This feature serves all three PA audiences, weighted toward the first two:

The curious learner (primary). Sees C3 = 12.5 km²/s² in the FLIGHT tab, taps a ? chip, lands on a 200-word section explaining what C3 means with a diagram of a launch trajectory's hyperbolic excess velocity. Returns to the simulator informed.

The STEM student (primary). Reads /science/orbits/vis-viva linearly. Sees the equation v = √(μ·(2/r − 1/a)) rendered with KaTeX, with a one-paragraph derivation hint, the values of μ for the Sun, and a cross-link "you can verify this on /explore — click any planet, the panel shows v at that orbital radius."

The space enthusiast (secondary). Uses /science as a quick reference. Cmd-K to search ("Hohmann transfer"), arrives at the section, reads, leaves.

§promises ​

The simulator makes these promises to a user reaching /science:

  1. Every formula and named term referenced anywhere in the app has an explanation here. No dead-end tooltips. No "go look this up." The PRD inventory (§appendix) is the contract — every entry must have a corresponding section.
  2. Every explanation is illustrated. Each section has at least one visual element: a diagram, photo, formula, or annotated chart. No walls of text.
  3. Every section is short. Body ≤ 200 words. One concept per section. Density via images, not paragraphs.
  4. Every section is deep-linkable. /science/transfers/hohmann is a URL. Sharing it lands you at the section, opened.
  5. Every section cross-references where the concept appears in the simulator. "You'll see this on /plan as the colour gradient on the porkchop." Links navigate.
  6. It is locale-aware. Spanish, future Wave-1 languages and beyond translate with the rest of the app per ADR-017. Physics terminology follows the glossary at docs/guides/i18n-style-guide.md.
  7. It is mobile-first. Every section readable at 375 px width without horizontal scroll. Math doesn't break the layout. Diagrams scale.

§scope ​

In scope (V1) ​

Six top-level tabs, each with 5–10 short sections:

  1. ORBITS — Keplerian elements (semi-major axis, eccentricity, mean longitude, true anomaly, inclination, longitude of ascending node, argument of periapsis); Kepler's three laws; perihelion / aphelion; perigee / apogee; line of apsides; vis-viva equation; circular vs elliptical vs hyperbolic orbits.

  2. TRANSFERS — Hohmann transfer; Lambert's problem; transfer ellipse; conic sections in orbital mechanics; free-return trajectory; gravity assist (flyby); patched-conic approximation.

  3. PROPULSION — ∆v as the universal mission budget; Tsiolkovsky rocket equation Δv = Isp·g·ln(m0/mf); specific impulse (Isp); characteristic energy (C3); hyperbolic excess velocity (V∞); Oberth effect.

  4. MISSION PHASES — launch; trans-X injection (TLI / TMI / TVI / TJI); cruise + trajectory correction maneuvers (TCMs); arrival options (orbit insertion · flyby · entry-descent-landing · sample return · splashdown); mission-elapsed time (MET); near-rectilinear halo orbit (NRHO).

  5. SCALES & TIME — astronomical unit (AU); light-minute; J2000 epoch; sidereal vs synodic period; mean motion; the ecliptic plane; heliocentric vs geocentric vs body-centric frames.

  6. PORKCHOP — what a porkchop plot is; departure-window axis; time-of-flight axis; the ∆v heatmap; reading a contour; why launch windows are constrained; what makes a trajectory "viable" given a rocket's ∆v capability.

Each section has the same structure:

  • Headline (Bebas Neue, 24 px desktop / 18 px mobile)
  • One-sentence intro (Crimson Pro italic, 14 px)
  • Visual element — formula, diagram, or photo
  • 1–3 short body paragraphs (Space Mono / Crimson Pro mix per existing tokens)
  • "See this in the app" chip → links to /plan, /fly, /explore, /missions, /earth, or /moon
  • "Learn more" external links (NASA, ESA, Wikipedia, original papers — same tier system as mission LEARN tabs)

Cross-screen ? chips. Every existing HUD label that names a concept covered in /science gets a 14×14 px ? chip next to it. Tapping the chip navigates to the relevant /science/[tab]/[section] URL. Examples:

  • /plan porkchop axis labels (DEPARTURE WINDOW ?, TIME OF FLIGHT ?)
  • /fly HUD rows (∆V HELIO ?, MET ?)
  • /missions FLIGHT tab fields (C3 ?, V∞ ?, TLI ?)
  • /explore planet panel (Keplerian element rows)

Out of scope (V1) ​

  • Interactive simulators inside /science. The existing screens are the simulators; /science is the reference.
  • Quizzes or self-test exercises.
  • Video.
  • User-contributed content / community editing.
  • Search across the whole app (Cmd-K). Search inside /science (jump-to-section) is in scope.
  • Citations engine. External links are hand-curated per section, same as existing LEARN tiers.

§design hints ​

Layout (desktop ≥ 1024 px). Three columns — agency-style chrome:

  • Left rail (240 px): tab list + active-tab section list. Sticky.
  • Centre column (flexible, max 720 px): reading pane. One section visible at a time.
  • Right rail (220 px): "see this in the app" + "learn more" links + a tiny progress dot showing position within the tab.

Layout (tablet 768–1024 px). Two columns — left rail collapses; reading pane grows.

Layout (mobile < 768 px).

  • Top: horizontal-scroll tab strip (44 px touch targets per ADR-018).
  • Below: reading pane (single column).
  • "See this in the app" + "learn more" stack as cards below the body text.
  • Section nav: prev / next arrows at bottom of each section.

Typography.

  • Bebas Neue for tab names + section headlines (matches the rest of the app).
  • Crimson Pro italic for intro sentences and prose paragraphs (editorial register).
  • Space Mono for formula lines, units, and HUD-style callouts (matches the simulator's data labels).
  • Math: KaTeX-rendered LaTeX (see §technical-considerations).

Embedded media.

  • Diagrams. SVG, hand-curated, dark-theme native. ~30 needed for V1 (one per section that has a geometric concept). Drawn in Inkscape / Figma; checked in to static/diagrams/science/[section].svg.
  • Photos. NASA Image API, ESA, Wikimedia Commons. Public-domain or CC-BY only. Same fetch-at-build flow as static/images/missions/.
  • Formulas. KaTeX renders \Delta v = I_{sp} \cdot g_0 \cdot \ln(m_0 / m_f) to crisp HTML at build time. No runtime math library.

Cross-link chips. Same token as the agency-link chips in mission LEARN tabs. Each chip names the destination route + a 1-line context: → /plan · the colour gradient on the porkchop is a Δv heatmap.

? chip pattern (cross-screen). 14 px circle, white-50 fill, white-90 question mark, 1 px border. Min 24×24 px hit area (smaller than the 44 px primary-touch baseline because they're inline with HUD rows). On hover/focus: tooltip ≤ 80 chars (the section's intro sentence). On tap: navigate to /science/[tab]/[section].

Empty / loading. /science is statically pre-rendered (no async data); no loading state needed. If a section URL is malformed, redirect to the tab index.

§non-goals ​

  • Not a replacement for Wikipedia. Sections are ≤ 200 words. The "learn more" links are the deep-dive path. We curate the entry point, not the encyclopedia.
  • Not a math textbook. Formulas appear with definition + practical "what this means in this app." No derivations beyond a one-line hint.
  • Not a separate site. /science is a peer route to /explore /plan /fly /missions /earth /moon. Always reachable in one click from anywhere via the nav bar.
  • Not a substitute for the LEARN tab on mission cards. Mission LEARN tabs stay; they cover that mission's engineering and history. /science covers the underlying physics independent of any one mission.

§technical considerations ​

  • Content storage. Sections live as locale-overlay JSON: static/data/science/[tab]/[section].json (base, language-neutral structure) and static/data/i18n/[locale]/science/[tab]/[section].json (translatable strings). Fetch via src/lib/data.ts per the existing pattern. Schema validated by ajv per ADR-019.
  • Math rendering. KaTeX (npm i katex, ~70 KB minified gzipped). Server-rendered at build (SvelteKit prerender), so the client receives HTML, not LaTeX source. No client-side math library.
  • Diagrams. Hand-drawn SVG. Build script (scripts/validate-diagrams.ts) verifies every section that declares a diagram field has a matching SVG file present.
  • URL structure. /science (tab index) → /science/[tab] (section list within the tab) → /science/[tab]/[section] (the section). All three are deep-linkable per RFC-004.
  • Locale flow. Already covered by ADR-017. Translators add one folder per locale. en-US fallback per ADR-017.
  • ? chip wiring. Each chip sets href={${base}/science/${tab}/${section}}. No new component infrastructure — same as existing LEARN tab links.
  • Performance budget. /science target: < 50 KB additional JS (KaTeX is the bulk; the route itself adds < 5 KB). Diagrams lazy-loaded per section.
  • Search. A static lookup table (science-index.json) generated at build maps every term, formula, and synonym to the canonical /science/[tab]/[section] URL. Cmd-K opens a section-list filter with fuzzy match. ~80 entries.

§definition-of-done ​

A locale is considered "Science-shipped" when:

  • [ ] All ~40 sections in §scope have base + locale JSON populated.
  • [ ] Every section has body ≤ 200 words, ≥ 1 visual element, ≥ 1 "see in app" chip, ≥ 1 "learn more" external link.
  • [ ] Every term in the §appendix inventory has a section (or is intentionally redirected to a related section — documented per term).
  • [ ] Every existing app HUD / panel surface that names a concept in §appendix carries a ? chip linking to the relevant section (auditable list maintained in this PRD).
  • [ ] All sections render at 375 px width without horizontal scroll.
  • [ ] All formulas render correctly via KaTeX.
  • [ ] All diagrams load and are visually correct in dark theme.
  • [ ] Deep-link URLs resolve: pasting /science/orbits/vis-viva lands you at that section, opened.
  • [ ] Cmd-K (or mobile equivalent) jump-to-section works against the static index.
  • [ ] No console errors on any section URL.
  • [ ] Lighthouse accessibility ≥ 95 on /science and one representative section URL.
  • [ ] E2e: tap a ? chip on /plan, /fly, /missions → land on the right section. Run for both /plan-axis and /fly-HUD.
  • [ ] KaTeX bundle adds < 100 KB to JS payload (audited via the build report).
  • [ ] Bundle adds < 200 KB total weight including diagrams (lazy-loaded — initial load only).

§appendix — concept inventory ​

The list below seeds the V1 sections. Items marked (constant) are physical constants the app hardcodes; they're documented in their parent concept's section, not as standalone sections.

Orbits ​

  • Keplerian orbit (two-body, heliocentric)
  • Semi-major axis (a)
  • Eccentricity (e)
  • Mean longitude (L₀); mean motion
  • True anomaly (ν); eccentric anomaly (E)
  • Inclination
  • Longitude of ascending node (Ω)
  • Argument of periapsis (ω)
  • Orbital period (T)
  • Vis-viva equation: v = √(μ·(2/r − 1/a))
  • Kepler's three laws
  • Perihelion / aphelion (heliocentric)
  • Perigee / apogee (geocentric)
  • Line of apsides
  • Sphere of influence

Transfers ​

  • Hohmann transfer
  • Lambert's problem (Lagrange–Gauss form)
  • Transfer ellipse with Sun at one focus
  • Conic sections (ellipse · parabola · hyperbola)
  • Free-return trajectory (lunar Apollo, Mars Inspiration-Mars concept)
  • Gravity assist / flyby
  • Patched conics

Propulsion ​

  • ∆v (delta-v) as mission budget
  • Tsiolkovsky rocket equation
  • Specific impulse (Isp)
  • Characteristic energy (C3) — (constant) in mission FLIGHT tabs
  • Hyperbolic excess velocity (V∞)
  • Oberth effect
  • Mass ratio (m₀/m_f)

Mission phases ​

  • Launch + ascent profile
  • Trans-X injection family (TLI · TMI · TVI · TJI · TSI)
  • Trajectory correction maneuver (TCM)
  • Cruise / coast phase
  • Orbit insertion (LOI / MOI / generic OI)
  • Entry-descent-landing (EDL) — Mars, Venus, Earth
  • Sample-return arrival
  • Splashdown
  • Mission-elapsed time (MET)
  • Near-rectilinear halo orbit (NRHO)

Scales & time ​

  • Astronomical unit (AU); UA in romance languages
  • Light-minute and light-year
  • Astronomical Unit-per-year and the kms↔AU/yr conversion
  • J2000 epoch
  • Sidereal vs synodic period
  • Solar gravitational parameter μ_Sun = 4π² AU³/yr² (constant)
  • IAU AU-to-km = 149,597,870.7 (constant)
  • The ecliptic plane
  • Heliocentric vs geocentric vs body-centric frames

Porkchop ​

  • What a porkchop plot is
  • The departure-window axis
  • The time-of-flight axis
  • The ∆v heatmap (3.2 → 11+ km/s scale used in the app)
  • Contour reading
  • Why launch windows are constrained (synodic geometry)
  • Reading viability (rocket's ∆v capability ≥ cell ∆v)

§what comes after ​

The companion RFC-011 will resolve the open design + technical questions:

  1. KaTeX vs alternatives. MathJax (slower, larger, better fallback) vs KaTeX (faster, smaller, less complete) vs server-side MathML (no client lib). Recommendation pending; KaTeX is the working assumption.
  2. Diagram authoring workflow. Inkscape source-of-truth → SVG export → checked in. Vs Figma export. Vs hand-coded SVG. Cost vs maintenance trade.
  3. ? chip UX. Hover tooltip vs click-to-open. Mobile has no hover, so click is the only universal path. Tooltip-on-hover is bonus.
  4. Image-per-paragraph vs image-per-section. V1 baseline is one visual per section. Some sections might want two (e.g. Hohmann transfer's diagram + Hohmann's photo).
  5. Diagram licensing chain. Are we OK with NASA/ESA/Wikimedia only, or do we draw original SVGs? Original SVGs are slower to produce but lock the visual style.
  6. Glossary view. Alphabetical lookup as a flat list, in addition to tabbed reading. Probably a nice-to-have for V1.5.
  7. /science indexing. Should /science have its own sitemap.xml entry? SEO play — these pages will be the most search-friendly part of the app.
  8. Translation cadence. Each section is ≤ 200 words, but ~40 sections × 5 Wave-1 languages = 200 sections. Not free; needs a translation budget.

Orrery · PRD-008 · Draft v0.1 · Update when scope or definition-of-done changes.

Orrery — architecture documentation · MIT · No tracking

© Marko Dragoljević and contributors