# yolkorg/yolkbot architecture

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

- Interactive diagram: https://gitdiagram.com/yolkorg/yolkbot
- Repository: https://github.com/yolkorg/yolkbot

## Overview

##### Project Type and Purpose
- Yolkbot is an open-source library and CLI/browser toolset for building Shell Shockers bots in minimal code.
- It provides:
- A core JavaScript/TypeScript library (under `/src`) that handles networking, game‐state decoding, dispatching actions, pathfinding, and WASM integration.
- A CLI tool (`/cli`) for scraping game data, building releases, and publishing to npm.
- A browser build target (`/browser`) that packages the core library for front-end use.
- The README emphasizes ease of bot creation, automated data scraping, and multi-target packaging.

##### File Structure
- Top-level:
- `/src` – Core library modules.
- `/cli` – Scripts for scraping, building, and publishing.
- `/browser` – Build and entry points for a browser-compatible bundle.
- `/alpha` and `/prod` – Likely environment configurations or prebuilt assets.
- CI config under `.github/workflows/scrape.yml` to automate data scraping.
- Within `/src`:
- `socket.js`, `matchmaker.js`, `comm/CommIn.js` & `CommOut.js` – Network layer.
- `dispatches/` – Action handlers (Fire, Move, Chat, etc.).
- `constants/` – Game data (maps, items, sounds) populated by the scraper.
- `pathing/` – A* pathfinding utilities.
- `wasm/` – A WASM loader and helpers for performance-critical code.
- `/cli/scrape` subdivides into `fromJS`, `fromJSON`, `fromWS`—each collecting different data sources.

##### Extract Architecture Insights from README
- Emphasis on “unified way” and “archive of game data” hints at a layered architecture:
- Data ingestion and update via CLI scraper
- Core library with clear API for bot authors
- Packaging layers for different environments (Node CLI vs Browser)

##### Main Components and Their Interactions
a. Core Library (Node & Browser)
– Modules: API (`api.js`), Bot (`bot.js`), Network (socket, comm), Dispatchers, Pathing, WASM, Constants
– Exposes a simple interface: instantiate a Bot, register event handlers, connect to game.
b. CLI Tool
– Scrape submodule gathers game data (JS files, JSON endpoints, WebSocket feeds).
– Build and publish modules compile and bundle `/src` into npm packages.
– Invoked manually or via CI.
c. Browser Bundle
– Uses `browser/compile.js` to produce global and module-format JS bundles.
– Hosts the same core library in client environments.
d. Data Sources
– Shell Shockers servers and web assets (for realtime game data).
– JSON APIs and scraped JS files.
e. External Services
– GitHub Actions (automate scraping and builds).
– npm registry (publishing).
f. Consumers
– Bot developers writing custom scripts against the Yolkbot API.
– CI pipelines keeping constants up to date.

