# steelclutchsean/elasto architecture

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

- Interactive diagram: https://gitdiagram.com/steelclutchsean/elasto
- Repository: https://github.com/steelclutchsean/elasto

## Overview

**Bungee Biker** is a **single-process desktop game** written in **Python**, structured as a small internal “engine” plus “game logic” packages, with **macOS app packaging** support (build script + `.spec` file strongly suggests a PyInstaller-style bundle).

- The **real-time game loop**
- **Input → simulation (physics) → game rules → rendering/UI**
- **Asset loading**
- The **packaging/build pipeline** for a standalone macOS app

##### File tree-driven decomposition (what components exist)
From the tree:

##### Entry / orchestration
- `main.py` — likely the executable entry point: initializes window, loads assets, creates `Game`, runs the loop, handles shutdown.

##### Core code packages
- `src/engine/physics.py` — physics integration, constraints (elastic bike), collisions.
- `src/engine/renderer.py` — rendering abstraction: draws world + UI.
- `src/game/game.py` — top-level game state machine and loop coordination (level switching, restart, timing, input mapping).
- `src/game/level.py` — level representation, loading/selection of test levels.
- `src/game/objects.py` — gameplay entities: bike, apples/collectibles, killers, etc.

##### Non-code / resources / build
- `assets/` — images/sounds/level assets (represent as a “resource store” used at runtime).
- `build_macos.sh`, `build_macos.spec`, `BUILD_MACOS.md`, `MACOS_APP_READY.md` — build pipeline for macOS `.app`.
- `setup.py` — packaging metadata (less important than `.spec`, but indicates distribution intent).

##### Build/Packaging Tooling (macOS app build)

Build as a separate lane because it’s architecturally important for this repo:
- `build_macos.sh` + `build_macos.spec` → produces **macOS `.app` bundle**

- Python Game Process → assets/: load textures/sounds/level definitions

**Top-level component: `main.py`**
- Responsibilities: init runtime, create window/context, instantiate `Game`, start loop.

**Game layer (`src/game/*`)**
- `Game` (`game.py`)
- Owns: current `Level`, game state (running/paused), timer/UI state, input mapping, restart/switch level.
- `Level` (`level.py`)
- Owns: static geometry, spawn points, object list, hazards/collectibles placement.
- Provides: objects to simulate/render; reset/reload logic.
- `Objects` (`objects.py`)
- Defines: Bike, Apple, Killer, maybe checkpoints/goal

**Engine layer (`src/engine/*`)**
- `Physics` (`physics.py`)
- Inputs: dt, object states, constraints, level geometry
- Outputs: updated transforms/velocities, collision events
- `Renderer` (`renderer.py`)
- Inputs: camera, object transforms, sprites, UI text/timer
- Outputs: frame presented to screen

**Resource layer**
- `assets/`
- textures/sprites, maybe audio, maybe level files (represent as data dependencies)

- `main.py` → `Game`
- `Game` → `Level`
- `Level` → `Objects` (composition)
- `Game` → `Physics` (per-tick step)
- `Physics` ↔ `Objects` (reads/writes state)
- `Renderer` → `Objects` (reads state for drawing)
- `Renderer` → `assets/` (loads textures/fonts)
- `Level` → `assets/` (if level data stored there)

This is the best way to capture accuracy for a physics game.

Sequence (typical; tailor to actual code after quick skim):
##### `Game.update(dt)`
- `Physics.step(dt, level_geometry, objects)`
- apply rule checks:
- collisions with apples → collect
- collisions with killers → death/restart
- finish condition check
- timer update
##### Present frame / sleep to maintain FPS

- **Layering**: `src/game` (rules/state) depends on `src/engine` (physics/render), not vice versa.
- **Game Loop** (fixed/variable timestep): show `dt` flowing into physics.
- **Entity/Object model**: `objects.py` defines entities; `level.py` aggregates them.
- **Data-driven resources**: `assets/` consumed by renderer/levels.

