How krishnendubarua/senteroid works
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: App.tsx App shell · simulation.ts Model layer · SimulationPage.tsx Simulation page · SpaceTravelPage.tsx Space Travel
Components 27
SPA Shell
Client-side React app entry, routing, and page assembly.
- Entry · Bootstraps the SPA and mounts the app.
src/main.tsx - App shell · Top-level application composition and page switching.
src/App.tsx - Navbar · Primary navigation across Home, Earth, Simulation, Space Travel, and Learn.
src/components/Navbar.tsx - Home page · Introductory landing experience.
src/HomePage.tsx - Earth page · Earth-centric visualization and context.
src/EarthPage.tsx - Simulation page · Core calculator and results experience.
src/SimulationPage.tsx - Space Travel · Cinematic educational and narrative mode.
src/SpaceTravelPage.tsx - HUD UI · Shared in-app controls and interface chrome.
src/components/UI.tsx - Build config · Vite, Tailwind, PostCSS, and deploy configuration.
vite.config.ts
Simulation Core
Domain math, catalog shaping, and external science data integration.
- Inputs · User parameter controls for asteroid and comet scenarios.
src/components/AsteroidControls.tsx - Neo selector · Selects near-Earth objects from curated or fetched lists.
src/components/NeoSelector.tsx - Results · Primary simulation output summaries.
src/components/SimulationResults.tsx - Detailed results · Expanded impact metrics and derived outputs.
src/components/DetailedSimulationResults.tsx - Model layer · Impact math, derived metrics, and domain types.
src/data/simulation.ts - NASA data · Fetches and shapes NeoWs-style asteroid data.
src/data/nasa.ts - SBDB client · Integrates JPL small-body database data.
src/data/sbdb.ts - Quake data · Earthquake comparison and seismic context layer.
src/data/earthquakes.ts - Static catalog · Local curated object catalog and data shaping.
src/data/staticCatalog.ts
Visualization
Globe, map, and object rendering layers for interactive views.
- Globe views · Cesium-driven globe and simulation globe variants.
src/components/CesiumGlobe.tsx - Map views · Alternative 2D map and simplified visualizations.
src/components/BingMap2D.tsx - Object viewer · Renders asteroid models and inspection views.
src/components/AsteroidViewer.tsx - Space visuals · Transforms comet and orbit data for cinematic display.
src/space/nasaComets.ts
Learn & Media
Narrative learning experience and supporting media assets.
- Learn · Scrollable learning and storytelling surface.
src/learn/Learn.tsx - Space background · 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 · Backgrounds, fact images, sounds, and local data files.
public - 3D assets · Bundled asteroid GLB models and simulation imagery.
src/assets - Cesium runtime · Bundled Cesium distribution used for 3D globe rendering.
public/cesium
Connections 29
- 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.