System Requirements Document for astronaut-lunar-base

1. Introduction

astronaut-lunar-base, branded in-product as OUTPOST — A Junior Astronaut Mission Trainer, is a free browser-based learning simulation for students aged 10–16. Students act as the Commander of a four-person lunar or Martian outpost and make engineering decisions for a ninety-day mission under one non-negotiable currency: mass in kilograms.

The system makes life-support, power, food, shielding, radiation, water-recovery, hygiene, and crew-morale trade-offs tangible without simplifying them into points or abstract coins. It is designed for individual student play and classroom use, including offline environments, and produces an exported mission log that students can retain and teachers can use as an assessment artefact.

2. System Overview

OUTPOST is an offline-capable Progressive Web Application (PWA) with a TypeScript simulation engine and React interface. A Student Commander configures a lunar or Martian base before landing, then runs the mission sol by sol, allocates available power and crew hours, responds to failures and solar-weather events, and observes resource and crew status.

The current simulation covers one lander, fixed cargo capacity, four crew, and ninety sols. The balance model intentionally makes an “everything” design weigh 24,386 kg, exceeding the 12,000 kg lander capacity. This is a deliberate engineering challenge rather than a balance defect.

The system supports two current modes:

• Cadet mode, for supported learning.
• Commander mode, for deeper mission-management engagement.

Two scenarios ship with the product so that the correct response to comparable trade-offs can invert between scenarios. The system must teach that engineering problems do not have one universal correct answer.

2a. Product Interpretation and Delivery Boundary

OUTPOST is delivered as a first-party, anonymous browser application. It requires no account, sign-in, profile, personal-data submission, analytics, or tracker. Mission state and cached source data are stored locally on the device so that students can begin, continue, complete, and export a mission without identity continuity across devices.

NASA data is fetched at startup when available, stored as an offline snapshot, and reused when connectivity is unavailable. NASA services remain external data providers; their information is represented in the game through first-party interface elements with visible source citations and a LIVE or CACHED state.

The current product includes the simulation, loadout configuration, mission dashboard, event decisions, debrief, mission-log export, NASA-backed data elements, and teacher-pack materials. It excludes account management, cloud storage, analytics, personal-data collection, social competition, point systems, crew-death depictions, and teacher dashboards.

Current Delivery Boundaries

• One Student Commander controls one four-person simulated outpost.
• The simulation covers a ninety-day lunar or Martian mission.
• The product uses kilograms as its sole decision currency; it does not use points, coins, achievements, or reward currencies.
• Classroom operation must not depend on venue Wi-Fi.
• The teacher pack is provided as openly reusable supporting material; no teacher account or in-product role permissions are required.
• NASA imagery and terrain data are evidence-bearing mission artefacts, not uncited decorative assets.

Future Boundary

The following are future work and are not part of the current pages, acceptance criteria, or required implementation:

• A cutaway outpost visualization showing effects such as dimming lights and wilting crops.
• A module designer that allows classes to define hardware for simulation evaluation.
• Localization into Hindi, Spanish, and Arabic.
• A teacher dashboard aggregating exported mission logs to identify class-wide misconceptions.

2b. Source Content Inventory

The authoritative NASA open-data content source supplies the following current factual content and feature uses:

2c. Page Content and Component Coverage

Landing

• Information and state

  • Identifies OUTPOST as a free, browser-based, offline-capable junior astronaut mission trainer for ages 10–16.
  • States that students command a four-person lunar or Martian base for ninety days.
  • Presents Cadet mode and Commander mode.
  • Shows that no account is required and that the product saves locally.
  • Shows the current NASA-data availability state when startup retrieval completes: LIVE for successfully retrieved current data or CACHED when the latest local snapshot is used.

• Primary actions

  • Start a mission and proceed to the loadout screen.
  • Select Cadet mode or Commander mode.

• Supporting content

  • Explains that kilograms, not points, are the mission currency.
  • Shows a concise offline-ready statement and data-citation expectation.
  • Provides access to the teacher-pack context without requiring a teacher account.

• Domain entities

  • Mission mode, scenario, mission seed, local NASA-data snapshot, LIVE/CACHED status.

• States and recovery

  • Loading state while startup data retrieval and cache lookup occur.
  • Cached-data state when offline or when retrieval fails.
  • Clear recovery message when no current live retrieval is available, continuing with a locally available snapshot where present.
  • Keyboard-operable mode selection and start control.

loadout screen

