# amundsenzach/gravitic-zephyr architecture

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

- Interactive diagram: https://gitdiagram.com/amundsenzach/gravitic-zephyr
- Repository: https://github.com/amundsenzach/gravitic-zephyr

## Overview

##### Project type and purpose
- Type: Single-page, client-side web game (static site hosted on GitHub Pages).
- Purpose: Simulate realistic orbital mechanics in real time with interactive controls and dynamic trajectory guides.

##### File structure
- index.html – the application entry point.
- resources/styles/main.css – styling layer.
- resources/js/
– entities/ (CelestialBody, Spacecraft, OrbitPredictor) – core physics models and orbital prediction.
– game/ (GameState, Camera, RenderStarfield) – core game loop, world state management and rendering engine.
– ui/ (UIManager) – HUD overlays, buttons, trajectory guides.
– utils/ (InputManager, TouchControls, MathUtils) – input abstraction, math helpers and cross-device control support.
– main.js – orchestrates initialization, module wiring and the main animation loop.

##### README for additional architectural hints
- No backend or external services – all logic runs in the browser.
- Components focus on real-time physics, rendering, and user input.

##### Components
a. Browser Environment
– HTML renderer & CSS engine
– Canvas API / WebGL (if used)
– requestAnimationFrame loop
b. Application Shell (main.js)
– Bootstraps modules, starts the game loop
c. Input Layer (utils/InputManager, TouchControls)
– Captures keyboard, mouse, touch events
– Normalizes events into game commands
d. Core Game Engine
– GameState: holds positions, velocities of entities
– Camera: maps world coordinates to viewport
– RenderStarfield: draws background and entities
– OrbitPredictor (entities): computes guide arcs
e. Entity Models (entities/CelestialBody, Spacecraft)
– Data structures and physics update methods
f. UI Layer (ui/UIManager)
– Renders on-screen controls, HUD, trajectory guides
g. Utility Services (utils/MathUtils)
– Provides vector math, numeric integration helpers
h. Static Assets & Styles (resources/styles, index.html)
– CSS for layout, styling; HTML for script & style inclusion

##### Relationships and interactions
- index.html loads CSS and main.js
- main.js → initializes InputManager, GameState, UIManager, Camera, RenderStarfield
- InputManager → pushes input events into GameState or UIManager
- Each animation frame:
1. InputManager polls events → updates control state
2. GameState updates entities via physics (MathUtils, CelestialBody, Spacecraft)
3. OrbitPredictor computes paths for UIManager
4. Camera computes view transform
- All modules communicate directly in the browser memory space—no network calls.

##### Important architectural patterns
- Modular separation by concern:
– Physics (entities + utils)
– Rendering (game + ui)
– Input abstraction (utils)
- Central game loop coordinating state → update → render
- Singleton pattern for managers (only one InputManager, UIManager, GameState)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser Environment"
        index["index.html"]:::static
        css["main.css"]:::static
        canvas["Canvas API / WebGL"]:::ui
    end

    subgraph "Application Shell"
        mainshell["main.js (Boot & Loop)"]:::shell
    end

    subgraph "Input Layer"
        inputmgr["InputManager"]:::input
        touch["TouchControls"]:::input
    end

    subgraph "Utility Services"
        mu["MathUtils"]:::physics
    end

    subgraph "Physics Modules"
        cb["CelestialBody"]:::physics
        sc["Spacecraft"]:::physics
        op["OrbitPredictor"]:::physics
    end

    subgraph "Core Game Engine"
        gs["GameState"]:::engine
        cam["Camera"]:::engine
        rs["RenderStarfield"]:::engine
    end

    subgraph "UI Layer"
        ui["UIManager"]:::ui
    end

    index --> mainshell
    index --> css
    mainshell --> inputmgr
    mainshell --> touch
    mainshell --> gs
    mainshell --> cam
    mainshell --> rs
    mainshell --> ui

    inputmgr --> gs
    inputmgr --> ui

    gs --> cb
    gs --> sc
    gs --> op

    op --> ui

    gs --> cam

    cam --> canvas
    rs --> canvas
    ui --> canvas

    cb --> mu
    sc --> mu
    op --> mu

    click index "https://github.com/amundsenzach/gravitic-zephyr/blob/main/index.html"
    click css "https://github.com/amundsenzach/gravitic-zephyr/blob/main/resources/styles/main.css"
    click mainshell "https://github.com/amundsenzach/gravitic-zephyr/blob/main/resources/js/main.js"
    click inputmgr "https://github.com/amundsenzach/gravitic-zephyr/blob/main/resources/js/utils/InputManager.js"
    click touch "https://github.com/amundsenzach/gravitic-zephyr/blob/main/resources/js/utils/TouchControls.js"
    click gs "https://github.com/amundsenzach/gravitic-zephyr/blob/main/resources/js/game/GameState.js"
    click cam "https://github.com/amundsenzach/gravitic-zephyr/blob/main/resources/js/game/Camera.js"
    click rs "https://github.com/amundsenzach/gravitic-zephyr/blob/main/resources/js/game/RenderStarfield.js"
    click cb "https://github.com/amundsenzach/gravitic-zephyr/blob/main/resources/js/entities/CelestialBody.js"
    click sc "https://github.com/amundsenzach/gravitic-zephyr/blob/main/resources/js/entities/Spacecraft.js"
    click op "https://github.com/amundsenzach/gravitic-zephyr/blob/main/resources/js/entities/OrbitPredictor.js"
    click ui "https://github.com/amundsenzach/gravitic-zephyr/blob/main/resources/js/ui/UIManager.js"
    click mu "https://github.com/amundsenzach/gravitic-zephyr/blob/main/resources/js/utils/MathUtils.js"

    classDef static fill:#eeeeee,stroke:#888,stroke-width:1px
    classDef physics fill:#cfe2f3,stroke:#2f75b5,stroke-width:1px
    classDef engine fill:#d9ead3,stroke:#6aa84f,stroke-width:1px
    classDef ui fill:#fff2cc,stroke:#b45f06,stroke-width:1px
    classDef input fill:#f4cccc,stroke:#a80000,stroke-width:1px
    classDef shell fill:#d9d9d9,stroke:#999999,stroke-width:1px
```
