# tokachi269/wasm-boids architecture

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

- Interactive diagram: https://gitdiagram.com/tokachi269/wasm-boids
- Repository: https://github.com/tokachi269/wasm-boids

## Overview

##### Project type and purpose
- This is a single‐page web application (SPA) that integrates a high‐performance C++ Boids simulation via WebAssembly into a Vue.js/Three.js frontend.
- Purpose: run a large‐scale, hierarchical Boids (fish‐school) simulation in the browser with real‐time 3D visualization.

##### File structure
- Top‐level config/build files:
– package.json, webpack.config.js, vue.config.js, nodemon.json
- Public/static assets:
– public/index.html, assets/.gitkeep
- Frontend source (Vue + Three.js):
– src/main.js (app bootstrap)
– src/App.vue (root component)
– src/components/Settings.vue (UI for simulation parameters)
- WASM simulation engine (C++ sources):
– src/wasm/boids_tree.cpp/.h, entry.cpp/.h, main.cpp, vec3.h

##### README for additional insights
- Core algorithm: Hierarchical BoidTree structure for spatial partitioning (paper CG‐133, 2008)
- Key features: recursive Boid updates, inter‐unit influence, stress/species parameters
- Integration: C++ simulation ➔ compiled with Emscripten ➔ loaded as WebAssembly module ➔ JS/Three.js drives rendering

##### Main components and interactions (
a. Components
1) Frontend UI (Vue.js)
– Settings.vue: user‐adjustable parameters
– App.vue: orchestrates canvas + controls
2) Rendering Engine (Three.js)
– Receives boid positions each frame and draws WebGL scene
3) Simulation Engine (WASM module)
– Compiled C++ code exposing functions: initialize(), updateRecursive(), getBoidData()
4) Build Toolchain
– Emscripten: compiles C++ sources → .wasm + JS glue
– Webpack/Vue CLI: bundles JS, Vue components, and WASM assets
5) Static Host
– public/index.html serves the SPA

b. Relationships & data flow
– User interacts with Settings.vue → emits parameter change event
– Vue.js (main.js) captures event → calls JS wrapper functions around WASM API
– WASM module executes BoidTree recursive update → updates internal memory buffer
– JS glue reads back boid position buffer → passes array to Three.js
– Three.js updates mesh positions in WebGL scene → browser renders frame
– Loop: requestAnimationFrame triggers next update/render cycle

c. Architectural patterns & design principles
– Separation of concerns: UI layer, simulation engine, rendering engine
– High‐performance core in WebAssembly; lean JS for orchestration
– Spatial partitioning (KD‐tree–like) for O(n log n) neighbor queries
– Reactive UI (Vue) for parameter tuning in real time

d. Key technologies/frameworks
– Vue.js (SPA framework)
– Three.js (WebGL renderer)
– Emscripten (C++ → WebAssembly)
– Webpack (module bundler)
– C++11 (simulation code, Vec3 library)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Static Host"
        HTML["public/index.html"]:::host
    end

    subgraph "Build Toolchain"
        BoidTreeCPP_src["boids_tree.cpp"]:::sim
        BoidTreeH_src["boids_tree.h"]:::sim
        EntryCPP_src["entry.cpp"]:::sim
        EntryH_src["entry.h"]:::sim
        MainCPP_src["main.cpp"]:::sim
        Vec3_src["vec3.h"]:::sim
        Emscripten["Emscripten"]:::build
        Webpack["Webpack/Vue CLI"]:::build
        package_json["package.json"]:::build
        webpack_conf["webpack.config.js"]:::build
        vue_conf["vue.config.js"]:::build
        nodemon_conf["nodemon.json"]:::build
    end

    subgraph "WASM/C++ World"
        BoidTreeCPP["boids_tree.cpp"]:::sim
        BoidTreeH["boids_tree.h"]:::sim
        EntryCPP["entry.cpp"]:::sim
        EntryH["entry.h"]:::sim
        MainCPP["main.cpp"]:::sim
        Vec3["vec3.h"]:::sim
    end

    subgraph "Browser/JS World"
        MainJS["main.js"]:::frontend
        AppVue["App.vue"]:::frontend
        Settings["Settings.vue"]:::frontend
        ThreeJS["Three.js Renderer"]:::render
        WASMWrapper["WASM JS Glue"]:::sim
        MemBuffer[(WASM Memory Buffer)]:::sim
    end

    HTML -->|"loads SPA"| MainJS
    package_json & webpack_conf & vue_conf & nodemon_conf --> Webpack
    BoidTreeCPP_src & BoidTreeH_src & EntryCPP_src & EntryH_src & MainCPP_src & Vec3_src -->|"compile C++"| Emscripten
    Emscripten -->|".wasm + glue"| Webpack
    Webpack -->|"bundle assets"| MainJS

    Settings -->|"emit params"| MainJS
    AppVue -->|"orchestrates canvas & controls"| MainJS
    MainJS -->|"initialize() / updateRecursive() / getBoidData()"| WASMWrapper
    WASMWrapper -->|"calls WebAssembly"| MemBuffer
    MemBuffer -->|"positions array"| MainJS
    MainJS -->|"passes positions"| ThreeJS
    ThreeJS -->|"renderFrame()"| MainJS

    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef render fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef sim fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef build fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef host fill:#f0f0f0,stroke:#333,stroke-width:1px

    click MainJS "https://github.com/tokachi269/wasm-boids/blob/main/src/main.js"
    click AppVue "https://github.com/tokachi269/wasm-boids/blob/main/src/App.vue"
    click Settings "https://github.com/tokachi269/wasm-boids/blob/main/src/components/Settings.vue"
    click ThreeJS "https://github.com/tokachi269/wasm-boids/blob/main/src/main.js"
    click BoidTreeCPP "https://github.com/tokachi269/wasm-boids/blob/main/src/wasm/boids_tree.cpp"
    click BoidTreeH "https://github.com/tokachi269/wasm-boids/blob/main/src/wasm/boids_tree.h"
    click EntryCPP "https://github.com/tokachi269/wasm-boids/blob/main/src/wasm/entry.cpp"
    click EntryH "https://github.com/tokachi269/wasm-boids/blob/main/src/wasm/entry.h"
    click MainCPP "https://github.com/tokachi269/wasm-boids/blob/main/src/wasm/main.cpp"
    click Vec3 "https://github.com/tokachi269/wasm-boids/blob/main/src/wasm/vec3.h"
    click HTML "https://github.com/tokachi269/wasm-boids/blob/main/public/index.html"
    click package_json "https://github.com/tokachi269/wasm-boids/blob/main/package.json"
    click webpack_conf "https://github.com/tokachi269/wasm-boids/blob/main/webpack.config.js"
    click vue_conf "https://github.com/tokachi269/wasm-boids/blob/main/vue.config.js"
    click nodemon_conf "https://github.com/tokachi269/wasm-boids/blob/main/nodemon.json"
```
