# bysggit/gobonsaisetup architecture

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

- Interactive diagram: https://gitdiagram.com/bysggit/gobonsaisetup
- Repository: https://github.com/bysggit/gobonsaisetup

## Overview

#### Purpose and Entry Points
This repository reverse-engineers the native GoBonsai executable and reimplements its simulation as a browser application with executable-parity goals. The original binary and extracted/decompiled evidence are retained at `GoBonsai.exe`, `decompiled/full.c`, and `installed game/GoBonsai.exe`. The web runtime starts at `gobonsai-web/src/main.ts`, mounts `gobonsai-web/src/App.vue`, and presents simulation/UI components including `gobonsai-web/src/components/BonsaiViewer.vue`.

#### UI-to-Engine Control Boundary
Vue components own browser presentation and user interaction; the engine is isolated beneath `gobonsai-web/src/engine`. `gobonsai-web/src/components/Dashboard.vue` likely exposes controls/state, while `gobonsai-web/src/engine/BonsaiController.ts` coordinates tree lifecycle and interaction. `gobonsai-web/src/engine/GrowthController.ts` drives growth updates. This separation keeps rendering/UI concerns outside native-behavior emulation.

#### Canonical Tree Model
Tree state is represented as an object graph rooted in `gobonsai-web/src/engine/TreeRoot.ts`, composed of sections and leaves in `gobonsai-web/src/engine/TreeSection.ts` and `gobonsai-web/src/engine/TreeLeaf.ts`. Shared shapes and state contracts reside in `gobonsai-web/src/engine/TreeInterfaces.ts` and `gobonsai-web/src/engine/TreeState.ts`. Runtime section behavior/type dispatch is modeled by `gobonsai-web/src/engine/SectionRuntimeType.ts`.

#### Frame Growth Pipeline
The principal simulation flow is organized in `gobonsai-web/src/engine/growth/GrowthFramePipeline.ts`: frame state enters, strict/parity branching is selected, and mutations are applied to the tree/world. The original growth-tick translation is `gobonsai-web/src/engine/growth/sub40DC90GrowthTick.ts`; a native-aligned route is maintained in `gobonsai-web/src/engine/growth/strictExeSimPath.ts`. Supporting stages include light tracing (`gobonsai-web/src/engine/growth/lightTracingSub40E460.ts`), leaf metabolism (`gobonsai-web/src/engine/growth/leafMetabolismSub416510.ts`), and per-frame physics (`gobonsai-web/src/engine/growth/perFramePhysicsSub4143E0.ts`).

#### Growth, Branching, and Structural Mutation
Branching decisions dispatch through `gobonsai-web/src/engine/growth/branchingDispatcherSub417F40.ts`; twig update and elongation are handled by `gobonsai-web/src/engine/growth/twigUpdateSub417C90.ts` and `gobonsai-web/src/engine/growth/twigLengthGrowthSub418BD0.ts`. Structural removal/detachment is a distinct mutation boundary in `gobonsai-web/src/engine/growth/detachPipelineSub40EEE0.ts`. Higher-level domain services—`gobonsai-web/src/engine/GrowthService.ts`, `gobonsai-web/src/engine/BranchingService.ts`, and `gobonsai-web/src/engine/MetabolismService.ts`—provide named orchestration around this lower-level recovered behavior.

#### World, Geometry, and Rendering Data
World-level allocation, lookup, and spatial behavior are separated under `gobonsai-web/src/engine/world/`, notably `gobonsai-web/src/engine/world/WorldGrowthState.ts`, `gobonsai-web/src/engine/world/WorldObjectSub401830.ts`, and `gobonsai-web/src/engine/world/SectionSpatialQueriesSub40x.ts`. Geometry and transform computation are isolated in `gobonsai-web/src/engine/GeometryService.ts`, `gobonsai-web/src/engine/growth/transformChainSub450BD0.ts`, and `gobonsai-web/src/engine/math/TransformService.ts`. Render submission parity has a dedicated specification at `GUIDES/spec_render_submit_sub_44F2A0.md`.