• Information and state

  • Displays the fixed 12,000 kg lander cargo capacity and continuously updated landed mass.
  • Displays an understandable mass ledger for selected hardware, consumables, and spares.
  • Supports lunar and Martian scenario context and real terrain placement at Shackleton Crater rim or Jezero Crater.
  • Presents terrain data citation, retrieval date, and LIVE/CACHED state.
  • Makes the deliberate impossibility of an “everything” configuration visible: 24,386 kg against the 12,000 kg lander limit.

• Primary actions

  • Select and remove habitat, power source, oxygen generator, carbon-dioxide scrubber, water processor, shielding, greenhouse, rover, spares, and food.
  • Select an available scenario and mission mode.
  • Begin a mission only with a loadout that fits the cargo capacity.

• Supporting actions

  • Review each item’s mass and relevant operating implications.
  • Review trade-offs including:
    • greenhouse lighting consuming 8 kW continuously;
    • shielding mass versus radiation dose;
    • air and water recycling hardware versus resupply mass;
    • hydroponics mass, food contribution, power draw, morale, and biology;
    • hygiene rationing versus morale.
  • Review terrain placement and cold-soak relevance.

• Domain entities

  • Lander, cargo capacity, loadout module, consumable, spare, scenario, terrain location, mass ledger, mission seed.

• States and recovery

  • Over-capacity state clearly identifies mass overflow and prevents mission start until the player removes or changes selected cargo.
  • Empty-loadout state identifies indispensable selections needed to form a mission configuration without inventing unlisted module types.
  • Selected-item and removed-item state updates mass immediately.
  • NASA source retrieval failure does not block loadout when cached terrain data is available; the display changes to CACHED.

dashboard

• Information and state

  • Displays current sol, mission seed, simulation-speed setting, pause state, and landed-mass counter.
  • Displays six resource dashboards: power, oxygen, carbon dioxide, water, food, and radiation.
  • Displays crew health and morale.
  • Displays relevant subsystem status, resource trends, alarms, solar-storm state, cold-soak penalties, and available crew hours.
  • Displays the selected terrain context and data citations where terrain, solar, temperature, or Earth imagery informs a shown state.
  • Provides an Earth View morale action with DSCOVR/EPIC Earth photography, citation, retrieval date, and LIVE/CACHED state.

• Primary actions

  • Allocate power among operating needs, including life-support needs and greenhouse demand.
  • Allocate crew hours each sol.
  • Advance simulation progress at the selected speed.
  • Pause the simulation mid-sol.
  • Open an active failure or event in Events.
  • Trigger the Earth View morale action when available.

• Supporting actions

  • Adjust simulation speed.
  • Review resource trends, current alarms, and the likely limiting resource.
  • Review resource, radiation, terrain, solar, temperature, and imagery citations.

• Domain entities

  • Sol, power allocation, crew-hour allocation, resource reserve, radiation dose, crew health, crew morale, Earth View image, solar event, cold-soak condition, alarm, mission seed.

• States and recovery

  • Paused state freezes simulation advancement while keeping current decisions visible.
  • Alarm states use sound, shape, text, and colour; they never rely on colour alone.
  • A solar storm creates a shelter outcome for the simulated crew.
  • Cold-soak penalties affect the simulation in permanently shadowed regions.
  • Resource-threshold and equipment-failure states lead to Events or, where mission continuation is no longer viable, a survivable abort and debrief.
  • Offline operation retains cached NASA-backed state and labels it CACHED.

Events

• Information and state

  • Presents active failure and event cards with the affected system, operational context, decision choices, consequences, and a short transferable real-world engineering note of fewer than twelve words.
  • Preserves the current water-processor scenario:
    • Water processor — urine line pressure loss.
    • Reclamation-loop throughput is reduced by 40 per cent.
    • Three spares remain.
    • The next resupply window is 22 sols away.
    • Option A: replace the pump now for one spare and three crew-hours.
    • Option B: run at half rate; water falls by 1.4 kg per sol.
    • Option C: bypass to storage until resupply; potable reserve falls below its 30-sol margin.
    • Engineering note: ISS water processors were designed to keep running while degraded.

• Primary actions

  • Choose a presented response option.
  • Confirm the selected option and return to the dashboard with its simulation effects applied.

• Supporting actions

  • Review exact effects on mass, spares, crew hours, resource reserves, projected sol consequences, and relevant crew outcomes.
  • Read the real-world engineering note.
  • Review NASA data citations for data-driven events such as solar storms and temperature-driven cold-soak conditions.

• Domain entities

  • Event, equipment failure, decision option, spare, crew hour, resource consequence, engineering note, solar storm, cold-soak penalty, abort condition.