If the code shows it, annotate:
- Whether physics uses **constraint solving** / **spring** model (elastic bike).
- Whether renderer is tied to a framework (pygame) or abstract.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Runtime Lane (Context + Container + Components)
    %% =========================
    subgraph "Runtime (Single-Process Desktop Game)"
        direction TB

        %% ---- System Context (C4 L1) ----
        subgraph "System Context (C4 L1)"
            direction TB
            Player["Player"]:::external
            macOS["macOS (Windowing/Input/Audio/Filesystem)"]:::external
            AppCtx["Bungee Biker App (Python)"]:::system
            GfxLib["Graphics/Input Library (from requirements)"]:::external

            Player -->|"keyboard_input"| AppCtx
            AppCtx -->|"frames+audio"| macOS
            AppCtx <-->|"files+assets"| macOS
            AppCtx -->|"calls_API"| GfxLib
        end

        %% ---- Container (C4 L2) ----
        subgraph "Containers (C4 L2)"
            direction TB
            PyProc["Runtime Container: Python Game Process"]:::container
            Assets[("Resource Container: assets/")]:::data
            ReqDoc["Runtime Dependencies: requirements.txt"]:::doc

            PyProc -->|"load_textures+audio+levels"| Assets
            PyProc -.->|"declares_deps"| ReqDoc
        end

        AppCtx -->|"executes_as"| PyProc

        %% ---- Component (C4 L3) ----
        subgraph "Components (C4 L3) inside Python Game Process"
            direction TB

            Main["main.py (Entry/Bootstrap)"]:::component

            subgraph "Game Layer (src/game)"
                direction TB
                Game["Game (game.py)"]:::game

                subgraph "Game Responsibilities (logical subcomponents)"
                    direction TB
                    InputMap["Input Mapping/Handling"]:::subcomp
                    Rules["Game Rules/State Machine"]:::subcomp
                    LevelMgmt["Level Switch/Restart"]:::subcomp
                    UIState["Timer/UI State"]:::subcomp
                end

                Level["Level (level.py)"]:::game
                Objects["Gameplay Objects (objects.py)"]:::game
            end

            subgraph "Engine Layer (src/engine)"
                direction TB
                Physics["Physics Engine (physics.py)"]:::engine
                Renderer["Rendering Engine (renderer.py)"]:::engine

                subgraph "Physics Internals (logical)"
                    direction TB
                    Integrator["Integration (dt)"]:::subcomp
                    Constraints["Constraints/Springs"]:::subcomp
                    Collisions["Collision Detection/Resolution"]:::subcomp
                end

                subgraph "Renderer Internals (logical)"
                    direction TB
                    WorldDraw["World Rendering"]:::subcomp
                    UIDraw["UI Overlay"]:::subcomp
                    AssetCache["Asset Loading/Cache"]:::subcomp
                end
            end

            %% Game Loop boundary
            Loop["Game Loop (per frame): Input → Update → Render"]:::loop

            Main -->|"init_window+load_assets+create_Game"| Game
            Main -->|"start_loop"| Loop
            Loop -->|"tick"| Game

            %% Responsibilities wiring (keep vertical)
            Game -->|"handle_input(input_state)"| InputMap
            Game -->|"update_state+rules"| Rules
            Game -->|"level_control"| LevelMgmt
            Game -->|"timer_ui_update"| UIState

            Game -->|"owns_current"| Level
            Level -->|"composes_entities"| Objects

            %% Core runtime calls/data flow
            Game -->|"step(dt)"| Physics
            Game -->|"draw(frame)"| Renderer

            %% Data dependencies
            Physics <-->|"read/write_object_state"| Objects
            Physics -->|"reads_level_geometry"| Level
            Physics -->|"emits_collision_events"| Rules

            Renderer -->|"reads_transforms+sprites"| Objects
            Renderer -->|"reads_level_geometry"| Level
            Renderer -->|"loads_textures+fonts+audio"| Assets
            Level -->|"load_level_data"| Assets

            %% Tie loop concepts to payload
            Loop -->|"input_state"| InputMap
            Loop -->|"dt"| Physics
            Physics -->|"transforms+velocities"| Objects
            Renderer -->|"present_frame"| GfxLib
        end

        PyProc -->|"contains"| Main
    end

    %% =========================
    %% Build / Packaging Lane
    %% =========================
    subgraph "Build/Packaging (macOS App)"
        direction TB

        BuildScript["build_macos.sh (Build Script)"]:::build
        Spec["build_macos.spec (Bundle Config)"]:::build
        IconGen["create_icon.py (Icon Generation)"]:::build
        BuildDocs["BUILD_MACOS.md (Build Notes)"]:::doc
        ReadyDoc["MACOS_APP_READY.md (Packaging Checklist)"]:::doc
        SetupMeta["setup.py (Packaging Metadata)"]:::doc
        DevDoc["DEVELOPMENT.md (Dev Workflow Notes)"]:::doc

        AppBundle["macOS .app Bundle (Artifact)"]:::artifact

        %% Build-time relationships (dashed)
        IconGen -.->|"produces_app_icon"| AppBundle
        BuildScript -.->|"invokes_packager"| Spec
        Spec -.->|"bundles_python+src+assets"| AppBundle
        BuildScript -.->|"produces"| AppBundle

        %% Supporting docs
        BuildDocs -.->|"documents"| BuildScript
        ReadyDoc -.->|"checklist_for"| AppBundle
        SetupMeta -.->|"metadata_for_distribution"| AppBundle
        DevDoc -.->|"dev_setup_for"| BuildScript

        %% Build consumes runtime inputs
        Assets -.->|"bundled_into"| AppBundle
        Main -.->|"entry_in_bundle"| AppBundle
        ReqDoc -.->|"deps_ref"| Spec
    end

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click Main "https://github.com/steelclutchsean/elasto/blob/claude/elasto-mania-prd-3PdUP/main.py"
    click Game "https://github.com/steelclutchsean/elasto/blob/claude/elasto-mania-prd-3PdUP/src/game/game.py"
    click Level "https://github.com/steelclutchsean/elasto/blob/claude/elasto-mania-prd-3PdUP/src/game/level.py"
    click Objects "https://github.com/steelclutchsean/elasto/blob/claude/elasto-mania-prd-3PdUP/src/game/objects.py"
    click Physics "https://github.com/steelclutchsean/elasto/blob/claude/elasto-mania-prd-3PdUP/src/engine/physics.py"
    click Renderer "https://github.com/steelclutchsean/elasto/blob/claude/elasto-mania-prd-3PdUP/src/engine/renderer.py"
    click Assets "https://github.com/steelclutchsean/elasto/tree/claude/elasto-mania-prd-3PdUP/assets/"
    click ReqDoc "https://github.com/steelclutchsean/elasto/blob/claude/elasto-mania-prd-3PdUP/requirements.txt"
    click BuildScript "https://github.com/steelclutchsean/elasto/blob/claude/elasto-mania-prd-3PdUP/build_macos.sh"
    click Spec "https://github.com/steelclutchsean/elasto/blob/claude/elasto-mania-prd-3PdUP/build_macos.spec"
    click BuildDocs "https://github.com/steelclutchsean/elasto/blob/claude/elasto-mania-prd-3PdUP/BUILD_MACOS.md"
    click ReadyDoc "https://github.com/steelclutchsean/elasto/blob/claude/elasto-mania-prd-3PdUP/MACOS_APP_READY.md"
    click IconGen "https://github.com/steelclutchsean/elasto/blob/claude/elasto-mania-prd-3PdUP/create_icon.py"
    click SetupMeta "https://github.com/steelclutchsean/elasto/blob/claude/elasto-mania-prd-3PdUP/setup.py"
    click DevDoc "https://github.com/steelclutchsean/elasto/blob/claude/elasto-mania-prd-3PdUP/DEVELOPMENT.md"

    %% =========================
    %% Styles (Color is critical)
    %% =========================
    classDef external fill:#F3F4F6,stroke:#6B7280,stroke-width:1px,color:#111827
    classDef system fill:#DBEAFE,stroke:#1D4ED8,stroke-width:2px,color:#0B1F4B
    classDef container fill:#E0E7FF,stroke:#3730A3,stroke-width:2px,color:#111827
    classDef component fill:#D1FAE5,stroke:#065F46,stroke-width:2px,color:#052E2B
    classDef game fill:#BBF7D0,stroke:#047857,stroke-width:2px,color:#052E2B
    classDef engine fill:#FFE4E6,stroke:#9F1239,stroke-width:2px,color:#3B0A1A
    classDef subcomp fill:#ECFDF5,stroke:#10B981,stroke-width:1px,color:#064E3B
    classDef data fill:#FEF9C3,stroke:#A16207,stroke-width:2px,color:#3A2A00
    classDef build fill:#FFF7ED,stroke:#C2410C,stroke-width:2px,color:#3A1406
    classDef artifact fill:#EDE9FE,stroke:#5B21B6,stroke-width:3px,color:#1F0A3A
    classDef doc fill:#E5E7EB,stroke:#374151,stroke-width:1px,color:#111827
    classDef loop fill:#CFFAFE,stroke:#0E7490,stroke-width:2px,color:#083344,stroke-dasharray: 6 4
```
