# krishnendubarua/senteroid architecture

> Architecture diagram of the GitHub repository krishnendubarua/senteroid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krishnendubarua/senteroid
- Repository: https://github.com/krishnendubarua/senteroid

## Overview

1. **System shape**
   - Senteroid is a **client-side single-page app** built with **React + TypeScript + Vite**.
   - There is no visible backend service in this repo; the browser app does the data fetching, simulation, and rendering itself.

2. **Entry and shell**
   - The runtime starts at `src/main.tsx`, mounts `src/App.tsx`, and then hands off to the page-level views.
   - `Navbar.tsx` likely provides the top-level navigation between the major experiences: Home, Earth, Simulation, Space Travel, and Learn.

3. **Page-level boundaries**
   - `HomePage.tsx` is the landing/intro experience.
   - `EarthPage.tsx` appears to focus on Earth-centric exploration and visualization.
   - `SimulationPage.tsx` is the core impact calculator and results view.
   - `SpaceTravelPage.tsx` supports the cinematic educational/story mode.
   - `src/learn/Learn.tsx` is a separate learning/storytelling area rather than a simulation surface.

4. **Core product flow**
   - User inputs asteroid or comet parameters through controls such as `AsteroidControls.tsx` and `NeoSelector.tsx`.
   - Those inputs feed a TypeScript-based physics/model layer in `src/data`, which computes impact metrics.
   - The outputs are then rendered in result components like `SimulationResults.tsx` and `DetailedSimulationResults.tsx`, and visualized in globe/map components.

5. **Simulation and domain model**
   - `src/data/simulation.ts`, `earthquakes.ts`, `nasa.ts`, `sbdb.ts`, and `types.ts` suggest the app keeps its scientific calculations and data shaping in a dedicated domain layer.
   - This layer likely performs the simplified impact math described in the README: energy, TNT equivalent, crater size, blast radii, seismic magnitude, and tsunami estimates.
   - `staticCatalog.ts` and the `public/data/near_earth_comets_static.json` file provide local fallback or curated catalog data.

6. **External data sources**
   - The app integrates with **NASA NeoWs** and **JPL SBDB** through the data/client files in `src/data`.
   - Historic earthquake context comes from **USGS**-based data and comparison links.
   - Comet orbit visualization is supported by `src/space/nasaComets.ts` and `src/space/neoOrbits.ts`, which likely transform orbital data for rendering.

7. **Visualization layer**
   - Cesium is the main 3D geospatial engine, with components like `CesiumGlobe.tsx`, `SimpleGlobe.tsx`, `SimulationGlobe.tsx`, `SimulationCesiumGlobe.tsx`, and `SimulationCesiumGlobeFixed.tsx`.
   - `BingMap2D.tsx` and `SimpleMap.tsx` provide 2D map alternatives or supporting views.
   - `AsteroidViewer.tsx` and `SimpleGlobe.tsx` suggest separate presentation modes for model inspection versus narrative exploration.

8. **Interaction and UI state**
   - The app is organized around reusable interactive controls rather than server-driven pages.
   - Components such as `AsteroidControls.tsx`, `NeoSelector.tsx`, and `UI.tsx` manage user input and the in-app HUD.
   - `SimulationResults.tsx` and `DetailedSimulationResults.tsx` form the output boundary between computation and presentation.

9. **Learning and storytelling subsystem**
   - `SpaceTravelBackground.tsx`, `Learn.tsx`, and the sound assets in `src/learn/` and `public/sound/` support the cinematic, scroll-driven educational experience.
   - The repo also contains dedicated factual media directories like `public/fact-images`, `public/space-travel-bg`, and `public/home-bg`, indicating a strong content-driven layer.

10. **Asset pipeline**
   - Large binary assets are stored locally: Cesium distribution files in `public/cesium`, asteroid GLB models in `src/assets/asteroids`, and simulation/space imagery in `src/assets`.
   - This means the app is designed to run with bundled static assets rather than fetching core rendering dependencies at runtime.
   - `scripts/copy-cesium.js` exists to keep Cesium’s runtime assets in the correct public location during builds.

11. **Rendering/runtime dependencies**
   - Cesium is the dominant runtime dependency for globe visualization.
   - The presence of `VITE_CESIUM_ION_TOKEN` in the README indicates optional access to Cesium ion services for imagery or terrain.
   - `VITE_NASA_API_KEY` is the other key runtime secret, used for NASA API access.

