ADR-040 — ISS Explorer asset pipeline and nav placement

Status · Accepted
Date · 2026-05-05
Closes · RFC-013 (with ADR-041, ADR-042)
TA anchor · §components / primary-route-pages
Related · PRD-010, ADR-016 (build-time assets), ADR-017 (i18n)

Context

PRD-010 / GitHub #41 introduce /iss: a rotatable ISS with per-module panels. RFC-013 asked where the mesh comes from, how heavy it may be, Earth backdrop, and nav order.

Decision

Model source (RFC OQ-1 — Option A refined)

V1 ships a code-built diagrammatic ISS in src/lib/iss-proxy-model.ts: Three.js box primitives + truss/array meshes assembled at runtime so each canonical module id from iss-modules.json maps to a named pickable mesh (userData.moduleId). No Node-side GLTF export — Three.js GLTFExporter depends on browser FileReader, so CI cannot emit a proxy GLB without extra tooling.

Rationale: NASA Science publishes low-detail ISS GLB references suitable for a future Blender-split swap-in; until then the proxy satisfies picking, attribution panels, and performance teaching goals while staying MIT-licensed and negligible in download weight. static/models/iss/CREDITS.md records NASA reference links.

Budget: Proxy stays ≪ 50k tris (actually low thousands). A future NASA-derived GLB must stay within PRD ~50k tris and < 4 MB gzipped when upgraded.

Earth limb backdrop (RFC OQ-4 — Option B)

Static Earth limb behind the station using existing texture static/textures/2k_earth_daymap.jpg (same asset as /earth + /explore): large textured sphere, no animated rotation in V1.

Nav order (RFC OQ-7)

Insert ISS after EARTH:

EXPLORE → MISSIONS → PLAN → FLY → EARTH → ISS → MOON → MARS

Build hook

npm run build does not invoke Blender or mesh exporters. Adjust layout in iss-proxy-model.ts when module positions change.

Consequences

Positive: Predictable CI; no multi-hundred-MB NASA checkout; clear path to replace GLB later.

Negative: V1 silhouette is diagrammatic, not photoreal — acceptable for interaction proof; PRD “recognisable ISS” is partially met via layout and labelling, not film-grade mesh.

Implementation notes

• Loader: GLTFLoader from three/examples/jsm (Three r128).
• Attribution: static/models/iss/CREDITS.md.