# addey34/galaxy-3d architecture

> Architecture diagram of the GitHub repository addey34/galaxy-3d, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/addey34/galaxy-3d
- Repository: https://github.com/addey34/galaxy-3d

## Overview

Galaxy is a browser-based 3D solar-system explorer with educational compressed-scale and true astronomical-scale exploration modes. Users navigate celestial bodies, change the simulated date, inspect scientific positions and surface detail, and use optional tours, events, and shareable links. The main runtime separates application orchestration, ephemeris and scale calculations, Three.js scene/rendering, and interaction UI. The README documents several product capabilities whose implementation files were not sampled; those are represented at their supported directory level, with links limited to documented relationships.

Main entry points: [`src/SolarSystemApp.ts`](https://github.com/addey34/galaxy-3d/blob/main/src/SolarSystemApp.ts) (Solar system app), [`src/MainSolarSystemApp.ts`](https://github.com/addey34/galaxy-3d/blob/main/src/MainSolarSystemApp.ts) (Main app), [`src/components/systems/SceneSystem.ts`](https://github.com/addey34/galaxy-3d/blob/main/src/components/systems/SceneSystem.ts) (Scene system), [`src/components/celestial/CelestialObject.ts`](https://github.com/addey34/galaxy-3d/blob/main/src/components/celestial/CelestialObject.ts) (Celestial objects)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App runtime"]
  node_app["Main app"]
  node_solar_app["Solar system app<br/>[SolarSystemApp.ts]"]
end

subgraph group_astronomy["Astronomy and data"]
  node_catalog[("Body catalogue<br/>[bodies.ts]")]
  node_registry[("Entity registry<br/>[index.ts]")]
  node_ephemeris["Horizons ephemeris"]
  node_orbital["Orbital mechanics"]
  node_scale["Scale conversion<br/>[ScaleService.ts]"]
  node_simulation["Simulation clock<br/>[SimulationClock.ts]"]
end

subgraph group_rendering["Scene and rendering"]
  node_scene["Scene system<br/>[SceneSystem.ts]"]
  node_textures["Texture system<br/>[TextureSystem.ts]"]
  node_celestial["Celestial objects<br/>[CelestialObject.ts]"]
  node_surface["Surface imagery"]
  node_camera["Camera controls<br/>[CameraSystem.ts]"]
  node_animation["Animation system<br/>[AnimationSystem.ts]"]
end

subgraph group_interaction["Exploration features"]
  node_ui["Exploration UI"]
  node_tours["Guided tours<br/>[tourEngine.ts]"]
  node_events["Earth events<br/>[earthEvents.ts]"]
end

node_visitor(("Explorer"))
node_external_catalogs[("Event catalogues")]

node_visitor -->|"uses"| node_app
node_app -->|"starts"| node_solar_app
node_solar_app -->|"initializes"| node_scene
node_solar_app -->|"coordinates"| node_camera
node_solar_app -->|"coordinates"| node_animation
node_solar_app -->|"uses"| node_ephemeris
node_solar_app -->|"uses"| node_orbital
node_solar_app -->|"uses"| node_simulation
node_registry -->|"provides entities"| node_catalog
node_scene -->|"configures"| node_textures
node_scene -->|"constructs"| node_celestial
node_celestial -->|"uses"| node_scale
node_surface -.->|"loads tiles"| node_external_catalogs
node_app -->|"provides controls"| node_ui
node_app -->|"offers tours"| node_tours
node_app -->|"offers events"| node_events
node_events -->|"reads reports"| node_external_catalogs
node_ui -.->|"selects dates"| node_ephemeris
node_visitor -.->|"catalogues USGS / NASA EONET"| node_external_catalogs

click node_app "https://github.com/addey34/galaxy-3d/blob/main/src/MainSolarSystemApp.ts"
click node_solar_app "https://github.com/addey34/galaxy-3d/blob/main/src/SolarSystemApp.ts"
click node_catalog "https://github.com/addey34/galaxy-3d/blob/main/src/config/bodies.ts"
click node_registry "https://github.com/addey34/galaxy-3d/blob/main/src/registry/entities/index.ts"
click node_ephemeris "https://github.com/addey34/galaxy-3d/blob/main/src/core/HorizonsEphemerisService.ts"
click node_orbital "https://github.com/addey34/galaxy-3d/blob/main/src/core/OrbitalMechanics.ts"
click node_scale "https://github.com/addey34/galaxy-3d/blob/main/src/core/ScaleService.ts"
click node_simulation "https://github.com/addey34/galaxy-3d/blob/main/src/core/SimulationClock.ts"
click node_scene "https://github.com/addey34/galaxy-3d/blob/main/src/components/systems/SceneSystem.ts"
click node_textures "https://github.com/addey34/galaxy-3d/blob/main/src/components/systems/TextureSystem.ts"
click node_celestial "https://github.com/addey34/galaxy-3d/blob/main/src/components/celestial/CelestialObject.ts"
click node_surface "https://github.com/addey34/galaxy-3d/blob/main/src/components/surface/PlanetarySurfaceEngine.ts"
click node_camera "https://github.com/addey34/galaxy-3d/blob/main/src/components/systems/CameraSystem.ts"
click node_animation "https://github.com/addey34/galaxy-3d/blob/main/src/components/systems/AnimationSystem.ts"
click node_ui "https://github.com/addey34/galaxy-3d/tree/main/src/ui"
click node_tours "https://github.com/addey34/galaxy-3d/blob/main/src/core/tourEngine.ts"
click node_events "https://github.com/addey34/galaxy-3d/blob/main/src/core/earthEvents.ts"

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_solar_app toneBlue
class node_catalog,node_registry,node_ephemeris,node_orbital,node_scale,node_simulation,node_external_catalogs toneAmber
class node_scene,node_textures,node_celestial,node_surface,node_camera,node_animation toneMint
class node_ui,node_tours,node_events toneRose
class node_visitor toneIndigo
```

## Components

### App runtime

- [Main app](https://github.com/addey34/galaxy-3d/blob/main/src/MainSolarSystemApp.ts): `src/MainSolarSystemApp.ts`
- [Solar system app](https://github.com/addey34/galaxy-3d/blob/main/src/SolarSystemApp.ts): `src/SolarSystemApp.ts`

### Astronomy and data

- [Body catalogue](https://github.com/addey34/galaxy-3d/blob/main/src/config/bodies.ts): `src/config/bodies.ts`
- [Entity registry](https://github.com/addey34/galaxy-3d/blob/main/src/registry/entities/index.ts): `src/registry/entities/index.ts`
- [Horizons ephemeris](https://github.com/addey34/galaxy-3d/blob/main/src/core/HorizonsEphemerisService.ts): `src/core/HorizonsEphemerisService.ts`
- [Orbital mechanics](https://github.com/addey34/galaxy-3d/blob/main/src/core/OrbitalMechanics.ts): `src/core/OrbitalMechanics.ts`
- [Scale conversion](https://github.com/addey34/galaxy-3d/blob/main/src/core/ScaleService.ts): `src/core/ScaleService.ts`
- [Simulation clock](https://github.com/addey34/galaxy-3d/blob/main/src/core/SimulationClock.ts): `src/core/SimulationClock.ts`

### Scene and rendering

- [Scene system](https://github.com/addey34/galaxy-3d/blob/main/src/components/systems/SceneSystem.ts): `src/components/systems/SceneSystem.ts`
- [Texture system](https://github.com/addey34/galaxy-3d/blob/main/src/components/systems/TextureSystem.ts): `src/components/systems/TextureSystem.ts`
- [Celestial objects](https://github.com/addey34/galaxy-3d/blob/main/src/components/celestial/CelestialObject.ts): `src/components/celestial/CelestialObject.ts`
- [Surface imagery](https://github.com/addey34/galaxy-3d/blob/main/src/components/surface/PlanetarySurfaceEngine.ts): `src/components/surface/PlanetarySurfaceEngine.ts`
- [Camera controls](https://github.com/addey34/galaxy-3d/blob/main/src/components/systems/CameraSystem.ts): `src/components/systems/CameraSystem.ts`
- [Animation system](https://github.com/addey34/galaxy-3d/blob/main/src/components/systems/AnimationSystem.ts): `src/components/systems/AnimationSystem.ts`

### Exploration features

- [Exploration UI](https://github.com/addey34/galaxy-3d/tree/main/src/ui): `src/ui`
- [Guided tours](https://github.com/addey34/galaxy-3d/blob/main/src/core/tourEngine.ts): `src/core/tourEngine.ts`
- [Earth events](https://github.com/addey34/galaxy-3d/blob/main/src/core/earthEvents.ts): `src/core/earthEvents.ts`

### Other components

- **Explorer**
- **Event catalogues**

## Connections

- Explorer → Main app: uses (evidence: `README.md`)
- Main app → Solar system app: starts (evidence: `src/MainSolarSystemApp.ts`)
- Solar system app → Scene system: initializes (evidence: `src/SolarSystemApp.ts`)
- Solar system app → Camera controls: coordinates (evidence: `src/SolarSystemApp.ts`)
- Solar system app → Animation system: coordinates (evidence: `src/SolarSystemApp.ts`)
- Solar system app → Horizons ephemeris: uses (evidence: `src/SolarSystemApp.ts`)
- Solar system app → Orbital mechanics: uses (evidence: `src/SolarSystemApp.ts`)
- Solar system app → Simulation clock: uses (evidence: `src/SolarSystemApp.ts`)
- Entity registry → Body catalogue: provides entities (evidence: `src/config/bodies.ts`)
- Scene system → Texture system: configures (evidence: `src/components/systems/SceneSystem.ts`)
- Scene system → Celestial objects: constructs (evidence: `src/components/systems/SceneSystem.ts`)
- Celestial objects → Scale conversion: uses (evidence: `src/components/celestial/CelestialObject.ts`)
- Surface imagery → Event catalogues: loads tiles
- Main app → Exploration UI: provides controls (evidence: `src/MainSolarSystemApp.ts`)
- Main app → Guided tours: offers tours (evidence: `README.md`)
- Main app → Earth events: offers events (evidence: `README.md`)
- Earth events → Event catalogues: reads reports (evidence: `README.md`)
- Exploration UI → Horizons ephemeris: selects dates
- Explorer → Event catalogues: catalogues USGS / NASA EONET (evidence: `README.md`)