# romapervushin1234/pachoink-newton architecture

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

- Interactive diagram: https://gitdiagram.com/romapervushin1234/pachoink-newton
- Repository: https://github.com/romapervushin1234/pachoink-newton

## Overview

1. This repo is a browser-based simulation/game called **Pachoink-Newton**. The architecture is split between a **JavaScript frontend** that owns the app loop, rendering, UI, and input, and a **Rust/WASM module** under `wasm/` that likely provides the Newtonian gravity-heavy computation path.

2. The browser entry point is `index.html`, which boots the JavaScript app from `src/main.js`. That file is the top-level coordinator for the client runtime and is the main place where the subsystems are wired together.

3. The core runtime is organized as a set of focused modules in `src/`:
   - `state.js` for shared game/application state
   - `input.js` for user interaction
   - `camera.js` for viewport/world transforms
   - `generation.js` for creating levels/objects/content
   - `particles.js` for simulation entities and motion
   - `scoring.js` for point calculation and progress tracking
   - `renderer.js` for drawing
   - `ui.js` for interface overlays and controls
   - `config.js` for tunable constants
   - `Newtonian_pachoink.js` as the domain-specific glue or exported simulation entry point

4. The likely data flow is: **input** changes **state**, the main loop advances **generation/particles/scoring**, and the **renderer** consumes the updated state to draw the frame. The **camera** sits between simulation state and rendering, translating world coordinates into view coordinates.

5. The **state boundary** is important: it appears to be the shared source of truth for the current scene, user progress, and simulation parameters. Other modules should be viewed as consumers or mutators of that central state rather than owning their own isolated copies.

6. The **simulation boundary** is split by responsibility, not by feature. `particles.js` and `generation.js` likely handle the evolving world model, while `scoring.js` interprets outcomes. This separation suggests the app keeps physics/behavior logic distinct from presentation logic.

7. The **rendering boundary** is cleanly isolated in `renderer.js` and `ui.js`. That implies two visual layers: the world canvas/scene rendering and a separate UI layer for buttons, indicators, and score display. `camera.js` influences only the world layer, not the UI layer.

8. The `wasm/` directory is a second major subsystem. It is a Rust crate (`Cargo.toml`, `Cargo.lock`, `src/lib.rs`) compiled to WebAssembly, likely used to accelerate gravity/physics calculations or other numerically heavy work that benefits from Rust performance and deterministic behavior.

9. The JS/WASM integration boundary is probably centered in `src/Newtonian_pachoink.js`. That file likely abstracts the WASM exports behind a JavaScript-friendly interface so the rest of the app can treat the simulation engine as a module rather than dealing with raw WASM details directly.

10. `server.js` is the lightweight host/runtime for development or local serving. It is not the application logic; it exists to deliver the static browser assets and make the client/WASM bundle runnable from a Node-based environment.

11. In architectural terms, this repo is mostly a **single-page interactive simulation** with:
   - a **presentation layer** in the browser
   - a **domain/simulation layer** in JavaScript
   - a **compute accelerator** in Rust/WASM
   - a **thin server wrapper** for hosting

12. For a diagram, the main arrows should be:
   - user input → `input.js` → `state.js`
   - state/update loop → `generation.js` / `particles.js` / `scoring.js`
   - simulation data → `renderer.js` / `ui.js`
   - camera transforms → `renderer.js`
   - JS simulation glue → `Newtonian_pachoink.js` ↔ `wasm/lib.rs`
   - `server.js` → serves `index.html` + client/WASM assets

