How arka-sengupta/grav0 works
1. What this repo is
Grav0 is a fully client-side browser application: a static HTML/CSS/JS app that simulates N-body gravity and renders a spacetime-style visual field in real time. There is no backend, database, or remote API boundary in the architecture.
2. Runtime and build boundary
The app is built with Vite and ships as static assets. index.html is the main entry page, tutorial.html is a separate auxiliary page, and dist/ contains the generated production bundle.
3. Bootstrapping and composition
src/main.js is the top-level entry point that ties the app together. It initializes the simulation, scene, UI, and any per-frame update loop, acting as the orchestration layer between physics state and rendering state.
4. Physics subsystem
src/simulation.js is the CPU-side physics engine. The README describes it as a Leapfrog integrator for interacting bodies, so this module is responsible for advancing positions/velocities over time using the current body state.
5. Body definitions and presets
src/bodies.js holds the initial celestial body data and likely preset configurations used by the simulator. This is the input boundary for masses, positions, velocities, and other scenario setup values.
6. Rendering subsystem
src/scene.js and src/spacetime.js form the visual layer. The README indicates the rendering uses WebGL/GLSL shader materials, with spacetime.js focused on the deforming grid visualization that represents gravitational wells.
7. GPU shader boundary
src/shaders/position.glsl and src/shaders/velocity.glsl contain the custom shader logic. These are the main GPU-side computation and deformation programs, separating visual math from the CPU physics engine.
8. UI and interaction
src/ui.js handles user controls for simulation parameters and scene behavior. It is the interaction boundary where slider/input changes feed back into the simulation state and, indirectly, the renderer.
9. Shared helpers
src/utils.js contains reusable math or helper functions shared across the simulation and rendering modules. This keeps lower-level calculations out of the orchestration and UI code.
10. Static assets and styling
style.css defines the global presentation layer, while src/assets/ and public/screenshots/ provide images and other static resources. These assets support the landing page, tutorial page, and UI polish rather than core simulation logic.
11. Primary data flow
The key flow is: user input in ui.js updates simulation parameters → simulation.js computes the next body state on the CPU → scene.js/spacetime.js consume that state as rendering inputs and uniforms → the GPU shaders deform and draw the visual grid in the browser.
12. Operational profile
The system is designed to run locally in the browser with no server dependency. In development, Vite serves the app; in production, the built contents in dist/ are the deployable artifact.
Main entry points: main.js main.js · scene.js scene.js · simulation.js simulation.js · index.html index.html
Components 16
Runtime
Browser app entry points and production bundle
- index.html · Main browser entry page
index.html - tutorial.html · Secondary tutorial page
tutorial.html - Vite · Development and build tool configuration
vite.config.js - main.js · Top-level orchestration and app startup
src/main.js - dist · Generated production assets and pages
dist
Core sim
Physics state and initial body definitions
- simulation.js · Leapfrog N-body integration on the CPU
src/simulation.js - bodies.js · Initial celestial bodies and scenario setup
src/bodies.js - utils.js · Shared math and utility helpers
src/utils.js
Rendering
Scene composition and spacetime visualization
- scene.js · WebGL scene composition and render wiring
src/scene.js - spacetime.js · Deforming spacetime grid visualization
src/spacetime.js - position.glsl · GPU program for position-related deformation
src/shaders/position.glsl - velocity.glsl · GPU program for velocity-related deformation
src/shaders/velocity.glsl
Assets
Static styling and media resources
- style.css · Application-wide styling
style.css - assets · Source asset bundle used by the app
src/assets - screenshots · Published screenshots for the site
public/screenshots
Connections 22
- index.html → main.js: loads · Main page loads the application entry module
- tutorial.html → main.js: shares runtime · Tutorial page reuses the browser application runtime
- Vite → index.html: builds · Vite config drives the served and bundled entry page
- main.js → simulation.js: starts · Bootstrap initializes the physics engine
- main.js → scene.js: wires · Bootstrap connects simulation state to rendering
- main.js → ui.js: binds · Bootstrap attaches user interaction handlers
- main.js → bodies.js: seeds · Bootstrap loads initial body presets
- main.js → utils.js: uses · Bootstrap relies on shared helpers
- simulation.js → bodies.js: advances · Physics engine evolves the configured bodies
- simulation.js → utils.js: calculates · Physics engine shares math helpers
- ui.js → simulation.js: updates · Controls feed parameters back into simulation state
- scene.js → spacetime.js: composes · Scene includes the spacetime visualization layer
- scene.js → position.glsl: uses · Scene loads position shader logic
- scene.js → velocity.glsl: uses · Scene loads velocity shader logic
- spacetime.js → position.glsl: drives · Spacetime rendering uses position deformation math
- spacetime.js → velocity.glsl: drives · Spacetime rendering uses velocity deformation math
- style.css → index.html: styles · Global stylesheet is applied by the main page
- style.css → tutorial.html: styles · Global stylesheet is applied by the tutorial page
- assets → main.js: supports · Source assets support the application UI and visuals
- screenshots → tutorial.html: illustrates · Screenshots support the public-facing tutorial content
- dist → index.html: produces · Production build outputs the deployable app pages
- dist → tutorial.html: produces · Production build outputs the deployable tutorial page