# mgvez/jsorrery architecture

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

- Interactive diagram: https://gitdiagram.com/mgvez/jsorrery
- Repository: https://github.com/mgvez/jsorrery

## Overview

Based on our analysis of the file tree and the README, jsOrrery is a WebGL/JavaScript-based simulation that models the solar system with accurate orbital mechanics. The project is primarily a client-side application which renders a dynamic orrery (a mechanical model of the solar system) through computed positions of the planets and moons based on real date inputs.

##### Main Components
- Simulation/Core Engine:
- This consists of the code in the “src/core” folder (including Universe, CelestialBody, and constants) that drives the simulation's state.
- The “src/algorithm” directory (Gravity, MoveAlgorithm, OrbitalElements, Quadratic, Ticker) handles the mathematical and physics-based calculations required to update positions.
- Graphics/Rendering Modules:
- The rendering is split between “src/graphics2d” and “src/graphics3d”. These modules manage drawing labels, orbits, 3D bodies, cameras, particles (MilkyWayParticles) and related visual effects.
- Assets (shaders, images, data files) and “src/three” (custom Three.js classes, like RingGeometry2) support the WebGL-based rendering pipeline.
- User Interface (GUI):
- Found in “src/gui”, this component offers interactive features such as input fields, buttons, sliders, and date pickers that allow configuration of the simulation. It also includes auxiliary modules like ExportValues and Preloader.
- Scenario Management:
- The “src/scenario” folder includes a loader and multiple pre-defined simulation scenarios (for the Solar System, Apollo missions, satellite simulations, etc.), plus scenario-specific data and additional celestial body definitions.
- Resource Loading and Utilities:
- “src/loaders” (ResourceLoader) is responsible for asynchronously loading assets and initializing resources.

##### Recognize Build/Deployment Components
- The build process is managed through webpack (webpack.config.js) with configurations that compile the source into the “dist” directory.
- The “package.json” file indicates dependencies and scripts (like npm start for local development) and “server.js” suggests there’s a lightweight local server for development or testing.

##### Interactions Between Components
- The simulation engine (core and algorithm) feeds computed positions and orbital data to the rendering modules.
- The rendering modules, using Three.js and WebGL, display the simulation visually; they interact with shader files (stated in “assets/shaders”) to achieve specific visual effects.
- The GUI collects user input which allows dynamic control (e.g., changing dates or simulation parameters) modifying the simulation engine’s behavior.
- Scenario management modules load predefined configurations that set up initial states for the simulation engine.
- The resource loader ensures that all required assets (from “assets/data”, images, and shader files) are available before initializing the simulation.

##### Key Architectural Patterns/Design Principles
- Separation of Concerns – Different directories handle simulation logic, rendering (2D/3D), GUI, and scenario configurations, reflecting a modular structure.
- Data Flow – The simulation calculates positions (via the algorithm modules) which then get rendered in 3D/2D; the GUI and scenarios serve as configuration layers that modify this behavior.
- Use of External Technologies – WebGL (for rendering), Three.js (for 3D graphics and camera handling), and webpack (for build automation) are central to the architecture.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Resource/Asset Loading Layer
    subgraph "Resource/Asset Loading"
        RL["Resource Loader (ResourceLoader)"]:::resource
        U["Utilities (ColorUtils, GeoCoord, JD, etc.)"]:::resource
    end

    %% Scenario Management Layer
    subgraph "Scenario Management"
        SC["Scenarios (Loader, SolarSystem, Apollo, etc.)"]:::scenario
    end

    %% User Interface (GUI) Layer
    subgraph "User Interface (GUI)"
        GUI["GUI (InputDate, Field, ExportValues, etc.)"]:::gui
    end

    %% Simulation Engine Layer
    subgraph "Simulation Engine"
        C["Core (Universe, CelestialBody, constants)"]:::simulation
        A["Algorithms (Gravity, MoveAlgorithm, OrbitalElements, Quadratic, Ticker)"]:::simulation
    end

    %% Graphics/Rendering Layer
    subgraph "Graphics/Rendering"
        G3["Graphics 3D (Body3d, CameraManager, Scene, Sun)"]:::graphics
        G2["Graphics 2D (Labels)"]:::graphics
        SH["Shaders (assets/shaders)"]:::graphics
        T["Three.js Extensions (RingGeometry2)"]:::graphics
    end

    %% Build/Deployment Components (Standalone)
    subgraph "Build/Deployment"
        W["webpack.config.js"]:::build
        P["package.json"]:::build
        S["server.js"]:::build
    end

    %% Relationships
    RL -->|"feeds"| C
    RL -->|"feeds"| G3
    U -->|"supports"| C
    U -->|"supports"| G3
    SC -->|"configures"| GUI
    SC -->|"configures"| C
    GUI -->|"updates"| C
    C -->|"provides state to"| G3
    A -->|"calculates for"| G3

    %% Click Events
    click C "https://github.com/mgvez/jsorrery/tree/master/src/core"
    click A "https://github.com/mgvez/jsorrery/tree/master/src/algorithm"
    click G3 "https://github.com/mgvez/jsorrery/tree/master/src/graphics3d"
    click G2 "https://github.com/mgvez/jsorrery/tree/master/src/graphics2d"
    click SH "https://github.com/mgvez/jsorrery/tree/master/assets/shaders"
    click T "https://github.com/mgvez/jsorrery/tree/master/src/three"
    click GUI "https://github.com/mgvez/jsorrery/tree/master/src/gui"
    click SC "https://github.com/mgvez/jsorrery/tree/master/src/scenario"
    click RL "https://github.com/mgvez/jsorrery/tree/master/src/loaders"
    click U "https://github.com/mgvez/jsorrery/tree/master/src/utils"
    click W "https://github.com/mgvez/jsorrery/blob/master/webpack.config.js"
    click P "https://github.com/mgvez/jsorrery/blob/master/package.json"
    click S "https://github.com/mgvez/jsorrery/blob/master/server.js"

    %% Styles
    classDef simulation fill:#99ccff,stroke:#3366cc,stroke-width:2px;
    classDef graphics fill:#ccffcc,stroke:#339933,stroke-width:2px;
    classDef gui fill:#ffccff,stroke:#cc33cc,stroke-width:2px;
    classDef scenario fill:#ffffcc,stroke:#cccc33,stroke-width:2px;
    classDef resource fill:#f2f2f2,stroke:#999999,stroke-width:2px;
    classDef build fill:#ffdd99,stroke:#ff9900,stroke-width:2px;
```