• States and recovery

  • Each choice is keyboard-addressable and distinguishable by its written label, shape, and state, not colour alone.
  • An accepted option records its consequences in mission state and mission log.
  • If a chosen response creates an abort threshold, the system presents a survivable equipment-failure abort rather than crew death and continues to debrief.
  • If event data is cached, the event remains playable with CACHED provenance shown.

debrief

• Information and state

  • Ends every run with mission outcome, including successful completion or survivable abort.
  • Names the exact system that failed when the run ends through failure.
  • Shows the mission’s limiting subsystem, mass-budget breakdown, resource trajectory, selected decisions, in-game events, and relevant learning notes.
  • Shows a ninety-sol mission trace where applicable.
  • Presents the exported mission log as a student record and teacher assessment artefact.

• Primary actions

  • Export the mission log at the end of every run.
  • Review the mission outcome and causal system failure.

• Supporting actions

  • Review chosen loadout, resource trends, mass ledger, event responses, solar-weather and cold-soak effects, and data provenance.
  • Continue by beginning another mission through the loadout screen.

• Domain entities

  • Mission result, exact failed system, abort result, mission log, mass ledger, resource trajectory, event record, source citation, mission seed.

• States and recovery

  • Export-success state confirms that the log has been produced locally.
  • Export-failure state retains the completed debrief and provides a retry path without rerunning the mission.
  • A completed run remains reviewable locally for the current device context.
  • The debrief does not depict crew death; failure is represented as an equipment failure and survivable abort.

3. Functional Requirements

FR-1 — Run a mass-constrained outpost mission

As a Student Commander, I should run a four-person lunar or Martian outpost mission for ninety days using one lander with fixed cargo capacity, so that I experience mission engineering as a constrained system.

• Provenance: explicit.
• Access: anonymous; no account, sign-in, or personal data is required.
• Trigger/input: The student starts a mission from Landing and configures it in the loadout screen.
• Observable result: The simulation represents four crew, a selected lunar or Martian setting, one lander, and a ninety-sol mission.
• Failure/recovery: If a simulation condition prevents continued operation, the system represents a survivable equipment-failure abort and continues to debrief.
• Continuation: The student progresses to the dashboard and ultimately to debrief.

FR-2 — Use kilograms as the sole mission currency

As a Student Commander, I should make every loadout decision in kilograms rather than points or abstract coins, so that I learn the real currency of mission design.

• Provenance: explicit.
• Trigger/input: The student adds, removes, or compares loadout selections.
• Observable result: The system displays mass costs and the total landed mass in kilograms; it does not substitute points, coins, achievements, or abstract reward currency.
• Failure/recovery: A mass-overflow state explains that the lander cannot carry the selected configuration and requires revision.
• Continuation: The student adjusts the loadout or starts a valid mission.

FR-3 — Configure the pre-landing outpost loadout

As a Student Commander, I should spend the lander mass budget on habitat, power source, oxygen generator, carbon-dioxide scrubber, water processor, shielding, greenhouse, rover, spares, and food, so that I can make explicit engineering trade-offs before landing.

• Provenance: explicit.
• Trigger/input: The student selects or removes the named loadout items on the loadout screen.
• Observable result: The mass ledger and operating implications update for each selected item.
• Failure/recovery: The system blocks mission start when selected cargo exceeds 12,000 kg and identifies the over-capacity condition.
• Continuation: The student revises the loadout or begins the mission.

FR-4 — Preserve the intentional lander-capacity challenge

As a Student Commander, I should see that no build can include everything, so that I understand trade-offs are required rather than a problem to be tuned away.

• Provenance: explicit.
• Trigger/input: The student attempts or reviews a fully provisioned configuration.
• Observable result: The system represents the “everything” design as 24,386 kg against a 12,000 kg lander capacity.
• Failure/recovery: The over-capacity loadout cannot launch; the student must remove or alter selections.
• Continuation: The revised configuration remains visible in the mass ledger.

FR-5 — Model the stated engineering trade-offs

As a Student Commander, I should see power, shielding, recycling, greenhouse, hygiene, food, and morale trade-offs reflected in mission consequences, so that I can explain why an outpost is a closed loop.

• Provenance: explicit.
• Trigger/input: The student chooses loadout items and operating allocations.
• Observable result: The simulation reflects all of the following:
  • Greenhouse lights draw 8 kW continuously and can compete with oxygen generation.
  • One metre of regolith shielding costs 1,200 kg and halves radiation dose.
  • An unshielded ninety-day Moon mission accrues 81 mSv against a 600 mSv career limit.
  • Mars shielding is mandatory for a 500-day Mars mission comparison.
  • Closing air and water loops requires hardware mass up front and can save several thousand kilograms over sufficiently long missions.
  • 40 m² of hydroponics saves barely 150 kg of stored food while costing 1,950 kg and 8 kW, with value through morale and biology.
  • Laundry and dishwashing choices can change landed mass by about 1,000 kg, while rationing harms morale.
