# openchanter/ecosystems architecture

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

- Interactive diagram: https://gitdiagram.com/openchanter/ecosystems
- Repository: https://github.com/openchanter/ecosystems

## Overview

This is a **single-process desktop simulation/game** written in **C#/.NET** using a **Raylib port (Vinculum)** for **3D rendering + input + windowing**. It simulates an **ecosystem** (fox/rabbit/bush + fluids like water) on a **procedurally generated island**, provides **debug/UI menus**, and can **log simulation data** that is later **visualized by a separate Python plotting script**.

So the “system” is not microservices; it’s best represented as:
- a **runtime in-process architecture** (game loop, simulation, rendering, input, UI, logging),
- plus an **offline analysis pipeline** (logs → Python/pandas/matplotlib).

##### What the file tree implies about architecture (map files → components)
Top-level C# sources indicate a compact codebase where major subsystems are split by domain:

- `Program.cs`
Likely **entry point** + **main loop orchestration** (spawning organisms, island generation, calling update/render). README explicitly says spawning is modified here.
- `Engine.cs`
Likely the **core engine loop / orchestration layer**: update ticks, timing, camera movement, input handling, scene management, rendering calls.
- `Organism.cs`
**Entity + behavior**: organism traits, stats (hydration/food), evolution, pathing targets (debug mentions pathing target), interactions (predation/herbivory).
- `Fluid.cs`
**Fluid model** (water) and hydration sources / interactions.
- `shader/lit_vert.glsl`, `shader/lit_frag.glsl`
**Rendering pipeline assets**: lighting shader used by models (README shows applying `lit` shader).
- `plot/main.py`
**Offline visualization tool** consuming logs produced by the simulation (pandas/matplotlib).
- `.github/workflows/build.yml`
**CI**: build & publish workflow (include in a “Dev/Delivery” view if desired).
- `readme-resources/*`
Documentation images (not runtime).

Goal: show what runs in-process, what external libraries are used, and major internal modules.

##### Ecosystems.exe (.NET process)
- **Program (Entry / Bootstrap)** — `Program.cs`
- **Engine / Game Loop** — `Engine.cs`
- **World Generation (Island/Heightmap/Terrain)** — likely inside `Program.cs` and/or `Engine.cs` (README mentions “random island generator” and `groundHeightmap`)
- **Simulation / ECS-like domain** (even if not formal ECS):
- **Organism System** — `Organism.cs`
- **Fluid System** — `Fluid.cs`
- **Interactions** (predation, eating, hydration) — likely within organism logic
- **Rendering Subsystem**
- **Model/Texture Loader**
- **Shader Manager** → uses `shader/lit_*.glsl`
- **Input & Camera Controller** (WASD, Space, Ctrl, Shift; click interaction)
- **UI / Menus**
- **Main Menu (Tab)**
- **God Menu (click organism)**
- **Debug Overlay** (stats above organisms, pathing target)
- **Logging Subsystem**

- **Vinculum/Raylib** (Rendering/Input/Window/Audio if used)
- **Filesystem** (for loading textures/models/shaders, and writing logs)

- `Program → Engine.Start()/Run()` (bootstrap)
- `Engine Loop → Simulation.Update(dt)` (control flow)
- `Simulation → Logging.Append(metrics/events)` (data)
- `Input → Engine/UI` and `Input → Interaction (raycast/pick organism)` (control + data)
- `Shader Files (.glsl) → Shader Manager → Renderer` (asset dependency)
- `Models/Textures → Loader → Renderer/Organisms` (asset dependency)
- `Logging → Filesystem(log files)` (output)

- **Blue** = control/orchestration (Program/Engine)
- **Green** = domain simulation (Organism/Fluid/WorldGen)
- **Orange** = rendering/assets (Shaders/Models/Textures)
- **Purple** = UI/Debug
- **Gray** = external dependencies (Raylib, filesystem)

Goal: show the most important truth of a simulation game: *the order of operations*.

##### UI Handling
- Tab menu toggles
- Click → selection → god menu actions (kill/feed/hydrate)
##### Simulation Step
- Update organisms (needs, traits, movement/pathing, interactions)
- Update fluids/resources
##### Present Frame

