# arka-sengupta/grav0 architecture

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

- Interactive diagram: https://gitdiagram.com/arka-sengupta/grav0
- Repository: https://github.com/arka-sengupta/grav0

## Overview

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: [`src/main.js`](https://github.com/arka-sengupta/grav0/blob/main/src/main.js) (main.js), [`src/scene.js`](https://github.com/arka-sengupta/grav0/blob/main/src/scene.js) (scene.js), [`src/simulation.js`](https://github.com/arka-sengupta/grav0/blob/main/src/simulation.js) (simulation.js), [`index.html`](https://github.com/arka-sengupta/grav0/blob/main/index.html) (index.html)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_index_html["index.html<br/>entry page<br/>[index.html]"]
  node_tutorial_html["tutorial.html<br/>aux page<br/>[tutorial.html]"]
  node_vite_config["Vite<br/>build config<br/>[vite.config.js]"]
  node_main_js["main.js<br/>app bootstrap<br/>[main.js]"]
  node_dist_bundle[("dist<br/>build output")]
end

subgraph group_core["Core sim"]
  node_simulation_js["simulation.js<br/>physics engine<br/>[simulation.js]"]
  node_bodies_js["bodies.js<br/>body presets<br/>[bodies.js]"]
  node_utils_js["utils.js<br/>helpers<br/>[utils.js]"]
end

subgraph group_render["Rendering"]
  node_scene_js["scene.js<br/>scene setup<br/>[scene.js]"]
  node_spacetime_js["spacetime.js<br/>visual field<br/>[spacetime.js]"]
  node_pos_shader["position.glsl<br/>shader<br/>[position.glsl]"]
  node_vel_shader["velocity.glsl<br/>shader<br/>[velocity.glsl]"]
end

subgraph group_ui["Interaction"]
  node_ui_js["ui.js<br/>controls<br/>[ui.js]"]
end

subgraph group_assets["Assets"]
  node_style_css["style.css<br/>global styles<br/>[style.css]"]
  node_src_assets[("assets<br/>static media")]
  node_public_screenshots[("screenshots<br/>public media")]
end

node_index_html -->|"loads"| node_main_js
node_tutorial_html -->|"shares runtime"| node_main_js
node_vite_config -->|"builds"| node_index_html
node_main_js -->|"starts"| node_simulation_js
node_main_js -->|"wires"| node_scene_js
node_main_js -->|"binds"| node_ui_js
node_main_js -->|"seeds"| node_bodies_js
node_main_js -->|"uses"| node_utils_js
node_simulation_js -->|"advances"| node_bodies_js
node_simulation_js -->|"calculates"| node_utils_js
node_ui_js -->|"updates"| node_simulation_js
node_scene_js -->|"composes"| node_spacetime_js
node_scene_js -->|"uses"| node_pos_shader
node_scene_js -->|"uses"| node_vel_shader
node_spacetime_js -->|"drives"| node_pos_shader
node_spacetime_js -->|"drives"| node_vel_shader
node_style_css -->|"styles"| node_index_html
node_style_css -->|"styles"| node_tutorial_html
node_src_assets -->|"supports"| node_main_js
node_public_screenshots -->|"illustrates"| node_tutorial_html
node_dist_bundle -.->|"produces"| node_index_html
node_dist_bundle -.->|"produces"| node_tutorial_html

click node_index_html "https://github.com/arka-sengupta/grav0/blob/main/index.html"
click node_tutorial_html "https://github.com/arka-sengupta/grav0/blob/main/tutorial.html"
click node_vite_config "https://github.com/arka-sengupta/grav0/blob/main/vite.config.js"
click node_main_js "https://github.com/arka-sengupta/grav0/blob/main/src/main.js"
click node_simulation_js "https://github.com/arka-sengupta/grav0/blob/main/src/simulation.js"
click node_bodies_js "https://github.com/arka-sengupta/grav0/blob/main/src/bodies.js"
click node_utils_js "https://github.com/arka-sengupta/grav0/blob/main/src/utils.js"
click node_scene_js "https://github.com/arka-sengupta/grav0/blob/main/src/scene.js"
click node_spacetime_js "https://github.com/arka-sengupta/grav0/blob/main/src/spacetime.js"
click node_pos_shader "https://github.com/arka-sengupta/grav0/blob/main/src/shaders/position.glsl"
click node_vel_shader "https://github.com/arka-sengupta/grav0/blob/main/src/shaders/velocity.glsl"
click node_ui_js "https://github.com/arka-sengupta/grav0/blob/main/src/ui.js"
click node_style_css "https://github.com/arka-sengupta/grav0/blob/main/style.css"
click node_src_assets "https://github.com/arka-sengupta/grav0/tree/main/src/assets"
click node_public_screenshots "https://github.com/arka-sengupta/grav0/tree/main/public/screenshots"
click node_dist_bundle "https://github.com/arka-sengupta/grav0/tree/main/dist"

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_index_html,node_tutorial_html,node_vite_config,node_main_js,node_dist_bundle toneBlue
class node_simulation_js,node_bodies_js,node_utils_js toneAmber
class node_scene_js,node_spacetime_js,node_pos_shader,node_vel_shader toneMint
class node_ui_js toneRose
class node_style_css,node_src_assets,node_public_screenshots toneIndigo
```

## Components

### Runtime

Browser app entry points and production bundle

- [index.html](https://github.com/arka-sengupta/grav0/blob/main/index.html): entry page · Main browser entry page · `index.html`
- [tutorial.html](https://github.com/arka-sengupta/grav0/blob/main/tutorial.html): aux page · Secondary tutorial page · `tutorial.html`
- [Vite](https://github.com/arka-sengupta/grav0/blob/main/vite.config.js): build config · Development and build tool configuration · `vite.config.js`
- [main.js](https://github.com/arka-sengupta/grav0/blob/main/src/main.js): app bootstrap · Top-level orchestration and app startup · `src/main.js`
- [dist](https://github.com/arka-sengupta/grav0/tree/main/dist): build output · Generated production assets and pages · `dist`

### Core sim

Physics state and initial body definitions

- [simulation.js](https://github.com/arka-sengupta/grav0/blob/main/src/simulation.js): physics engine · Leapfrog N-body integration on the CPU · `src/simulation.js`
- [bodies.js](https://github.com/arka-sengupta/grav0/blob/main/src/bodies.js): body presets · Initial celestial bodies and scenario setup · `src/bodies.js`
- [utils.js](https://github.com/arka-sengupta/grav0/blob/main/src/utils.js): helpers · Shared math and utility helpers · `src/utils.js`

### Rendering

Scene composition and spacetime visualization

- [scene.js](https://github.com/arka-sengupta/grav0/blob/main/src/scene.js): scene setup · WebGL scene composition and render wiring · `src/scene.js`
- [spacetime.js](https://github.com/arka-sengupta/grav0/blob/main/src/spacetime.js): visual field · Deforming spacetime grid visualization · `src/spacetime.js`
- [position.glsl](https://github.com/arka-sengupta/grav0/blob/main/src/shaders/position.glsl): shader · GPU program for position-related deformation · `src/shaders/position.glsl`
- [velocity.glsl](https://github.com/arka-sengupta/grav0/blob/main/src/shaders/velocity.glsl): shader · GPU program for velocity-related deformation · `src/shaders/velocity.glsl`

### Interaction

Controls and user-facing behavior

- [ui.js](https://github.com/arka-sengupta/grav0/blob/main/src/ui.js): controls · User controls and parameter updates · `src/ui.js`

### Assets

Static styling and media resources

- [style.css](https://github.com/arka-sengupta/grav0/blob/main/style.css): global styles · Application-wide styling · `style.css`
- [assets](https://github.com/arka-sengupta/grav0/tree/main/src/assets): static media · Source asset bundle used by the app · `src/assets`
- [screenshots](https://github.com/arka-sengupta/grav0/tree/main/public/screenshots): public media · Published screenshots for the site · `public/screenshots`

## Connections

- 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