• Failure/recovery: Insufficient resource, power, or crew-hour conditions create alarms, events, equipment failures, or survivable abort as applicable.
• Continuation: The student uses dashboard data and event choices to adapt the run.

FR-6 — Allocate power and crew hours each sol

As a Student Commander, I should allocate power and crew hours each sol, so that I can operate the selected outpost under competing resource demands.

• Provenance: explicit.
• Trigger/input: The student sets power and crew-hour allocations on the dashboard.
• Observable result: The simulation advances with allocations affecting relevant resource, subsystem, and crew conditions.
• Failure/recovery: Inadequate allocations produce visible subsystem conditions, alarms, events, or abort criteria rather than unobservable failure.
• Continuation: The student modifies future-sol allocations, responds to an event, pauses, or advances the simulation.

FR-7 — Monitor resource and crew dashboards

As a Student Commander, I should monitor power, oxygen, carbon dioxide, water, food, radiation, crew health, and crew morale, so that I can identify the limiting resource.

• Provenance: explicit.
• Trigger/input: The student views the dashboard during a mission.
• Observable result: Current state and trend information are visible for all six resource categories plus crew health and morale.
• Failure/recovery: Alarms communicate affected systems through sound, shape, text, and colour; the student can inspect the condition and respond through allocations or Events.
• Continuation: The student makes an operating decision, opens an event, advances a sol, or pauses.

FR-8 — Respond to event cards and equipment failures

As a Student Commander, I should choose from multiple responses to failures and events, so that I can compare real operational consequences.

• Provenance: explicit.
• Trigger/input: A simulation condition or data-driven event triggers an event card.
• Observable result: The event presents decision options and their mass, resource, spare, crew-hour, and projected-sol consequences where applicable.
• Failure/recovery: A selected option applies its defined simulation state change; a resulting abort remains survivable and leads to debrief.
• Continuation: The student returns to the dashboard and sees the outcome in mission state and log.

FR-9 — Present the water-processor pressure-loss event

As a Student Commander, I should respond to the urine-line pressure-loss event using the stated options, so that I can learn why degraded recycling systems are an engineering feature.

• Provenance: explicit.
• Trigger/input: The water-processor event occurs.
• Observable result: The event states 40% throughput loss, three remaining spares, and a resupply window 22 sols away, then offers:
  • Replace the pump now: one spare and three crew-hours.
  • Run at half rate: water falls by 1.4 kg per sol.
  • Bypass to storage until resupply: potable reserve drops below its 30-sol margin.
• Failure/recovery: The chosen option is recorded and modifies the applicable simulation state.
• Continuation: The student returns to the dashboard and receives the note that ISS water processors were designed to keep running while degraded.
• Engineering-note constraint: Every event card ends with a transferable real-world engineering note of fewer than twelve words.

FR-10 — Apply live and cached NASA data to gameplay

As a Student Commander, I should have NASA open data influence mission conditions, so that the outpost environment is grounded in current and cached science data rather than fiction.

• Provenance: explicit.
• Trigger/input: The application starts while online or accesses a locally cached snapshot while offline.
• Observable result: The application uses:
  • DONKI solar flare and solar-particle-event feeds for in-game solar storms and crew sheltering.
  • DSCOVR/EPIC imagery for an Earth View morale action showing an Earth photograph.
  • Moon Trek and Mars Trek terrain tiles for Shackleton Crater rim and Jezero Crater placement.
  • PDS LRO/Diviner temperature data for cold-soak penalties in permanently shadowed regions.
• Failure/recovery: If live retrieval is unavailable, the system uses the latest cached snapshot where present and labels it CACHED.
• Continuation: The student continues the mission without a network dependency.

FR-11 — Cite and label NASA-backed elements

As a Student Commander, I should see a citation and LIVE or CACHED state for every data-driven element, so that I can distinguish sourced evidence from simulated interpretation.

• Provenance: explicit.
• Trigger/input: A NASA-backed terrain, solar, temperature, or Earth-image element is displayed.
• Observable result: The displayed element includes source name, retrieval date, and LIVE or CACHED state.
• Failure/recovery: A retrieval failure changes the state to CACHED when a snapshot exists; the product must not misleadingly display cached data as live.
• Continuation: The player may continue using the cited data in the mission.

FR-12 — Support offline classroom play

As a Student Commander, I should continue playing offline using cached NASA snapshots, so that classroom use does not depend on venue Wi-Fi.

