# thai-max-gif/ares-cradle architecture

> Architecture diagram of the GitHub repository thai-max-gif/ares-cradle, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thai-max-gif/ares-cradle
- Repository: https://github.com/thai-max-gif/ares-cradle

## Overview

Ares Cradle is a browser-based Mars outpost simulator and STEM explorer. Cadets enter through the mission-control interface, explore the 3D outpost, manage survival resources and equipment, and progress through story objectives and science activities. The documented experience also includes NASA weather telemetry, classroom rankings, and a sandbox; some of these capabilities are represented by directory-level nodes because their wiring was not sampled. The graph follows visible imports and calls where available; omitted source limits certainty about additional connections.

Main entry points: [`src/modules/store/useOutpostStore.ts`](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/store/useOutpostStore.ts) (Outpost Simulation State), [`src/modules/mission-control/MissionControlOverlay.tsx`](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/mission-control/MissionControlOverlay.tsx) (Mission Control HUD), [`src/services/api/IMissionService.ts`](https://github.com/thai-max-gif/ares-cradle/blob/main/src/services/api/IMissionService.ts) (Mission Service Contract), [`src/App.tsx`](https://github.com/thai-max-gif/ares-cradle/blob/main/src/App.tsx) (Application Shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Game Experience"]
  node_app["Application Shell<br/>[App.tsx]"]
  node_mission_ui["Mission Control HUD"]
  node_survival_ui["Survival UI"]
  node_backpack["Backpack<br/>[BackpackModal.tsx]"]
  node_item_catalog["Equipment Catalog<br/>[itemRegistry.ts]"]
  node_audio["Sound Engine<br/>[soundEngine.ts]"]
end

subgraph group_simulation["Simulation and World"]
  node_world_canvas["Mars World<br/>[MarsCanvas.tsx]"]
  node_rover["Rover<br/>[MarsRover.tsx]"]
  node_physics["Movement Physics<br/>[physicsEngine.ts]"]
  node_outpost_state["Outpost Simulation State<br/>[useOutpostStore.ts]"]
  node_formulas["Simulation Formulas<br/>[formulas.ts]"]
  node_weather["Mars Weather"]
end

subgraph group_story["Story and Learning"]
  node_story_state["Story Progress<br/>[useStoryStore.ts]"]
  node_story_ui["Story and Science UI"]
  node_lab["Lab Showcase"]
  node_classroom["Classroom Features<br/>[ClassroomModal.tsx]"]
end

subgraph group_services["Mission Services"]
  node_service_contract["Mission Service Contract<br/>[IMissionService.ts]"]
  node_mock_service["Demo Mission Service"]
  node_django_service["Django Mission Adapter"]
  node_backend_sim[("Stage Data<br/>[models.py]")]
  node_backend_telemetry[("Telemetry Data<br/>[models.py]")]
end

node_cadet(("Cadet"))

node_cadet -->|"opens"| node_app
node_app -->|"renders"| node_world_canvas
node_app -->|"renders"| node_mission_ui
node_cadet -.->|"uses"| node_mission_ui
node_mission_ui -->|"reads and updates"| node_outpost_state
node_mission_ui -->|"renders"| node_backpack
node_mission_ui -->|"renders"| node_story_ui
node_mission_ui -->|"renders"| node_classroom
node_world_canvas -->|"renders"| node_rover
node_rover -->|"updates"| node_outpost_state
node_rover -->|"uses"| node_physics
node_world_canvas -->|"reads"| node_outpost_state
node_outpost_state -->|"uses"| node_formulas
node_outpost_state -->|"fetches"| node_weather
node_outpost_state -->|"reads"| node_story_state
node_outpost_state -->|"uses"| node_item_catalog
node_backpack -->|"displays items"| node_item_catalog
node_backpack -->|"manages equipment"| node_outpost_state
node_story_state -->|"plays feedback"| node_audio
node_lab -->|"reads"| node_outpost_state
node_lab -->|"reads"| node_story_state
node_mock_service -->|"implements"| node_service_contract
node_django_service -->|"implements"| node_service_contract
node_classroom -.->|"uses rankings"| node_service_contract
node_service_contract -.->|"retrieves stage data"| node_backend_sim
node_service_contract -.->|"submits telemetry"| node_backend_telemetry

click node_app "https://github.com/thai-max-gif/ares-cradle/blob/main/src/App.tsx"
click node_mission_ui "https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/mission-control/MissionControlOverlay.tsx"
click node_survival_ui "https://github.com/thai-max-gif/ares-cradle/tree/main/src/modules/survival-ui"
click node_backpack "https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/survival-ui/BackpackModal.tsx"
click node_item_catalog "https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/survival-ui/itemRegistry.ts"
click node_world_canvas "https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/outpost-3d/MarsCanvas.tsx"
click node_rover "https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/outpost-3d/MarsRover.tsx"
click node_physics "https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/character/physicsEngine.ts"
click node_outpost_state "https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/store/useOutpostStore.ts"
click node_formulas "https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/simulation-engine/formulas.ts"
click node_weather "https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/story-engine/services/marsWeatherService.ts"
click node_story_state "https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/store/useStoryStore.ts"
click node_story_ui "https://github.com/thai-max-gif/ares-cradle/tree/main/src/modules/story-engine/components"
click node_lab "https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/showcase/LabShowcaseModal.tsx"
click node_audio "https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/audio/soundEngine.ts"
click node_service_contract "https://github.com/thai-max-gif/ares-cradle/blob/main/src/services/api/IMissionService.ts"
click node_mock_service "https://github.com/thai-max-gif/ares-cradle/blob/main/src/services/api/MockMissionService.ts"
click node_django_service "https://github.com/thai-max-gif/ares-cradle/blob/main/src/services/api/DjangoMissionService.ts"
click node_backend_sim "https://github.com/thai-max-gif/ares-cradle/blob/main/backend/apps/simulation/models.py"
click node_backend_telemetry "https://github.com/thai-max-gif/ares-cradle/blob/main/backend/apps/telemetry/models.py"
click node_classroom "https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/survival-ui/ClassroomModal.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_mission_ui,node_survival_ui,node_backpack,node_item_catalog,node_audio toneBlue
class node_world_canvas,node_rover,node_physics,node_outpost_state,node_formulas,node_weather toneAmber
class node_story_state,node_story_ui,node_lab,node_classroom toneMint
class node_service_contract,node_mock_service,node_django_service,node_backend_sim,node_backend_telemetry toneRose
class node_cadet toneIndigo
```

## Components

### Game Experience

- [Application Shell](https://github.com/thai-max-gif/ares-cradle/blob/main/src/App.tsx): `src/App.tsx`
- [Mission Control HUD](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/mission-control/MissionControlOverlay.tsx): `src/modules/mission-control/MissionControlOverlay.tsx`
- [Survival UI](https://github.com/thai-max-gif/ares-cradle/tree/main/src/modules/survival-ui): `src/modules/survival-ui`
- [Backpack](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/survival-ui/BackpackModal.tsx): `src/modules/survival-ui/BackpackModal.tsx`
- [Equipment Catalog](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/survival-ui/itemRegistry.ts): `src/modules/survival-ui/itemRegistry.ts`
- [Sound Engine](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/audio/soundEngine.ts): `src/modules/audio/soundEngine.ts`

### Simulation and World

- [Mars World](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/outpost-3d/MarsCanvas.tsx): `src/modules/outpost-3d/MarsCanvas.tsx`
- [Rover](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/outpost-3d/MarsRover.tsx): `src/modules/outpost-3d/MarsRover.tsx`
- [Movement Physics](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/character/physicsEngine.ts): `src/modules/character/physicsEngine.ts`
- [Outpost Simulation State](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/store/useOutpostStore.ts): `src/modules/store/useOutpostStore.ts`
- [Simulation Formulas](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/simulation-engine/formulas.ts): `src/modules/simulation-engine/formulas.ts`
- [Mars Weather](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/story-engine/services/marsWeatherService.ts): `src/modules/story-engine/services/marsWeatherService.ts`

### Story and Learning

- [Story Progress](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/store/useStoryStore.ts): `src/modules/store/useStoryStore.ts`
- [Story and Science UI](https://github.com/thai-max-gif/ares-cradle/tree/main/src/modules/story-engine/components): `src/modules/story-engine/components`
- [Lab Showcase](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/showcase/LabShowcaseModal.tsx): `src/modules/showcase/LabShowcaseModal.tsx`
- [Classroom Features](https://github.com/thai-max-gif/ares-cradle/blob/main/src/modules/survival-ui/ClassroomModal.tsx): `src/modules/survival-ui/ClassroomModal.tsx`

### Mission Services

- [Mission Service Contract](https://github.com/thai-max-gif/ares-cradle/blob/main/src/services/api/IMissionService.ts): `src/services/api/IMissionService.ts`
- [Demo Mission Service](https://github.com/thai-max-gif/ares-cradle/blob/main/src/services/api/MockMissionService.ts): `src/services/api/MockMissionService.ts`
- [Django Mission Adapter](https://github.com/thai-max-gif/ares-cradle/blob/main/src/services/api/DjangoMissionService.ts): `src/services/api/DjangoMissionService.ts`
- [Stage Data](https://github.com/thai-max-gif/ares-cradle/blob/main/backend/apps/simulation/models.py): `backend/apps/simulation/models.py`
- [Telemetry Data](https://github.com/thai-max-gif/ares-cradle/blob/main/backend/apps/telemetry/models.py): `backend/apps/telemetry/models.py`

### Other components

- **Cadet**

## Connections

- Cadet → Application Shell: opens
- Application Shell → Mars World: renders (evidence: `src/App.tsx`)
- Application Shell → Mission Control HUD: renders (evidence: `src/App.tsx`)
- Cadet → Mission Control HUD: uses
- Mission Control HUD → Outpost Simulation State: reads and updates (evidence: `src/modules/mission-control/MissionControlOverlay.tsx`)
- Mission Control HUD → Backpack: renders (evidence: `src/modules/mission-control/MissionControlOverlay.tsx`)
- Mission Control HUD → Story and Science UI: renders (evidence: `src/modules/mission-control/MissionControlOverlay.tsx`)
- Mission Control HUD → Classroom Features: renders (evidence: `src/modules/mission-control/MissionControlOverlay.tsx`)
- Mars World → Rover: renders (evidence: `src/modules/outpost-3d/MarsCanvas.tsx`)
- Rover → Outpost Simulation State: updates (evidence: `src/modules/outpost-3d/MarsRover.tsx`)
- Rover → Movement Physics: uses (evidence: `src/modules/outpost-3d/MarsRover.tsx`)
- Mars World → Outpost Simulation State: reads (evidence: `src/modules/outpost-3d/MarsCanvas.tsx`)
- Outpost Simulation State → Simulation Formulas: uses (evidence: `src/modules/store/useOutpostStore.ts`)
- Outpost Simulation State → Mars Weather: fetches (evidence: `src/modules/store/useOutpostStore.ts`)
- Outpost Simulation State → Story Progress: reads (evidence: `src/modules/store/useOutpostStore.ts`)
- Outpost Simulation State → Equipment Catalog: uses (evidence: `src/modules/store/useOutpostStore.ts`)
- Backpack → Equipment Catalog: displays items (evidence: `src/modules/survival-ui/BackpackModal.tsx`)
- Backpack → Outpost Simulation State: manages equipment (evidence: `src/modules/survival-ui/BackpackModal.tsx`)
- Story Progress → Sound Engine: plays feedback (evidence: `src/modules/store/useStoryStore.ts`)
- Lab Showcase → Outpost Simulation State: reads (evidence: `src/modules/showcase/LabShowcaseModal.tsx`)
- Lab Showcase → Story Progress: reads (evidence: `src/modules/showcase/LabShowcaseModal.tsx`)
- Demo Mission Service → Mission Service Contract: implements (evidence: `src/services/api/MockMissionService.ts`)
- Django Mission Adapter → Mission Service Contract: implements (evidence: `src/services/api/DjangoMissionService.ts`)
- Classroom Features → Mission Service Contract: uses rankings
- Mission Service Contract → Stage Data: retrieves stage data
- Mission Service Contract → Telemetry Data: submits telemetry