Main entry points: [`src/main.js`](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/main.js) (Main Loop), [`src/state.js`](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/state.js) (State), [`src/renderer.js`](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/renderer.js) (Renderer), [`src/config.js`](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/config.js) (Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host"]
  node_server_js["Server<br/>[server.js]"]
  node_index_html["Entry Page<br/>html boot<br/>[index.html]"]
end

subgraph group_client["Browser Client"]
  node_main_js["Main Loop<br/>app coordinator<br/>[main.js]"]
  node_state_js[("State<br/>[state.js]")]
  node_input_js["Input<br/>controls<br/>[input.js]"]
  node_camera_js["Camera<br/>view transform<br/>[camera.js]"]
  node_generation_js["Generation<br/>content gen<br/>[generation.js]"]
  node_particles_js(("Particles<br/>simulation<br/>[particles.js]"))
  node_scoring_js["Scoring<br/>progress logic<br/>[scoring.js]"]
  node_renderer_js["Renderer<br/>drawing<br/>[renderer.js]"]
  node_ui_js["UI<br/>[ui.js]"]
  node_config_js["Config<br/>tuning constants<br/>[config.js]"]
  node_newton_js["Newton Bridge<br/>wasm glue"]
end

subgraph group_wasm["WASM Compute"]
  node_wasm_lib{{"WASM Core<br/>rust crate<br/>[lib.rs]"}}
end

node_server_js -->|"serves"| node_index_html
node_index_html -->|"boots"| node_main_js
node_main_js -->|"wires"| node_input_js
node_main_js -->|"owns"| node_state_js
node_main_js -->|"drives"| node_generation_js
node_main_js -->|"updates"| node_particles_js
node_main_js -->|"evaluates"| node_scoring_js
node_main_js -->|"ticks"| node_renderer_js
node_main_js -->|"updates"| node_ui_js
node_main_js -->|"uses"| node_newton_js
node_input_js -->|"mutates"| node_state_js
node_generation_js -->|"writes"| node_state_js
node_particles_js -->|"reads/writes"| node_state_js
node_scoring_js -->|"reads"| node_state_js
node_renderer_js -->|"reads"| node_state_js
node_renderer_js -->|"applies"| node_camera_js
node_ui_js -->|"reads"| node_state_js
node_newton_js -->|"bridges"| node_wasm_lib
node_config_js -->|"configures"| node_generation_js
node_config_js -->|"configures"| node_particles_js
node_config_js -->|"configures"| node_renderer_js

click node_server_js "https://github.com/romapervushin1234/pachoink-newton/blob/main/server.js"
click node_index_html "https://github.com/romapervushin1234/pachoink-newton/blob/main/index.html"
click node_main_js "https://github.com/romapervushin1234/pachoink-newton/blob/main/src/main.js"
click node_state_js "https://github.com/romapervushin1234/pachoink-newton/blob/main/src/state.js"
click node_input_js "https://github.com/romapervushin1234/pachoink-newton/blob/main/src/input.js"
click node_camera_js "https://github.com/romapervushin1234/pachoink-newton/blob/main/src/camera.js"
click node_generation_js "https://github.com/romapervushin1234/pachoink-newton/blob/main/src/generation.js"
click node_particles_js "https://github.com/romapervushin1234/pachoink-newton/blob/main/src/particles.js"
click node_scoring_js "https://github.com/romapervushin1234/pachoink-newton/blob/main/src/scoring.js"
click node_renderer_js "https://github.com/romapervushin1234/pachoink-newton/blob/main/src/renderer.js"
click node_ui_js "https://github.com/romapervushin1234/pachoink-newton/blob/main/src/ui.js"
click node_config_js "https://github.com/romapervushin1234/pachoink-newton/blob/main/src/config.js"
click node_newton_js "https://github.com/romapervushin1234/pachoink-newton/blob/main/src/Newtonian_pachoink.js"
click node_wasm_lib "https://github.com/romapervushin1234/pachoink-newton/blob/main/wasm/src/lib.rs"

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_server_js,node_index_html toneBlue
class node_main_js,node_state_js,node_input_js,node_camera_js,node_generation_js,node_particles_js,node_scoring_js,node_renderer_js,node_ui_js,node_config_js,node_newton_js toneAmber
class node_wasm_lib toneMint
```

## Components

### Host

Local server and delivery of the browser app

- [Server](https://github.com/romapervushin1234/pachoink-newton/blob/main/server.js): node server · Static host for the browser app · `server.js`
- [Entry Page](https://github.com/romapervushin1234/pachoink-newton/blob/main/index.html): html boot · Browser entry point that loads the client app · `index.html`

### Browser Client

JavaScript runtime for input, simulation, rendering, and UI

- [Main Loop](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/main.js): app coordinator · Top-level client coordinator and wiring point · `src/main.js`
- [State](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/state.js): shared state · Central source of truth for scene and progress · `src/state.js`
- [Input](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/input.js): controls · User interaction and event handling · `src/input.js`
- [Camera](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/camera.js): view transform · Viewport and world coordinate transforms · `src/camera.js`
- [Generation](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/generation.js): content gen · Creates levels, objects, or simulation content · `src/generation.js`
- [Particles](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/particles.js): simulation · Evolving world entities and motion · `src/particles.js`
- [Scoring](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/scoring.js): progress logic · Points, outcomes, and progression tracking · `src/scoring.js`
- [Renderer](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/renderer.js): drawing · Renders the world scene · `src/renderer.js`
- [UI](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/ui.js): overlay ui · On-screen controls and status overlays · `src/ui.js`
- [Config](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/config.js): tuning constants · Shared tunable parameters · `src/config.js`
- [Newton Bridge](https://github.com/romapervushin1234/pachoink-newton/blob/main/src/Newtonian_pachoink.js): wasm glue · JavaScript-facing wrapper around the simulation engine · `src/Newtonian_pachoink.js`

### WASM Compute

Rust module compiled to WebAssembly for heavy simulation work

- [WASM Core](https://github.com/romapervushin1234/pachoink-newton/blob/main/wasm/src/lib.rs): rust crate · Rust WebAssembly module for heavy compute · `wasm/src/lib.rs`

## Connections

- Server → Entry Page: serves · Hosts the browser entry page and client assets
- Entry Page → Main Loop: boots · Loads the JavaScript application entry point
- Main Loop → Input: wires · Connects input handling into the app loop
- Main Loop → State: owns · Coordinates the shared application state
- Main Loop → Generation: drives · Advances content or level generation
- Main Loop → Particles: updates · Runs the simulation entities and motion
- Main Loop → Scoring: evaluates · Computes points and progress from outcomes
- Main Loop → Renderer: ticks · Triggers frame rendering from updated state
- Main Loop → UI: updates · Refreshes overlays and controls
- Main Loop → Newton Bridge: uses · Calls into the simulation bridge for compute-heavy work
- Input → State: mutates · Converts user actions into state changes
- Generation → State: writes · Adds or changes world content in shared state
- Particles → State: reads/writes · Consumes and updates simulation state
- Scoring → State: reads · Derives score and progression from state
- Renderer → State: reads · Draws the current simulation state
- Renderer → Camera: applies · Uses camera transforms for world rendering
- UI → State: reads · Displays state-driven HUD and controls
- Newton Bridge → WASM Core: bridges · Wraps the Rust/WASM exports behind a JS interface
- Config → Generation: configures · Supplies tunable generation parameters
- Config → Particles: configures · Supplies simulation constants
- Config → Renderer: configures · Supplies rendering-related constants