12. **Styling and UX**
   - Styling is handled by **TailwindCSS** plus `src/styles/index.css`, with custom animation support and some lightweight global CSS.
   - `postcss.config.js` and `tailwind.config.js` define the styling toolchain.
   - The app emphasizes immersive UX: sticky HUDs, smooth scrolling, animated content, and responsive layouts.

13. **Build and deployment boundary**
   - The app is built with **Vite** and deployed through **Vercel** (`vercel.json`).
   - `package.json`, `vite.config.ts`, and the copied Cesium public tree define the frontend-only build/deploy pipeline.
   - `index.html` is the single HTML host page for the SPA.

14. **Important architectural takeaway**
   - For diagramming, the key boundaries are: **browser SPA shell**, **scientific/data transformation layer**, **Cesium/map visualization layer**, and **static/media asset layer**.
   - Data flows from NASA/USGS/static catalogs into local TypeScript models, then into simulation outputs and 3D/2D visual components, with no dedicated backend in this repository.

Main entry points: [`src/App.tsx`](https://github.com/krishnendubarua/senteroid/blob/main/src/App.tsx) (App shell), [`src/data/simulation.ts`](https://github.com/krishnendubarua/senteroid/blob/main/src/data/simulation.ts) (Model layer), [`src/SimulationPage.tsx`](https://github.com/krishnendubarua/senteroid/blob/main/src/SimulationPage.tsx) (Simulation page), [`src/SpaceTravelPage.tsx`](https://github.com/krishnendubarua/senteroid/blob/main/src/SpaceTravelPage.tsx) (Space Travel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_shell["SPA Shell"]
  node_node_main["Entry<br/>[main.tsx]"]
  node_node_app["App shell<br/>root component<br/>[App.tsx]"]
  node_node_nav["Navbar<br/>navigation UI<br/>[Navbar.tsx]"]
  node_node_home["Home page<br/>landing page<br/>[HomePage.tsx]"]
  node_node_earth["Earth page<br/>exploration page<br/>[EarthPage.tsx]"]
  node_node_simpage["Simulation page<br/>impact page<br/>[SimulationPage.tsx]"]
  node_node_spacepage["Space Travel<br/>story page"]
  node_node_ui["HUD UI<br/>overlay UI<br/>[UI.tsx]"]
  node_node_build["Build config<br/>tooling<br/>[vite.config.ts]"]
end

subgraph group_group_sim["Simulation Core"]
  node_node_controls["Inputs<br/>control panel"]
  node_node_selector["Neo selector<br/>object picker<br/>[NeoSelector.tsx]"]
  node_node_results["Results<br/>summary view"]
  node_node_detailresults["Detailed results<br/>analysis view"]
  node_node_simdata[("Model layer<br/>scientific model<br/>[simulation.ts]")]
  node_node_nasa["NASA data<br/>API client<br/>[nasa.ts]"]
  node_node_sbdb["SBDB client<br/>API client<br/>[sbdb.ts]"]
  node_node_earthquakes["Quake data<br/>context data<br/>[earthquakes.ts]"]
  node_node_staticcat[("Static catalog<br/>fallback catalog<br/>[staticCatalog.ts]")]
end

subgraph group_group_viz["Visualization"]
  node_node_globe(("Globe views<br/>3D geospatial<br/>[CesiumGlobe.tsx]"))
  node_node_map["Map views<br/>2D geospatial<br/>[BingMap2D.tsx]"]
  node_node_viewer["Object viewer<br/>asset viewer<br/>[AsteroidViewer.tsx]"]
  node_node_spacelayer["Space visuals<br/>orbit rendering<br/>[nasaComets.ts]"]
end

subgraph group_group_learn["Learn & Media"]
  node_node_learn["Learn<br/>[Learn.tsx]"]
  node_node_bg["Space background<br/>presentation layer"]
end

subgraph group_group_assets["Static Assets"]
  node_node_assets_public[("Public media<br/>static media")]
  node_node_assets_models[("3D assets<br/>model assets")]
  node_node_cesium[("Cesium runtime<br/>vendor runtime")]
end

node_node_main -->|"mounts"| node_node_app
node_node_app -->|"hosts"| node_node_nav
node_node_app -->|"routes to"| node_node_home
node_node_app -->|"routes to"| node_node_earth
node_node_app -->|"routes to"| node_node_simpage
node_node_app -->|"routes to"| node_node_spacepage
node_node_app -->|"routes to"| node_node_learn
node_node_app -->|"composes"| node_node_ui
node_node_simpage -->|"uses"| node_node_controls
node_node_simpage -->|"uses"| node_node_selector
node_node_controls -->|"feeds"| node_node_simdata
node_node_selector -->|"fetches"| node_node_nasa
node_node_selector -->|"falls back to"| node_node_staticcat
node_node_simdata -->|"shapes"| node_node_nasa
node_node_simdata -->|"shapes"| node_node_sbdb
node_node_simdata -->|"compares with"| node_node_earthquakes
node_node_simdata -->|"renders in"| node_node_results
node_node_simdata -->|"renders in"| node_node_detailresults
node_node_results -->|"visualizes on"| node_node_globe
node_node_detailresults -->|"visualizes on"| node_node_map
node_node_earth -->|"uses"| node_node_globe
node_node_spacepage -->|"uses"| node_node_spacelayer
node_node_spacepage -->|"layers"| node_node_bg
node_node_globe -->|"depends on"| node_node_cesium
node_node_viewer -->|"loads"| node_node_assets_models
node_node_bg -->|"reads"| node_node_assets_public
node_node_learn -->|"reads"| node_node_assets_public
node_node_build -->|"packages"| node_node_cesium
node_node_build -->|"bundles"| node_node_assets_public

click node_node_main "https://github.com/krishnendubarua/senteroid/blob/main/src/main.tsx"
click node_node_app "https://github.com/krishnendubarua/senteroid/blob/main/src/App.tsx"
click node_node_nav "https://github.com/krishnendubarua/senteroid/blob/main/src/components/Navbar.tsx"
click node_node_home "https://github.com/krishnendubarua/senteroid/blob/main/src/HomePage.tsx"
click node_node_earth "https://github.com/krishnendubarua/senteroid/blob/main/src/EarthPage.tsx"
click node_node_simpage "https://github.com/krishnendubarua/senteroid/blob/main/src/SimulationPage.tsx"
click node_node_spacepage "https://github.com/krishnendubarua/senteroid/blob/main/src/SpaceTravelPage.tsx"
click node_node_learn "https://github.com/krishnendubarua/senteroid/blob/main/src/learn/Learn.tsx"
click node_node_ui "https://github.com/krishnendubarua/senteroid/blob/main/src/components/UI.tsx"
click node_node_controls "https://github.com/krishnendubarua/senteroid/blob/main/src/components/AsteroidControls.tsx"
click node_node_selector "https://github.com/krishnendubarua/senteroid/blob/main/src/components/NeoSelector.tsx"
click node_node_results "https://github.com/krishnendubarua/senteroid/blob/main/src/components/SimulationResults.tsx"
click node_node_detailresults "https://github.com/krishnendubarua/senteroid/blob/main/src/components/DetailedSimulationResults.tsx"
click node_node_simdata "https://github.com/krishnendubarua/senteroid/blob/main/src/data/simulation.ts"
click node_node_nasa "https://github.com/krishnendubarua/senteroid/blob/main/src/data/nasa.ts"
click node_node_sbdb "https://github.com/krishnendubarua/senteroid/blob/main/src/data/sbdb.ts"
click node_node_earthquakes "https://github.com/krishnendubarua/senteroid/blob/main/src/data/earthquakes.ts"
click node_node_staticcat "https://github.com/krishnendubarua/senteroid/blob/main/src/data/staticCatalog.ts"
click node_node_globe "https://github.com/krishnendubarua/senteroid/blob/main/src/components/CesiumGlobe.tsx"
click node_node_map "https://github.com/krishnendubarua/senteroid/blob/main/src/components/BingMap2D.tsx"
click node_node_viewer "https://github.com/krishnendubarua/senteroid/blob/main/src/components/AsteroidViewer.tsx"
click node_node_spacelayer "https://github.com/krishnendubarua/senteroid/blob/main/src/space/nasaComets.ts"
click node_node_bg "https://github.com/krishnendubarua/senteroid/blob/main/src/components/SpaceTravelBackground.tsx"
click node_node_assets_public "https://github.com/krishnendubarua/senteroid/tree/main/public"
click node_node_assets_models "https://github.com/krishnendubarua/senteroid/tree/main/src/assets"
click node_node_cesium "https://github.com/krishnendubarua/senteroid/tree/main/public/cesium"
click node_node_build "https://github.com/krishnendubarua/senteroid/blob/main/vite.config.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_node_main,node_node_app,node_node_nav,node_node_home,node_node_earth,node_node_simpage,node_node_spacepage,node_node_ui,node_node_build toneBlue
class node_node_controls,node_node_selector,node_node_results,node_node_detailresults,node_node_simdata,node_node_nasa,node_node_sbdb,node_node_earthquakes,node_node_staticcat toneAmber
class node_node_globe,node_node_map,node_node_viewer,node_node_spacelayer toneMint
class node_node_learn,node_node_bg toneRose
class node_node_assets_public,node_node_assets_models,node_node_cesium toneIndigo
```

## Components

### SPA Shell

Client-side React app entry, routing, and page assembly.

- [Entry](https://github.com/krishnendubarua/senteroid/blob/main/src/main.tsx): React/Vite entry · Bootstraps the SPA and mounts the app. · `src/main.tsx`
- [App shell](https://github.com/krishnendubarua/senteroid/blob/main/src/App.tsx): root component · Top-level application composition and page switching. · `src/App.tsx`
- [Navbar](https://github.com/krishnendubarua/senteroid/blob/main/src/components/Navbar.tsx): navigation UI · Primary navigation across Home, Earth, Simulation, Space Travel, and Learn. · `src/components/Navbar.tsx`
- [Home page](https://github.com/krishnendubarua/senteroid/blob/main/src/HomePage.tsx): landing page · Introductory landing experience. · `src/HomePage.tsx`
- [Earth page](https://github.com/krishnendubarua/senteroid/blob/main/src/EarthPage.tsx): exploration page · Earth-centric visualization and context. · `src/EarthPage.tsx`
- [Simulation page](https://github.com/krishnendubarua/senteroid/blob/main/src/SimulationPage.tsx): impact page · Core calculator and results experience. · `src/SimulationPage.tsx`
- [Space Travel](https://github.com/krishnendubarua/senteroid/blob/main/src/SpaceTravelPage.tsx): story page · Cinematic educational and narrative mode. · `src/SpaceTravelPage.tsx`
- [HUD UI](https://github.com/krishnendubarua/senteroid/blob/main/src/components/UI.tsx): overlay UI · Shared in-app controls and interface chrome. · `src/components/UI.tsx`
- [Build config](https://github.com/krishnendubarua/senteroid/blob/main/vite.config.ts): tooling · Vite, Tailwind, PostCSS, and deploy configuration. · `vite.config.ts`

### Simulation Core

Domain math, catalog shaping, and external science data integration.

- [Inputs](https://github.com/krishnendubarua/senteroid/blob/main/src/components/AsteroidControls.tsx): control panel · User parameter controls for asteroid and comet scenarios. · `src/components/AsteroidControls.tsx`
- [Neo selector](https://github.com/krishnendubarua/senteroid/blob/main/src/components/NeoSelector.tsx): object picker · Selects near-Earth objects from curated or fetched lists. · `src/components/NeoSelector.tsx`
- [Results](https://github.com/krishnendubarua/senteroid/blob/main/src/components/SimulationResults.tsx): summary view · Primary simulation output summaries. · `src/components/SimulationResults.tsx`
- [Detailed results](https://github.com/krishnendubarua/senteroid/blob/main/src/components/DetailedSimulationResults.tsx): analysis view · Expanded impact metrics and derived outputs. · `src/components/DetailedSimulationResults.tsx`
- [Model layer](https://github.com/krishnendubarua/senteroid/blob/main/src/data/simulation.ts): scientific model · Impact math, derived metrics, and domain types. · `src/data/simulation.ts`
- [NASA data](https://github.com/krishnendubarua/senteroid/blob/main/src/data/nasa.ts): API client · Fetches and shapes NeoWs-style asteroid data. · `src/data/nasa.ts`
- [SBDB client](https://github.com/krishnendubarua/senteroid/blob/main/src/data/sbdb.ts): API client · Integrates JPL small-body database data. · `src/data/sbdb.ts`
- [Quake data](https://github.com/krishnendubarua/senteroid/blob/main/src/data/earthquakes.ts): context data · Earthquake comparison and seismic context layer. · `src/data/earthquakes.ts`
- [Static catalog](https://github.com/krishnendubarua/senteroid/blob/main/src/data/staticCatalog.ts): fallback catalog · Local curated object catalog and data shaping. · `src/data/staticCatalog.ts`

### Visualization

Globe, map, and object rendering layers for interactive views.

- [Globe views](https://github.com/krishnendubarua/senteroid/blob/main/src/components/CesiumGlobe.tsx): 3D geospatial · Cesium-driven globe and simulation globe variants. · `src/components/CesiumGlobe.tsx`
- [Map views](https://github.com/krishnendubarua/senteroid/blob/main/src/components/BingMap2D.tsx): 2D geospatial · Alternative 2D map and simplified visualizations. · `src/components/BingMap2D.tsx`
- [Object viewer](https://github.com/krishnendubarua/senteroid/blob/main/src/components/AsteroidViewer.tsx): asset viewer · Renders asteroid models and inspection views. · `src/components/AsteroidViewer.tsx`
- [Space visuals](https://github.com/krishnendubarua/senteroid/blob/main/src/space/nasaComets.ts): orbit rendering · Transforms comet and orbit data for cinematic display. · `src/space/nasaComets.ts`

### Learn & Media

Narrative learning experience and supporting media assets.

- [Learn](https://github.com/krishnendubarua/senteroid/blob/main/src/learn/Learn.tsx): learning module · Scrollable learning and storytelling surface. · `src/learn/Learn.tsx`
- [Space background](https://github.com/krishnendubarua/senteroid/blob/main/src/components/SpaceTravelBackground.tsx): presentation layer · Cinematic backdrop and scene atmosphere for travel mode. · `src/components/SpaceTravelBackground.tsx`

### Static Assets

Bundled runtime assets and public data used by the frontend.

- [Public media](https://github.com/krishnendubarua/senteroid/tree/main/public): static media · Backgrounds, fact images, sounds, and local data files. · `public`
- [3D assets](https://github.com/krishnendubarua/senteroid/tree/main/src/assets): model assets · Bundled asteroid GLB models and simulation imagery. · `src/assets`
- [Cesium runtime](https://github.com/krishnendubarua/senteroid/tree/main/public/cesium): vendor runtime · Bundled Cesium distribution used for 3D globe rendering. · `public/cesium`

## Connections

- Entry → App shell: mounts · Main entry mounts the app shell.
- App shell → Navbar: hosts · App shell provides the global navigation.
- App shell → Home page: routes to · One of the major page-level experiences.
- App shell → Earth page: routes to · One of the major page-level experiences.
- App shell → Simulation page: routes to · One of the major page-level experiences.
- App shell → Space Travel: routes to · One of the major page-level experiences.
- App shell → Learn: routes to · Dedicated learning/storytelling area.
- App shell → HUD UI: composes · Shared HUD and reusable UI surfaces.
- Simulation page → Inputs: uses · Collects asteroid and impact parameters.
- Simulation page → Neo selector: uses · Chooses a target object from catalog/data.
- Inputs → Model layer: feeds · User inputs drive the model calculations.
- Neo selector → NASA data: fetches · Selection can pull live NASA object data.
- Neo selector → Static catalog: falls back to · Uses local curated catalog when needed.
- Model layer → NASA data: shapes · Scientific model consumes fetched object data.
- Model layer → SBDB client: shapes · Scientific model consumes SBDB data.
- Model layer → Quake data: compares with · Provides earthquake/seismic context.
- Model layer → Results: renders in · Primary outputs are displayed in summary results.
- Model layer → Detailed results: renders in · Expanded metrics are displayed in detailed results.
- Results → Globe views: visualizes on · Results are paired with globe-based views.
- Detailed results → Map views: visualizes on · Detailed outputs can be paired with map views.
- Earth page → Globe views: uses · Earth exploration centers on geospatial rendering.
- Space Travel → Space visuals: uses · Travel mode uses orbit and comet visual transforms.
- Space Travel → Space background: layers · Cinematic background supports the narrative experience.
- Globe views → Cesium runtime: depends on · Globe rendering is powered by the bundled Cesium runtime.
- Object viewer → 3D assets: loads · Viewer consumes asteroid GLB assets.
- Space background → Public media: reads · Backgrounds and sounds are served as static media.
- Learn → Public media: reads · Learning experience uses fact images and audio.
- Build config → Cesium runtime: packages · Build pipeline copies Cesium assets into public output.
- Build config → Public media: bundles · Static public assets are part of the frontend build.