# Moon Courier Crisis

Technical documentation

A game about a courier on the Moon. Mission selection, routes, radio events and shift results. React handles the interface; Phaser handles the game scenes. It runs in the browser without a backend.

Source version: `b6b24e1215368727b8ad002919aa7989c04ddfdd`

Retained stage history: August 2026; development start is unknown. Demo published: 7 September 2026.

[Project notes](https://portfolio.komaroff-dev.ru/en/projects/moon/) · [Online documentation](https://portfolio.komaroff-dev.ru/en/projects/moon/docs/)

[Demo](https://moon.komaroff-dev.ru/)

[Source repository](https://github.com/komaroffsergei/moon-rover)

## Task

The React interface and Phaser scenes share mission state. Showing the result and restarting must not leave state from the previous attempt.

A browser game with route controls.

## Work done

- Connected the React interface to Phaser game scenes.
- Routes, events, briefing, radio panel and mission restart.
- Build, asset checks and mobile layout for the pre-game screens.

## Stack

| Technology | Role |
| --- | --- |
| React | Briefing, panels, hints and mission result. |
| Phaser | Canvas, game loop, scenes, routes and objects. |
| TypeScript / Vite | Game model, production build and asset checks. |

## Architecture and decisions

- React handles the interface; Phaser handles the canvas and game loop.
- Level selection, briefing, mission and result are separate states.
- After a defeat, replay returns to the briefing; a new shift starts through an explicit action.

### Components of the published demo

![Components of the published demo](https://portfolio.komaroff-dev.ru/evidence/moon/diagrams/components.svg)

[Mermaid source](https://portfolio.komaroff-dev.ru/evidence/moon/diagrams/components.mmd)

### Main workflow

![Main workflow](https://portfolio.komaroff-dev.ru/evidence/moon/diagrams/scenario.svg)

[Mermaid source](https://portfolio.komaroff-dev.ru/evidence/moon/diagrams/scenario.mmd)

### Deployment of the published version

![Deployment of the published version](https://portfolio.komaroff-dev.ru/evidence/moon/diagrams/deployment.svg)

[Mermaid source](https://portfolio.komaroff-dev.ru/evidence/moon/diagrams/deployment.mmd)

## Code map

| Feature | Screen / API | Module | Data / verification |
| --- | --- | --- | --- |
| Startup | Selection / briefing | src/ui/store/gameStore.ts; src/game/createGame.ts | level config; production browser QA |
| Route | Canvas | src/game/MapScene.ts; simulation/routing/confirmRouteDraft.ts | routeDraft / findWeightedRoute; actual route |
| Events | Radio panel | simulation/radio/createRadioJournal.ts | formatRadioEvent; game history |
| Simulation | Mission / result | simulation/createSimulationEngine.ts; clock/fixedStepClock.ts | courier and hub states; unit suite |
| Mobile view | Preflight / radio | React styles / src/ui | 390px; no-overflow QA |

Before changing a feature, trace its interface, API, state and storage dependencies. Check inputs, errors, retries and related workflows. Update the map and affected diagrams alongside the code, rerun the related checks and attach evidence for the source version.

## Workflows and API

1. Choose a level and read the briefing.
2. Start a shift, select a courier and assign a route.
3. Open the radio panel and follow a mission event.
4. Wait for the result, select replay and start a new shift from the briefing.

## Verification

- Original full suite: 464 unit tests, 20 E2E tests and one skipped test. Production build, asset checks and mobile QA were repeated after the CSS change.
- Production build / assets
- Desktop route and actual defeat/replay
- Mobile levels, briefing, radio; no overflow
- No verified GitHub CI run is available for this SHA; the listed evidence covers local checks and published-version scenarios. Historical CI links, where available, are labeled separately.

## Results and measurements

- 15 meaningful screenshots of the actual interface retained.
- Each screenshot includes its date, scenario and code revision.
- No separate backend process runs on the VPS: Nginx serves static files. Shared Nginx resources cannot fairly be attributed to a single site.
- 6 scenario repetitions measured; median 61.0 ms, maximum 1770 ms. Timing includes the browser and HTTPS; methodology and limitations are included.

These checks apply to the listed version. Business metrics and model quality on an independent dataset were not measured.

![Shared VPS resource context for the static demo · 2026-09-07T01:08:27 — 01:11:22 UTC](https://portfolio.komaroff-dev.ru/evidence/moon/charts/resources.svg)

[Shared VPS resource context for the static demo · 2026-09-07T01:08:27 — 01:11:22 UTC: source data](https://portfolio.komaroff-dev.ru/evidence/moon/metrics/measurements.json)

![Measured scenario repetitions over HTTPS · 2026-09-07T01:08:36 UTC; methodology limitations in JSON](https://portfolio.komaroff-dev.ru/evidence/moon/charts/scenario-time.svg)

[Measured scenario repetitions over HTTPS · 2026-09-07T01:08:36 UTC; methodology limitations in JSON: source data](https://portfolio.komaroff-dev.ru/evidence/moon/metrics/measurements.json)

## Limitations

- Route control is designed for a mouse and keyboard. Mobile screens are responsive, but full touch-based routing is not claimed.
- The first available commit is a baseline of an already completed stage, so it does not establish when development began.
- No external integrations or server database: the mission runs in the browser.

## Running and operating

The game runs in the browser. The server serves static files; there are no payment or AI integrations.

The production build, TypeScript checks and asset checks run outside the VPS. Nginx serves the resulting directory; there is no persistent backend.

Verify actual mission states without replacing the outcome through test hooks. Evidence includes a real defeat and replay. Screenshots from different releases are labeled individually; the mobile change affects layout rather than game mechanics.

Builds run outside the VPS; the server receives static files and versioned images. Secrets are kept separately. Logs rotate; changing log options requires recreating the container. No server-wide docker prune.

The code map links a screen or API to its module and data. A change needs those links checked, the map updated and the affected flows rerun: normal path, error, retry and reset. Diagrams can go stale, so their version is listed alongside them.

Rollback checked at 2026-09-07T00:59:40.423436+00:00: 20260907-verified → 20260907b → 20260907-verified. HTTPS, readiness and SHA were confirmed after each switch. This checks configuration and artifacts at one verified SHA; no reverse database migration was performed.

## Screenshot index

1. [Mission selection](https://portfolio.komaroff-dev.ru/evidence/moon/full/01-level-select.png) — 2026-09-07T01:05:40.267729+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

2. [Briefing and shift conditions](https://portfolio.komaroff-dev.ru/evidence/moon/full/02-briefing.png) — 2026-09-07T01:05:47.034942+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

3. [Map of the running mission](https://portfolio.komaroff-dev.ru/evidence/moon/full/03-mission.png) — 2026-09-07T01:07:40.196399+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

4. [Pause and shift controls](https://portfolio.komaroff-dev.ru/evidence/moon/full/04-pause.png) — 2026-09-07T01:07:48.861345+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

5. [Radio events](https://portfolio.komaroff-dev.ru/evidence/moon/full/05-radio.png) — 2026-09-07T01:17:22.254481+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

6. [Courier selection](https://portfolio.komaroff-dev.ru/evidence/moon/full/06-rover.png) — 2026-09-07T01:12:20.586436+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

7. [Assigned route](https://portfolio.komaroff-dev.ru/evidence/moon/full/07-route.png) — 2026-09-07T01:12:36.010812+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

8. [Arrival at a waypoint](https://portfolio.komaroff-dev.ru/evidence/moon/full/08-arrival.png) — 2026-09-07T01:17:00.583707+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

9. [Mobile mission selection](https://portfolio.komaroff-dev.ru/evidence/moon/full/09-mobile-levels.png) — 2026-09-06T23:50:44.174550+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

10. [Mobile briefing](https://portfolio.komaroff-dev.ru/evidence/moon/full/10-mobile-briefing.png) — 2026-09-06T23:50:44.760211+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

11. [Map on a narrow screen](https://portfolio.komaroff-dev.ru/evidence/moon/full/11-mobile-map.png) — 2026-09-06T23:50:47.754791+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

12. [Mobile radio panel](https://portfolio.komaroff-dev.ru/evidence/moon/full/12-mobile-radio.png) — 2026-09-06T23:50:48.366580+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

13. [Actual outcome: mission lost](https://portfolio.komaroff-dev.ru/evidence/moon/full/14-outcome.png) — 2026-09-07T01:10:26.052432+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

14. [Replay returns to the briefing](https://portfolio.komaroff-dev.ru/evidence/moon/full/15-replay-briefing.png) — 2026-09-07T01:11:14.388480+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

15. [New shift after replay](https://portfolio.komaroff-dev.ru/evidence/moon/full/16-restarted-mission.png) — 2026-09-07T01:11:35.021611+00:00, source `b6b24e1215368727b8ad002919aa7989c04ddfdd`.

Screenshots, diagrams and the original evidence package retain their source language. Captions and this document are translated into English.

[Original evidence package](https://portfolio.komaroff-dev.ru/downloads/moon-evidence.zip)