##### Architectural Patterns & Principles
- Layered Architecture:
- Data Layer (constants, scraper)
- Core Logic Layer (network, dispatch, pathfinding, WASM)
- API Layer (Bot class, user hooks)
- Presentation/Packaging Layer (CLI, Browser)
- Plugin-style dispatch handlers: each game action lives in its own module.
- CI/CD integration for automated data updates.
- Dual-target bundling (Node & browser) via separate entry points.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Ingestion Layer
    subgraph "Data Ingestion / CLI Scraper"
        style CLI_Scraper fill:#ffa500,stroke:#333,stroke-width:1px
        CLI_Scraper["CLI Scraper"] 
        subgraph Scrape Modules
            style FromJS fill:#ffe5b4,stroke:#333
            FromJS["fromJS"] 
            style FromJSON fill:#ffe5b4,stroke:#333
            FromJSON["fromJSON"]
            style FromWS fill:#ffe5b4,stroke:#333
            FromWS["fromWS"]
        end
    end

    %% Core Library Layer
    subgraph "Core Library" 
        style Core fill:#add8e6,stroke:#333,stroke-width:1px
        subgraph API_Layer
            style API fill:#cfe2f3,stroke:#333
            API["API (src/api.js)"]
            style Index fill:#cfe2f3,stroke:#333
            Index["Entry (src/index.js)"]
        end
        subgraph Bot_Layer
            style Bot fill:#cfe2f3,stroke:#333
            BotCore["Bot (src/bot.js)"]
            BotPlayer["GamePlayer (src/bot/GamePlayer.js)"]
        end
        subgraph Network_Layer
            style Net fill:#cfe2f3,stroke:#333
            Socket["socket.js"]
            Matchmaker["matchmaker.js"]
            subgraph Comm
                style Comm fill:#d9edf7,stroke:#333
                CommIn["CommIn.js"]
                CommOut["CommOut.js"]
                CommIndex["index.js"]
            end
        end
        subgraph Dispatchers
            style Disp fill:#cfe2f3,stroke:#333
            DispatchDir["dispatches/"]
            Fire["FireDispatch.js"]
            Move["MovementDispatch.js"]
            Chat["ChatDispatch.js"]
            DispIndex["index.js"]
        end
        subgraph Pathfinding
            style Path fill:#cfe2f3,stroke:#333
            Astar["astar.js"]
            Heap["binaryheap.js"]
            MapNode["mapnode.js"]
        end
        subgraph WASM
            style Wasm fill:#cfe2f3,stroke:#333
            WasmLoader["wasm_loader.wasm"]
            Wrapper["wrapper.js"]
            Bytes["bytes.js"]
            Imports["imports.js"]
            Utils["utils.js"]
        end
        subgraph Constants
            style Const fill:#d3d3d3,stroke:#333
            ConstDir["constants/"]
        end
    end

    %% Packaging Layer
    subgraph "Packaging"
        style Packaging fill:#add8e6,stroke:#333,stroke-width:1px
        NodePkg["Node CLI / Library"]
        BrowserPkg["Browser Bundle"]
    end

    %% CI/CD and External
    GitHubActions["GitHub Actions"]:::ci
    npmRegistry["npm Registry"]:::external
    GameServer["Shell Shockers Game Server"]:::external
    BotConsumer["Bot Consumer"]:::external

    %% Connections
    GameServer -->|"WebSocket messages"| Socket
    Socket -->|"decode & dispatch"| DispatchDir
    DispatchDir -->|"API events"| BotCore
    BotCore -->|"actions"| Socket
    FromJS -->|populate| DispIndex
    FromJSON -->|populate| ConstDir
    FromWS -->|populate| ConstDir

    CLI_Scraper --> FromJS
    CLI_Scraper --> FromJSON
    CLI_Scraper --> FromWS
    CLI_Scraper -->|writes| ConstDir

    ConstDir -->|"import constants"| API
    API --> BotCore
    BotConsumer -->|uses API| API

    Core --> NodePkg
    Core --> BrowserPkg
    NodePkg -->|publish| npmRegistry
    BrowserPkg -->|publish| npmRegistry

    GitHubActions -->|triggers scrape/build| CLI_Scraper
    GitHubActions -->|triggers packaging| NodePkg

    BotConsumer -->|installs from| npmRegistry

    %% Click Events
    click API "https://github.com/yolkorg/yolkbot/blob/main/src/api.js"
    click Index "https://github.com/yolkorg/yolkbot/blob/main/src/index.js"
    click BotCore "https://github.com/yolkorg/yolkbot/blob/main/src/bot.js"
    click BotPlayer "https://github.com/yolkorg/yolkbot/blob/main/src/bot/GamePlayer.js"
    click Socket "https://github.com/yolkorg/yolkbot/blob/main/src/socket.js"
    click Matchmaker "https://github.com/yolkorg/yolkbot/blob/main/src/matchmaker.js"
    click CommIn "https://github.com/yolkorg/yolkbot/blob/main/src/comm/CommIn.js"
    click CommOut "https://github.com/yolkorg/yolkbot/blob/main/src/comm/CommOut.js"
    click CommIndex "https://github.com/yolkorg/yolkbot/blob/main/src/comm/index.js"
    click DispatchDir "https://github.com/yolkorg/yolkbot/tree/main/src/dispatches/"
    click Fire "https://github.com/yolkorg/yolkbot/blob/main/src/dispatches/FireDispatch.js"
    click Move "https://github.com/yolkorg/yolkbot/blob/main/src/dispatches/MovementDispatch.js"
    click Chat "https://github.com/yolkorg/yolkbot/blob/main/src/dispatches/ChatDispatch.js"
    click DispIndex "https://github.com/yolkorg/yolkbot/blob/main/src/dispatches/index.js"
    click Astar "https://github.com/yolkorg/yolkbot/blob/main/src/pathing/astar.js"
    click Heap "https://github.com/yolkorg/yolkbot/blob/main/src/pathing/binaryheap.js"
    click MapNode "https://github.com/yolkorg/yolkbot/blob/main/src/pathing/mapnode.js"
    click WasmLoader "https://github.com/yolkorg/yolkbot/blob/main/src/wasm/wasm_loader.wasm"
    click Wrapper "https://github.com/yolkorg/yolkbot/blob/main/src/wasm/wrapper.js"
    click Bytes "https://github.com/yolkorg/yolkbot/blob/main/src/wasm/bytes.js"
    click Imports "https://github.com/yolkorg/yolkbot/blob/main/src/wasm/imports.js"
    click Utils "https://github.com/yolkorg/yolkbot/blob/main/src/wasm/utils.js"
    click ConstDir "https://github.com/yolkorg/yolkbot/blob/main/src/constants/index.js"
    click FromJS "https://github.com/yolkorg/yolkbot/tree/main/cli/scrape/fromJS/"
    click FromJSON "https://github.com/yolkorg/yolkbot/tree/main/cli/scrape/fromJSON/"
    click FromWS "https://github.com/yolkorg/yolkbot/tree/main/cli/scrape/fromWS/"
    click CLI_Scraper "https://github.com/yolkorg/yolkbot/blob/main/cli/scrape/common.js"
    click NodePkg "https://github.com/yolkorg/yolkbot/blob/main/cli/build.js"
    click NodePkg "https://github.com/yolkorg/yolkbot/blob/main/cli/publish.js"
    click BrowserPkg "https://github.com/yolkorg/yolkbot/blob/main/browser/compile.js"

    %% Styles
    classDef runtime fill:#add8e6,stroke:#333,stroke-width:1px
    classDef external fill:#90ee90,stroke:#333
    classDef ci fill:#ffa500,stroke:#333
    classDef build fill:#ffa500,stroke:#333
    classDef data fill:#d3d3d3,stroke:#333
```
