# sp5555/simbiosis architecture

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

- Interactive diagram: https://gitdiagram.com/sp5555/simbiosis
- Repository: https://github.com/sp5555/simbiosis

## Overview

##### Project type and purpose
- This is a single–page JavaScript application (front-end only) that runs in the browser as a life simulator (“Simbiosis”).
- It contains a simulation core, a rendering engine, user input handling, and GUI/HUD overlays. There is no backend or external service.

##### File structure
- Top level:
- index.html, main entry point
- package.json / package-lock.json, project metadata
- src/, all application code
- src/app: application bootstrap (app.js)
- src/main.js: the main loop orchestrator
- src/input: gathers user input
- src/simulation: world model, map generator, entity behaviors
- src/renderer: scene construction, mesh managers, animations
- src/gui & src/hud: UI overlays
- src/utils: shared event emitters and helper functions

##### README for additional insights
- Confirms it’s served as static files, no backend
- Execution order: load index.html → main.js → initialize app → start local HTTP server

a. Main components
1. Browser environment (container)
2. App Bootstrap (src/app/app.js)
3. Input Manager (src/input/input.js)
4. Simulation Engine
– World Model, Map Generator
– Entities & Simulation Loop (src/simulation)
5. Rendering Engine
– Renderer Core, Mesh Managers, Animations, Tile/Vegetation modules
6. GUI Manager (src/gui)
7. HUD Manager (src/hud)
8. Shared Utilities / Event Bus (src/utils)
9. index.html + assets
b. Component relationships & interactions
- Browser loads index.html → app.js
- app.js → initializes main loop in main.js
- main loop cycle:
- Input Manager captures user events → emits events on Event Bus
- Simulation Engine consumes events, updates World Model
- Rendering Engine reads updated World Model → draws scene to WebGL/Canvas
- GUI & HUD Managers subscribe to state/events → update overlays
- Utilities (event-emitters, utils) are used by all modules for decoupled communication
c. Architectural patterns & design principles
- Modular separation: input, simulation, rendering, UI are distinct layers
- Event-driven communication: Event Bus as a pub/sub mechanism
- Main game loop: a central orchestrator (controls simulation and rendering updates)
- Data flow is unidirectional each frame: Input → Simulation → Rendering → GUI/HUD
d. Key technologies & libraries
- Vanilla JavaScript modules (ES6)
- Canvas or WebGL (renderer.js)
- No external frameworks (React, Vue, etc.)
- Simple HTTP server for static file hosting

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser and Entry Point
    subgraph "Browser Environment"
        B["Browser / index.html"]:::bootstrap
    end

    %% Bootstrap and Main Loop
    subgraph "Bootstrap & Main Loop"
        A["App Bootstrap\n(src/app/app.js)"]:::bootstrap
        C["Main Loop Orchestrator\n(src/main.js)"]:::bootstrap
    end

    %% Input Layer
    subgraph "Input Layer"
        I["Input Manager\n(src/input/input.js)"]:::managers
    end

    %% Shared Event Bus
    E(("Event Bus")):::utils

    %% Simulation Engine
    subgraph "Simulation Engine"
        SE["Simulation Engine Core\n(src/simulation/simulation.js)"]:::core
        subgraph "World Model"
            WM["World Model"]:::core
            MAP["Map\n(src/simulation/world/map.js)"]:::core
            MG["Map Generator\n(src/simulation/world/map-generator.js)"]:::core
            CL["Cell Definition\n(src/simulation/world/cell.js)"]:::core
        end
        EB["Entities & Behaviors\n(src/simulation/entities/vegetation.js)"]:::core
    end

    %% Rendering Engine
    subgraph "Rendering Engine"
        RE["Rendering Engine Core\n(src/renderer/renderer.js)"]:::core
        subgraph "Mesh Managers"
            MT["Land Tile Manager\n(src/renderer/mesh-managers/land-tile-manager.js)"]:::core
            WT["Water Tile Manager\n(src/renderer/mesh-managers/water-tile-manager.js)"]:::core
            VT["Vegetation Manager\n(src/renderer/mesh-managers/vegetation-manager.js)"]:::core
        end
        AN["Animation State\n(src/renderer/animation/animation-state.js)"]:::core
        REE["Renderer Entities\n(src/renderer/entities/vegetation.js)"]:::core
        subgraph "World / Tile"
            TD["Tile Definition\n(src/renderer/world/tile.js)"]:::core
            TCC["Tile Color Core\n(src/renderer/world/colors/tile-color-core.js)"]:::core
            TCD["Tile Color Data\n(src/renderer/world/colors/tile-color-data.js)"]:::core
        end
    end

    %% UI Overlays
    subgraph "UI Overlays"
        GU["GUI Manager\n(src/gui/gui-manager.js)"]:::managers
        HU["HUD Manager\n(src/hud/hud-manager.js)"]:::managers
    end

    %% Shared Utilities
    subgraph "Shared Utilities"
        EE["Event Emitters\n(src/utils/event-emitters.js)"]:::utils
        ED["Event Definitions\n(src/utils/events.js)"]:::utils
        RU["Random Utils\n(src/simulation/utils/random.js)"]:::utils
        CU["Color Utils\n(src/renderer/utils/color-utils.js)"]:::utils
        GU2["General Utils\n(src/renderer/utils/utils.js)"]:::utils
    end

    %% Connections
    B --> A
    A --> C
    C -->|"tick()"| I
    I -->|"onInput() / emits"| E
    E -->|"inputEvent"| SE
    SE -->|"updates"| WM
    WM -->|"provides worldState"| RE
    RE -->|"renderFrame()"| B
    WM -->|"worldState"| GU
    WM -->|"worldState"| HU
    RE -->|"overlayRender"| GU
    RE -->|"overlayRender"| HU

    %% Utilities Connections
    EE --> E
    ED --> E
    RU --> SE
    CU --> RE
    GU2 --> RE

    %% Click Events
    click B "https://github.com/sp5555/simbiosis/blob/main/index.html"
    click A "https://github.com/sp5555/simbiosis/blob/main/src/app/app.js"
    click C "https://github.com/sp5555/simbiosis/blob/main/src/main.js"
    click I "https://github.com/sp5555/simbiosis/blob/main/src/input/input.js"
    click SE "https://github.com/sp5555/simbiosis/blob/main/src/simulation/simulation.js"
    click MAP "https://github.com/sp5555/simbiosis/blob/main/src/simulation/world/map.js"
    click MG "https://github.com/sp5555/simbiosis/blob/main/src/simulation/world/map-generator.js"
    click CL "https://github.com/sp5555/simbiosis/blob/main/src/simulation/world/cell.js"
    click EB "https://github.com/sp5555/simbiosis/blob/main/src/simulation/entities/vegetation.js"
    click RU "https://github.com/sp5555/simbiosis/blob/main/src/simulation/utils/random.js"
    click RE "https://github.com/sp5555/simbiosis/blob/main/src/renderer/renderer.js"
    click MT "https://github.com/sp5555/simbiosis/blob/main/src/renderer/mesh-managers/land-tile-manager.js"
    click WT "https://github.com/sp5555/simbiosis/blob/main/src/renderer/mesh-managers/water-tile-manager.js"
    click VT "https://github.com/sp5555/simbiosis/blob/main/src/renderer/mesh-managers/vegetation-manager.js"
    click AN "https://github.com/sp5555/simbiosis/blob/main/src/renderer/animation/animation-state.js"
    click REE "https://github.com/sp5555/simbiosis/blob/main/src/renderer/entities/vegetation.js"
    click TD "https://github.com/sp5555/simbiosis/blob/main/src/renderer/world/tile.js"
    click TCC "https://github.com/sp5555/simbiosis/blob/main/src/renderer/world/colors/tile-color-core.js"
    click TCD "https://github.com/sp5555/simbiosis/blob/main/src/renderer/world/colors/tile-color-data.js"
    click CU "https://github.com/sp5555/simbiosis/blob/main/src/renderer/utils/color-utils.js"
    click GU2 "https://github.com/sp5555/simbiosis/blob/main/src/renderer/utils/utils.js"
    click GU "https://github.com/sp5555/simbiosis/blob/main/src/gui/gui-manager.js"
    click HU "https://github.com/sp5555/simbiosis/blob/main/src/hud/hud-manager.js"
    click EE "https://github.com/sp5555/simbiosis/blob/main/src/utils/event-emitters.js"
    click ED "https://github.com/sp5555/simbiosis/blob/main/src/utils/events.js"

    %% Styles
    classDef core fill:#AED6F1,stroke:#21618C,color:#1B2631;
    classDef managers fill:#ABEBC6,stroke:#1D8348,color:#1B2631;
    classDef utils fill:#D5D8DC,stroke:#7B7D7D,color:#1B2631;
    classDef bootstrap fill:#F9E79F,stroke:#B9770E,color:#1B2631;
    class E utils
    class E,Ee,ED,RU,CU,GU2 utils
```