#### Parity Evidence and Toolchain
`GUIDES/` is the operational specification layer linking recovered native functions to TypeScript implementations, including `GUIDES/decomp_master_manifest.csv`, `GUIDES/sub_to_ts_coverage_map.md`, and `GUIDES/full_technical_parity_execution_plan_v2.md`. IDA artifacts and automation support further native analysis under `installed game/` and `tools/ida/gobonsai_one_run_trace.py`. The material runtime is a Vite/TypeScript/Vue browser app (`gobonsai-web/package.json`, `gobonsai-web/vite.config.ts`); no server-side infrastructure or external service integration is evident.

Main entry points: [`gobonsai-web/src/engine/growth/GrowthFramePipeline.ts`](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/growth/GrowthFramePipeline.ts) (Growth frame pipeline), [`gobonsai-web/src/engine/TreeRoot.ts`](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/TreeRoot.ts) (Tree object graph), [`gobonsai-web/src/App.vue`](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/App.vue) (App shell), [`gobonsai-web/src/engine/BonsaiController.ts`](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/BonsaiController.ts) (Bonsai controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_evidence["Native Evidence"]
  node_native_exe["Native executables<br/>reference binary<br/>[GoBonsai.exe]"]
  node_decompilation["Decompiled native evidence<br/>C decompilation<br/>[full.c]"]
  node_parity_guides["Parity guides<br/>specification"]
  node_ida_trace["IDA trace automation<br/>analysis tool"]
end

subgraph group_web["Browser UI"]
  node_web_entry["Browser entry<br/>TypeScript entry<br/>[main.ts]"]
  node_app["App shell<br/>Vue root<br/>[App.vue]"]
  node_dashboard["Dashboard controls<br/>Vue component<br/>[Dashboard.vue]"]
  node_viewer["Bonsai viewer<br/>Vue component<br/>[BonsaiViewer.vue]"]
end

subgraph group_engine["Simulation Engine"]
  node_bonsai_controller["Bonsai controller<br/>engine controller"]
  node_growth_controller["Growth controller<br/>engine controller"]
  node_tree_model["Tree object graph<br/>domain model<br/>[TreeRoot.ts]"]
  node_tree_contracts["Tree contracts and state<br/>model contracts<br/>[TreeInterfaces.ts]"]
  node_world_state["World growth state<br/>world model"]
  node_spatial_queries["Section spatial queries<br/>world geometry"]
  node_geometry["Geometry and transforms<br/>geometry service<br/>[GeometryService.ts]"]
  node_growth_services["Domain growth services<br/>service layer<br/>[GrowthService.ts]"]
end

subgraph group_pipeline["Frame Growth Pipeline"]
  node_frame_pipeline["Growth frame pipeline<br/>frame orchestrator"]
  node_strict_path["Strict EXE simulation path<br/>parity route"]
  node_growth_tick["Recovered growth tick<br/>growth stage"]
  node_metabolism_light["Light and leaf metabolism<br/>growth stages"]
  node_branching_twig["Branching and twig growth<br/>growth stages"]
  node_detach["Detach pipeline<br/>structural mutation"]
end

node_native_exe -.->|"reverse-engineered into"| node_decompilation
node_decompilation -.->|"documents recovered behavior"| node_parity_guides
node_ida_trace -.->|"supports analysis"| node_decompilation
node_parity_guides -.->|"specifies parity"| node_strict_path
node_web_entry -->|"mounts"| node_app
node_app -->|"hosts"| node_dashboard
node_app -->|"hosts"| node_viewer
node_dashboard -->|"controls"| node_bonsai_controller
node_bonsai_controller -->|"coordinates updates"| node_growth_controller
node_growth_controller -->|"runs each frame"| node_frame_pipeline
node_bonsai_controller -->|"owns lifecycle"| node_tree_model
node_tree_contracts -->|"defines state"| node_tree_model
node_viewer -->|"renders"| node_tree_model
node_frame_pipeline -->|"selects strict branch"| node_strict_path
node_frame_pipeline -->|"runs growth tick"| node_growth_tick
node_growth_tick -->|"evaluates resources"| node_metabolism_light
node_growth_tick -->|"updates growth structure"| node_branching_twig
node_branching_twig -->|"removes structures"| node_detach
node_frame_pipeline -->|"mutates"| node_tree_model
node_frame_pipeline -->|"updates world"| node_world_state
node_metabolism_light -->|"traces through"| node_spatial_queries
node_spatial_queries -->|"queries"| node_world_state
node_geometry -->|"computes transforms for"| node_tree_model
node_growth_services -->|"orchestrates named behavior"| node_frame_pipeline

click node_native_exe "https://github.com/bysggit/gobonsaisetup/blob/master/GoBonsai.exe"
click node_decompilation "https://github.com/bysggit/gobonsaisetup/blob/master/decompiled/full.c"
click node_parity_guides "https://github.com/bysggit/gobonsaisetup/blob/master/GUIDES/sub_to_ts_coverage_map.md"
click node_ida_trace "https://github.com/bysggit/gobonsaisetup/blob/master/tools/ida/gobonsai_one_run_trace.py"
click node_web_entry "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/main.ts"
click node_app "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/App.vue"
click node_dashboard "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/components/Dashboard.vue"
click node_viewer "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/components/BonsaiViewer.vue"
click node_bonsai_controller "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/BonsaiController.ts"
click node_growth_controller "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/GrowthController.ts"
click node_tree_model "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/TreeRoot.ts"
click node_tree_contracts "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/TreeInterfaces.ts"
click node_world_state "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/world/WorldGrowthState.ts"
click node_spatial_queries "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/world/SectionSpatialQueriesSub40x.ts"
click node_geometry "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/GeometryService.ts"
click node_growth_services "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/GrowthService.ts"
click node_frame_pipeline "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/growth/GrowthFramePipeline.ts"
click node_strict_path "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/growth/strictExeSimPath.ts"
click node_growth_tick "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/growth/sub40DC90GrowthTick.ts"
click node_metabolism_light "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/growth/lightTracingSub40E460.ts"
click node_branching_twig "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/growth/branchingDispatcherSub417F40.ts"
click node_detach "https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/growth/detachPipelineSub40EEE0.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_native_exe,node_decompilation,node_parity_guides,node_ida_trace toneBlue
class node_web_entry,node_app,node_dashboard,node_viewer toneAmber
class node_bonsai_controller,node_growth_controller,node_tree_model,node_tree_contracts,node_world_state,node_spatial_queries,node_geometry,node_growth_services toneMint
class node_frame_pipeline,node_strict_path,node_growth_tick,node_metabolism_light,node_branching_twig,node_detach toneRose
```

## Components

### Native Evidence

Retained executable, decompilation, and parity specifications.

- [Native executables](https://github.com/bysggit/gobonsaisetup/blob/master/GoBonsai.exe): reference binary · `GoBonsai.exe`
- [Decompiled native evidence](https://github.com/bysggit/gobonsaisetup/blob/master/decompiled/full.c): C decompilation · `decompiled/full.c`
- [Parity guides](https://github.com/bysggit/gobonsaisetup/blob/master/GUIDES/sub_to_ts_coverage_map.md): specification · Maps recovered native functions to TypeScript behavior. · `GUIDES/sub_to_ts_coverage_map.md`
- [IDA trace automation](https://github.com/bysggit/gobonsaisetup/blob/master/tools/ida/gobonsai_one_run_trace.py): analysis tool · `tools/ida/gobonsai_one_run_trace.py`

### Browser UI

Vite/Vue application entry and presentation layer.

- [Browser entry](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/main.ts): TypeScript entry · `gobonsai-web/src/main.ts`
- [App shell](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/App.vue): Vue root · `gobonsai-web/src/App.vue`
- [Dashboard controls](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/components/Dashboard.vue): Vue component · Exposes simulation controls and state. · `gobonsai-web/src/components/Dashboard.vue`
- [Bonsai viewer](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/components/BonsaiViewer.vue): Vue component · Presents the simulated tree. · `gobonsai-web/src/components/BonsaiViewer.vue`

### Simulation Engine

Controller, model, world, and recovered growth behavior.

- [Bonsai controller](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/BonsaiController.ts): engine controller · Coordinates tree lifecycle and interaction. · `gobonsai-web/src/engine/BonsaiController.ts`
- [Growth controller](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/GrowthController.ts): engine controller · Drives frame growth updates. · `gobonsai-web/src/engine/GrowthController.ts`
- [Tree object graph](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/TreeRoot.ts): domain model · Root, sections, and leaves form canonical tree state. · `gobonsai-web/src/engine/TreeRoot.ts`
- [Tree contracts and state](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/TreeInterfaces.ts): model contracts · Shared state, shapes, and runtime section dispatch. · `gobonsai-web/src/engine/TreeInterfaces.ts`
- [World growth state](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/world/WorldGrowthState.ts): world model · Holds world-level growth allocation and state. · `gobonsai-web/src/engine/world/WorldGrowthState.ts`
- [Section spatial queries](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/world/SectionSpatialQueriesSub40x.ts): world geometry · `gobonsai-web/src/engine/world/SectionSpatialQueriesSub40x.ts`
- [Geometry and transforms](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/GeometryService.ts): geometry service · Computes geometry and transform chains. · `gobonsai-web/src/engine/GeometryService.ts`
- [Domain growth services](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/GrowthService.ts): service layer · Named growth, branching, and metabolism orchestration. · `gobonsai-web/src/engine/GrowthService.ts`

### Frame Growth Pipeline

Native-aligned per-frame simulation stages.

- [Growth frame pipeline](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/growth/GrowthFramePipeline.ts): frame orchestrator · Selects parity path and applies frame mutations. · `gobonsai-web/src/engine/growth/GrowthFramePipeline.ts`
- [Strict EXE simulation path](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/growth/strictExeSimPath.ts): parity route · Native-aligned growth execution route. · `gobonsai-web/src/engine/growth/strictExeSimPath.ts`
- [Recovered growth tick](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/growth/sub40DC90GrowthTick.ts): growth stage · `gobonsai-web/src/engine/growth/sub40DC90GrowthTick.ts`
- [Light and leaf metabolism](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/growth/lightTracingSub40E460.ts): growth stages · Light tracing feeds leaf metabolism. · `gobonsai-web/src/engine/growth/lightTracingSub40E460.ts`
- [Branching and twig growth](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/growth/branchingDispatcherSub417F40.ts): growth stages · Dispatches branching and elongates twigs. · `gobonsai-web/src/engine/growth/branchingDispatcherSub417F40.ts`
- [Detach pipeline](https://github.com/bysggit/gobonsaisetup/blob/master/gobonsai-web/src/engine/growth/detachPipelineSub40EEE0.ts): structural mutation · Removes or detaches tree structures. · `gobonsai-web/src/engine/growth/detachPipelineSub40EEE0.ts`

## Connections

- Native executables → Decompiled native evidence: reverse-engineered into
- Decompiled native evidence → Parity guides: documents recovered behavior
- IDA trace automation → Decompiled native evidence: supports analysis
- Parity guides → Strict EXE simulation path: specifies parity
- Browser entry → App shell: mounts
- App shell → Dashboard controls: hosts
- App shell → Bonsai viewer: hosts
- Dashboard controls → Bonsai controller: controls
- Bonsai controller → Growth controller: coordinates updates
- Growth controller → Growth frame pipeline: runs each frame
- Bonsai controller → Tree object graph: owns lifecycle
- Tree contracts and state → Tree object graph: defines state
- Bonsai viewer → Tree object graph: renders
- Growth frame pipeline → Strict EXE simulation path: selects strict branch
- Growth frame pipeline → Recovered growth tick: runs growth tick
- Recovered growth tick → Light and leaf metabolism: evaluates resources
- Recovered growth tick → Branching and twig growth: updates growth structure
- Branching and twig growth → Detach pipeline: removes structures
- Growth frame pipeline → Tree object graph: mutates
- Growth frame pipeline → World growth state: updates world
- Light and leaf metabolism → Section spatial queries: traces through
- Section spatial queries → World growth state: queries
- Geometry and transforms → Tree object graph: computes transforms for
- Domain growth services → Growth frame pipeline: orchestrates named behavior