# hygia1122-susu/ares-cradle architecture

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

- Interactive diagram: https://gitdiagram.com/hygia1122-susu/ares-cradle
- Repository: https://github.com/hygia1122-susu/ares-cradle

## Overview

Ares Cradle is a Mars-outpost engineering simulator for young learners. Cadets manage power and life-support trade-offs during timed Sol scenarios, respond to environmental events, and receive a mission debrief. The React experience combines a 3D outpost with a mission-control HUD, driven by a shared simulation store and deterministic formulas. Classroom rooms and leaderboards, NASA weather with fallback data, and Django-backed stages and telemetry extend the core play loop. Backend view-to-model links are supported by the source index; some UI and backend routing details were not excerpted.

Main entry points: [`src/modules/store/useOutpostStore.ts`](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/store/useOutpostStore.ts) (Outpost State), [`src/modules/mission-control/MissionControlOverlay.tsx`](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/mission-control/MissionControlOverlay.tsx) (Mission HUD), [`backend/backend/urls.py`](https://github.com/hygia1122-susu/ares-cradle/blob/main/backend/backend/urls.py) (Django REST API), [`src/App.tsx`](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/App.tsx) (React App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Mission Experience"]
  node_app["React App<br/>[App.tsx]"]
  node_mars_scene["3D Outpost<br/>[MarsCanvas.tsx]"]
  node_rover["Rover Interaction<br/>[MarsRover.tsx]"]
  node_astronaut["Astronaut Controls"]
  node_mission_hud["Mission HUD"]
  node_stage_banner["Stage Banner<br/>[StageBanner.tsx]"]
  node_classroom["Classroom Tools<br/>[ClassroomModal.tsx]"]
  node_survival_tools["Survival UI"]
end

subgraph group_simulation["Simulation Runtime"]
  node_store["Outpost State<br/>[useOutpostStore.ts]"]
  node_formulas["Simulation Math<br/>[formulas.ts]"]
  node_weather["Mars Weather"]
  node_sound["Sound Engine<br/>[soundEngine.ts]"]
end

subgraph group_services["Mission Services"]
  node_mission_contract["Mission Service Contract<br/>[IMissionService.ts]"]
  node_mock_service["Mock Mission Service"]
  node_django_service["Django Mission Adapter"]
  node_hybrid_api["Classroom API Client<br/>[apiClient.ts]"]
end

subgraph group_backend["Django Backend"]
  node_django["Django REST API<br/>[urls.py]"]
  node_stage_views["Stage Endpoints<br/>[views.py]"]
  node_stage_models[("Stage Configurations<br/>[models.py]")]
  node_telemetry_views["Telemetry Endpoints<br/>[views.py]"]
  node_telemetry_models[("Telemetry Records<br/>[models.py]")]
end

node_cadet(("Cadet"))
node_nasa["NASA InSight"]

node_cadet -->|"starts"| node_app
node_app -->|"renders"| node_mars_scene
node_app -->|"renders"| node_mission_hud
node_mars_scene -->|"renders"| node_rover
node_mars_scene -->|"renders"| node_astronaut
node_mission_hud -->|"reads state"| node_store
node_mission_hud -->|"renders"| node_stage_banner
node_mission_hud -->|"renders"| node_classroom
node_mission_hud -->|"renders"| node_survival_tools
node_rover -->|"updates state"| node_store
node_rover -->|"plays effects"| node_sound
node_astronaut -->|"updates state"| node_store
node_store -->|"calculates outcomes"| node_formulas
node_store -->|"fetches telemetry"| node_weather
node_store -->|"plays cues"| node_sound
node_stage_banner -->|"reads state"| node_store
node_classroom -->|"requests rooms"| node_hybrid_api
node_store -->|"uses service"| node_mission_contract
node_mission_contract -->|"implemented by"| node_mock_service
node_mission_contract -->|"implemented by"| node_django_service
node_django_service -->|"calls REST API"| node_django
node_hybrid_api -->|"calls REST API"| node_django
node_weather -->|"fetches weather"| node_nasa
node_django -.->|"routes requests"| node_stage_views
node_django -.->|"routes requests"| node_telemetry_views
node_stage_views -->|"reads stages"| node_stage_models
node_stage_views -->|"serializes stages"| node_stage_models
node_telemetry_views -->|"reads records"| node_telemetry_models
node_telemetry_views -->|"serializes records"| node_telemetry_models

click node_app "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/App.tsx"
click node_mars_scene "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/outpost-3d/MarsCanvas.tsx"
click node_rover "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/outpost-3d/MarsRover.tsx"
click node_astronaut "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/character/AstronautPlayer.tsx"
click node_mission_hud "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/mission-control/MissionControlOverlay.tsx"
click node_stage_banner "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/mission-control/StageBanner.tsx"
click node_classroom "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/survival-ui/ClassroomModal.tsx"
click node_survival_tools "https://github.com/hygia1122-susu/ares-cradle/tree/main/src/modules/survival-ui"
click node_store "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/store/useOutpostStore.ts"
click node_formulas "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/simulation-engine/formulas.ts"
click node_weather "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/story-engine/services/marsWeatherService.ts"
click node_sound "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/audio/soundEngine.ts"
click node_mission_contract "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/services/api/IMissionService.ts"
click node_mock_service "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/services/api/MockMissionService.ts"
click node_django_service "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/services/api/DjangoMissionService.ts"
click node_hybrid_api "https://github.com/hygia1122-susu/ares-cradle/blob/main/src/services/api/apiClient.ts"
click node_django "https://github.com/hygia1122-susu/ares-cradle/blob/main/backend/backend/urls.py"
click node_stage_views "https://github.com/hygia1122-susu/ares-cradle/blob/main/backend/apps/simulation/views.py"
click node_stage_models "https://github.com/hygia1122-susu/ares-cradle/blob/main/backend/apps/simulation/models.py"
click node_telemetry_views "https://github.com/hygia1122-susu/ares-cradle/blob/main/backend/apps/telemetry/views.py"
click node_telemetry_models "https://github.com/hygia1122-susu/ares-cradle/blob/main/backend/apps/telemetry/models.py"

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_mars_scene,node_rover,node_astronaut,node_mission_hud,node_stage_banner,node_classroom,node_survival_tools toneBlue
class node_store,node_formulas,node_weather,node_sound toneAmber
class node_mission_contract,node_mock_service,node_django_service,node_hybrid_api toneMint
class node_django,node_stage_views,node_stage_models,node_telemetry_views,node_telemetry_models toneRose
class node_cadet,node_nasa toneIndigo
```

## Components

### Mission Experience

- [React App](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/App.tsx): `src/App.tsx`
- [3D Outpost](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/outpost-3d/MarsCanvas.tsx): `src/modules/outpost-3d/MarsCanvas.tsx`
- [Rover Interaction](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/outpost-3d/MarsRover.tsx): `src/modules/outpost-3d/MarsRover.tsx`
- [Astronaut Controls](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/character/AstronautPlayer.tsx): `src/modules/character/AstronautPlayer.tsx`
- [Mission HUD](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/mission-control/MissionControlOverlay.tsx): `src/modules/mission-control/MissionControlOverlay.tsx`
- [Stage Banner](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/mission-control/StageBanner.tsx): `src/modules/mission-control/StageBanner.tsx`
- [Classroom Tools](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/survival-ui/ClassroomModal.tsx): `src/modules/survival-ui/ClassroomModal.tsx`
- [Survival UI](https://github.com/hygia1122-susu/ares-cradle/tree/main/src/modules/survival-ui): `src/modules/survival-ui`

### Simulation Runtime

- [Outpost State](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/store/useOutpostStore.ts): `src/modules/store/useOutpostStore.ts`
- [Simulation Math](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/simulation-engine/formulas.ts): `src/modules/simulation-engine/formulas.ts`
- [Mars Weather](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/story-engine/services/marsWeatherService.ts): `src/modules/story-engine/services/marsWeatherService.ts`
- [Sound Engine](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/modules/audio/soundEngine.ts): `src/modules/audio/soundEngine.ts`

### Mission Services

- [Mission Service Contract](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/services/api/IMissionService.ts): `src/services/api/IMissionService.ts`
- [Mock Mission Service](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/services/api/MockMissionService.ts): `src/services/api/MockMissionService.ts`
- [Django Mission Adapter](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/services/api/DjangoMissionService.ts): `src/services/api/DjangoMissionService.ts`
- [Classroom API Client](https://github.com/hygia1122-susu/ares-cradle/blob/main/src/services/api/apiClient.ts): `src/services/api/apiClient.ts`

### Django Backend

- [Django REST API](https://github.com/hygia1122-susu/ares-cradle/blob/main/backend/backend/urls.py): `backend/backend/urls.py`
- [Stage Endpoints](https://github.com/hygia1122-susu/ares-cradle/blob/main/backend/apps/simulation/views.py): `backend/apps/simulation/views.py`
- [Stage Configurations](https://github.com/hygia1122-susu/ares-cradle/blob/main/backend/apps/simulation/models.py): `backend/apps/simulation/models.py`
- [Telemetry Endpoints](https://github.com/hygia1122-susu/ares-cradle/blob/main/backend/apps/telemetry/views.py): `backend/apps/telemetry/views.py`
- [Telemetry Records](https://github.com/hygia1122-susu/ares-cradle/blob/main/backend/apps/telemetry/models.py): `backend/apps/telemetry/models.py`

### Other components

- **Cadet**
- **NASA InSight**

## Connections

- Cadet → React App: starts
- React App → 3D Outpost: renders (evidence: `src/App.tsx`)
- React App → Mission HUD: renders (evidence: `src/App.tsx`)
- 3D Outpost → Rover Interaction: renders (evidence: `src/modules/outpost-3d/MarsCanvas.tsx`)
- 3D Outpost → Astronaut Controls: renders (evidence: `src/modules/outpost-3d/MarsCanvas.tsx`)
- Mission HUD → Outpost State: reads state (evidence: `src/modules/mission-control/MissionControlOverlay.tsx`)
- Mission HUD → Stage Banner: renders (evidence: `src/modules/mission-control/MissionControlOverlay.tsx`)
- Mission HUD → Classroom Tools: renders (evidence: `src/modules/mission-control/MissionControlOverlay.tsx`)
- Mission HUD → Survival UI: renders (evidence: `src/modules/mission-control/MissionControlOverlay.tsx`)
- Rover Interaction → Outpost State: updates state (evidence: `src/modules/outpost-3d/MarsRover.tsx`)
- Rover Interaction → Sound Engine: plays effects (evidence: `src/modules/outpost-3d/MarsRover.tsx`)
- Astronaut Controls → Outpost State: updates state (evidence: `src/modules/character/AstronautPlayer.tsx`)
- Outpost State → Simulation Math: calculates outcomes (evidence: `src/modules/store/useOutpostStore.ts`)
- Outpost State → Mars Weather: fetches telemetry (evidence: `src/modules/store/useOutpostStore.ts`)
- Outpost State → Sound Engine: plays cues (evidence: `src/modules/store/useOutpostStore.ts`)
- Stage Banner → Outpost State: reads state (evidence: `src/modules/mission-control/StageBanner.tsx`)
- Classroom Tools → Classroom API Client: requests rooms (evidence: `src/modules/survival-ui/ClassroomModal.tsx`)
- Outpost State → Mission Service Contract: uses service (evidence: `src/modules/store/useOutpostStore.ts`)
- Mission Service Contract → Mock Mission Service: implemented by (evidence: `src/services/api/index.ts`)
- Mission Service Contract → Django Mission Adapter: implemented by (evidence: `src/services/api/index.ts`)
- Django Mission Adapter → Django REST API: calls REST API (evidence: `src/services/api/DjangoMissionService.ts`)
- Classroom API Client → Django REST API: calls REST API (evidence: `src/services/api/apiClient.ts`)
- Mars Weather → NASA InSight: fetches weather (evidence: `src/modules/story-engine/services/marsWeatherService.ts`)
- Django REST API → Stage Endpoints: routes requests
- Django REST API → Telemetry Endpoints: routes requests
- Stage Endpoints → Stage Configurations: reads stages (evidence: `backend/apps/simulation/views.py`)
- Stage Endpoints → Stage Configurations: serializes stages (evidence: `backend/apps/simulation/views.py`)
- Telemetry Endpoints → Telemetry Records: reads records (evidence: `backend/apps/telemetry/views.py`)
- Telemetry Endpoints → Telemetry Records: serializes records (evidence: `backend/apps/telemetry/views.py`)