Goal: show the offline analysis workflow as a separate subsystem.

Components:
- **Simulation Logging (C#)** → produces **Log Files**
- **Python Plot Tool** (`plot/main.py`)
- **pandas** (ingest/transform)
- **Graphs/Plots** (output)

- `C# Logging → log files → Python tool → plots`

- log location (if known),
- log schema (metrics per tick? per organism? aggregate?).

##### Search for “logging” write points
- What triggers logging (menu toggle, always-on, debug).
- Document where logs are written and in what format.
##### Map organism lifecycle
- Spawn path (README: `placeFeatures(...)` in `Program.cs`)
- Update path (likely method on `Organism`)
- Interaction path (eat/hydrate/predation)
##### Rendering wiring
- Where shaders are loaded (reads `shader/lit_*.glsl`)
- Where models/textures are loaded (README shows example calls)
##### Input → interaction
- Left click: interaction + organism selection for god menu implies picking logic (raycast or bounding checks). Show this as a distinct “Selection/Interaction” component even if it’s just functions.

##### What to explicitly label
- **File anchor**: e.g., “Engine (Engine.cs)”
- **Responsibility**: one short line
- **Key data** it owns/produces:
- Organism list / traits
- Terrain heightmap
- Logs (metrics/events)
- Shader handles / model handles
- **Key dependencies**:
- “Uses Raylib API”
- “Reads shader/*.glsl”
- “Writes logs to disk”

##### Diagramming conventions (make it principal-engineer-grade)
- **Boundaries**
- One big boundary: “.NET Process: ecosystems”
- Outside boundary: “Vinculum/Raylib”, “Filesystem”, “Python runtime”
- **Consistent naming**
- Use the same terms as README: “God Menu”, “Debug mode”, “Logging Display”, “Island generator”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ========= External Inputs / Dependencies =========
    subgraph "External Inputs & Dependencies"
        KBD["Keyboard"]:::external
        MSE["Mouse"]:::external
        RAY["Vinculum / Raylib (Windowing + Input + 3D Rendering)"]:::external
        FS["Filesystem"]:::external
    end

    %% ========= .NET Single Process =========
    subgraph "Single .NET Process: ecosystems.exe"
        PRG["Program (Entry + Bootstrap + Spawning)"]:::control
        ENG["Engine (Main Loop + Orchestration)"]:::control

        subgraph "Input & Camera"
            INP["Input Handler (poll keyboard/mouse)"]:::control
            CAM["Camera / Movement Controller (WASD + modifiers)"]:::control
            PICK["Selection / Interaction (click pick organism)"]:::sim
        end

        subgraph "UI / Debug"
            UI["UI Layer"]:::ui
            MENU["Main Menu (Tab)"]:::ui
            GOD["God Menu (selected organism actions)"]:::ui
            DBG["Debug Overlay (stats + pathing target)"]:::ui
        end

        subgraph "Simulation"
            WGEN["World/Island Generator (heightmap/terrain)"]:::sim
            ORG["Organism System (traits + needs + movement + interactions)"]:::sim
            FLD["Fluid System (water + hydration sources)"]:::sim
            STATE["World State (terrain + organisms + fluids)"]:::data
        end

        subgraph "Rendering"
            RENDER["Renderer (draw terrain + organisms + UI)"]:::render
            SHM["Shader Manager"]:::render
            MTM["Model/Texture Loader"]:::render
            SHV["Lit Vertex Shader (GLSL asset)"]:::asset
            SHF["Lit Fragment Shader (GLSL asset)"]:::asset
        end

        subgraph "Logging"
            LOG["Logging Subsystem (metrics/events)"]:::log
            LOGF[("Log Files (on disk)")]:::storage
        end
    end

    %% ========= Offline Analysis =========
    subgraph "Offline Analysis Pipeline"
        PY["Python Plot Tool (pandas + matplotlib)"]:::analysis
        PLOTS["Graphs / Plots (output)"]:::analysis
    end

    %% ========= Control Flow (solid) =========
    PRG -->|"Start()/Run()"| ENG
    ENG -->|"PollInput()"| INP
    INP -->|"UpdateCamera()"| CAM
    INP -->|"ClickPick()"| PICK

    ENG -->|"HandleUI()"| UI
    UI -->|"ToggleTabMenu"| MENU
    PICK -->|"SelectOrganism"| GOD
    UI -->|"ReadStateForDebug"| DBG

    ENG -->|"SimUpdate(dt)"| WGEN
    ENG -->|"SimUpdate(dt)"| ORG
    ENG -->|"SimUpdate(dt)"| FLD
    PICK -->|"MutateSimState(kill/feed/hydrate)"| ORG
    ORG -->|"Consume/Predate/Hydrate"| FLD

    ENG -->|"AppendLogs()"| LOG
    LOG -->|"Write()"| LOGF

    ENG -->|"RenderFrame()"| RENDER
    RENDER -->|"UseShaders()"| SHM
    RENDER -->|"LoadModels/Textures()"| MTM
    SHM -->|"Compile/Bind"| RAY
    RENDER -->|"DrawCalls"| RAY
    INP -->|"RaylibInputAPI"| RAY

    %% ========= Data Dependencies (dashed) =========
    WGEN -.->|"ProducesTerrain"| STATE
    ORG -.->|"UpdatesEntities"| STATE
    FLD -.->|"UpdatesResources"| STATE

    RENDER -.->|"ReadsWorldState"| STATE
    DBG -.->|"ReadsWorldState"| STATE
    LOG -.->|"ReadsMetricsFromState"| STATE

    %% ========= Asset / File Dependencies (dotted) =========
    FS -.->|"ReadShaderAsset"| SHV
    FS -.->|"ReadShaderAsset"| SHF
    SHV -.->|"LoadedBy"| SHM
    SHF -.->|"LoadedBy"| SHM
    FS -.->|"ReadModels/Textures"| MTM
    FS -.->|"WriteLogs"| LOGF

    %% ========= Offline Pipeline =========
    LOGF -->|"Ingest"| PY
    PY -->|"Generate"| PLOTS

    %% ========= Click Events (from component_mapping) =========
    click PRG "https://github.com/openchanter/ecosystems/blob/main/Program.cs"
    click ENG "https://github.com/openchanter/ecosystems/blob/main/Engine.cs"
    click ORG "https://github.com/openchanter/ecosystems/blob/main/Organism.cs"
    click FLD "https://github.com/openchanter/ecosystems/blob/main/Fluid.cs"
    click SHV "https://github.com/openchanter/ecosystems/blob/main/shader/lit_vert.glsl"
    click SHF "https://github.com/openchanter/ecosystems/blob/main/shader/lit_frag.glsl"
    click PY "https://github.com/openchanter/ecosystems/blob/main/plot/main.py"

    %% CI is not runtime; show as detached node in external area
    CI["CI: Build & Publish Workflow"]:::devops
    click CI "https://github.com/openchanter/ecosystems/blob/main/.github/workflows/build.yml"

    %% Keep vertical by attaching CI below external deps
    FS -->|"BuildArtifacts/Repo"| CI

    %% ========= Styles =========
    classDef control fill:#1f77b4,stroke:#0f3d66,color:#ffffff,stroke-width:1px
    classDef sim fill:#2ca02c,stroke:#145214,color:#ffffff,stroke-width:1px
    classDef render fill:#ff7f0e,stroke:#8a3f00,color:#ffffff,stroke-width:1px
    classDef ui fill:#9467bd,stroke:#4d2a73,color:#ffffff,stroke-width:1px
    classDef log fill:#8c564b,stroke:#4a2b24,color:#ffffff,stroke-width:1px
    classDef storage fill:#c49c94,stroke:#6b3d35,color:#1b1b1b,stroke-width:1px
    classDef data fill:#98df8a,stroke:#1f7a1f,color:#102010,stroke-width:1px
    classDef asset fill:#f2c14e,stroke:#9a6b00,color:#2b2000,stroke-width:1px
    classDef external fill:#7f7f7f,stroke:#3a3a3a,color:#ffffff,stroke-width:1px
    classDef analysis fill:#17becf,stroke:#0b5d66,color:#ffffff,stroke-width:1px
    classDef devops fill:#4c566a,stroke:#2e3440,color:#ffffff,stroke-width:1px
```