• Provenance: explicit and required_inference.
• Trigger/input: The user launches or continues the application without network connectivity.
• Observable result: Locally stored mission state and cached NASA snapshots remain available with CACHED badges.
• Failure/recovery: Network failure does not terminate an active mission; the user is informed of cached status.
• Continuation: The student can configure, run, complete, and export the mission locally.

FR-13 — Provide deterministic, traceable simulation outcomes

As a Student Commander, I should receive identical mission outcomes when the same seed and decisions are used, so that classroom comparisons and engineering reasoning are reproducible.

• Provenance: explicit.
• Trigger/input: A mission starts with a given seed and receives a defined sequence of player decisions.
• Observable result: The deterministic, unit-tested engine produces identical mission outcomes for the same seed and decision sequence.
• Failure/recovery: Simulation defects are detectable through unit testing and a headless ninety-sol trace; the companion model reproduces the mass ledger so game and science do not drift apart.
• Continuation: The seed and outcomes are available in mission context and log.

FR-14 — Use NASA-traceable scientific constants

As a Student Commander, I should receive simulation outcomes based on NASA-traceable constants, so that the training remains scientifically grounded.

• Provenance: explicit.
• Observable result: The simulation preserves these stated constants and assumptions:
  • Per crew per day: 0.84 kg oxygen, 1 kg carbon dioxide, 3,035 kilocalories, and 3.52 kg drinking and food-preparation water.
  • Oxygen generation water-to-oxygen mass ratio: 9:8.
  • Lithium-hydroxide scrubbing: about 2 kg per kg of carbon dioxide.
  • ISS-class water recovery: 85–89%.
  • Radiation: approximately 0.64 mSv/day on the Martian surface and 0.9 mSv/day on the Moon.
  • NASA radiation career limit: 600 mSv.
  • Power assumptions: 20 kW habitat load, 2 kW keep-alive load, 60–70 kW ISRU peak, and a 40 kW reactor placed one kilometre from crew.
• Failure/recovery: Source-derived constants are maintained in traceable content and simulation configuration rather than silently changed through interface behavior.
• Continuation: The student interprets outcomes in dashboard, event, and debrief contexts.

FR-15 — Offer the Earth View morale action

As a Student Commander, I should use an Earth View action powered by DSCOVR/EPIC imagery, so that I can see an evidence-cited morale-related mission action.

• Provenance: explicit.
• Trigger/input: The student selects Earth View on the dashboard when the imagery is available.
• Observable result: The system displays an Earth photograph and applies the defined morale action within the simulation.
• Failure/recovery: Cached imagery remains usable offline with its source, retrieval date, and CACHED state.
• Continuation: The student returns to operating the current mission.

FR-16 — Complete a survivable mission outcome and export its log

As a Student Commander, I should receive a debrief that names the exact failed system and export the mission log at the end of every run, so that I have a record of my decisions and outcomes.

• Provenance: explicit.
• Trigger/input: The mission completes successfully or reaches a survivable abort condition.
• Observable result: Debrief names the exact failed system when applicable and provides a locally exportable mission log.
• Failure/recovery: If export fails, the completed debrief remains available and provides a retry path without rerunning the mission.
• Continuation: The student reviews the record or starts a new loadout.

FR-17 — Support teacher-led shared-seed instruction

As a Teacher, I should use a teacher pack containing a 45-minute lesson plan, shared mission seed, exit-ticket questions, and supported/core/extension differentiation tiers, so that I can run an accessible classroom activity.

• Provenance: explicit and required_inference.
• Trigger/input: The teacher prepares or conducts a classroom session.
• Observable result: The teacher pack supplies a shared mission seed so students can face the same solar storm, along with the stated lesson-plan, exit-ticket, and differentiation materials.
• Failure/recovery: The instructional activity remains usable without accounts or network dependence because students can use local, cached operation.
• Continuation: Students run comparable missions and provide exported logs for review.

FR-18 — Use mission logs as assessment artefacts

As a Teacher, I should receive a student-exported mission log, so that I can assess decisions, outcomes, and understanding without a teacher dashboard or student account.

• Provenance: explicit.
• Trigger/input: A student completes a run and exports the mission log.
• Observable result: The log provides a record of loadout choices, mission events, decisions, resource and mass context, outcome, and failed system where applicable.
• Failure/recovery: Export can be retried from debrief if it does not complete.
• Continuation: The teacher reviews the exported artefact alongside the lesson plan and exit-ticket questions.

FR-19 — Make current content JSON-authored

As a content author, I should have modules, events, crops, and scenarios represented in JSON, so that non-programmers can write and modify content.

• **