# wowsims/wotlk architecture

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

- Interactive diagram: https://gitdiagram.com/wowsims/wotlk
- Repository: https://github.com/wowsims/wotlk

## Overview

##### Project type and purpose
- This is a full-stack simulation framework for World of Warcraft WotLK Classic.
- Backend: Go-based simulation engine (CLI, WASM, & server binary).
- Frontend: TypeScript/React UI with templated pages for each class/spec.
- Data exchange: Google Protocol Buffers define the API between sim and UI.

##### File structure
- Top level:
- cmd/… → standalone CLI (`wowsimcli`).
- sim/… → simulation code in Go, with `sim/wasm` entrypoint for WebAssembly, `sim/core` for engine logic, `sim/register_all.go` to register specs.
- ui/… → UI code: `ui/core` is shared React/TS templates and proto utils; `ui/<spec>` folders contain spec-specific pages and JSON presets; `ui/worker` houses web workers for off-thread sim.
- proto/… → .proto definitions for messages & enums.
- assets/… → static DB files loaded by the sim.
- Dockerfile, makefile, GitHub workflows for CI/CD.

##### README for additional insights
- Architecture is based on a single sim engine shared by all specs.
- UI is generated from templates; sim code compiles to WASM for in-browser runs or is invoked by Go HTTP server.
- Build & deployment use Makefile and Docker; GitHub Actions auto-deploy master to GitHub Pages.

a. Main components:
- Browser UI: React/TS app + Web Workers.
- WASM Sim Engine: Go code compiled to WebAssembly, loaded in `sim_worker.js`.
- Go Server Binary (`wowsimwotlk`): hosts static assets and can run simulations server-side.
- CLI (`wowsimcli`): for batch simulations & decoding links.
- Proto Definitions: single source of truth for messages (in `proto/`).
- Assets & Database: static JSON/BIN in `assets/database`.
- External scrapers/tools: Python/Go scripts in `tools/` to generate DB inputs.
b. Relationships & flows:
1. Developer runs `make host` → UI build (via Vite or embedded in Go) → served at `/wotlk/<spec>`.
2. Browser(UI) → sends simulation request (via Proto-serialized message) to sim worker.
3. sim_worker loads WASM sim engine → invokes `Simulation.RunOnce`, reads assets (in-memory DB) → returns results.
4. net_worker can proxy requests to Go server in dev mode (for server-side sim).
5. CLI uses the same proto & sim core to run headless sims or decode links.
c. Architectural patterns & design principles:
- Single codebase for engine logic, reused in CLI, WASM, and server.
- Template-driven UI generation: common `ui/core` + spec-specific JSON.
- Web Workers to offload CPU-heavy sim from main thread.
- Proto-driven API to enforce type safety across Go and TS.
- Makefile and Docker for reproducible builds & CI.
d. Key technologies & libraries:
- Go >=1.21, google.golang.org/protobuf, Wasm.
- TypeScript, React, Vite (via `vite.config.js`), Web Workers.
- Docker, Make, GitHub Actions (deploy & tests).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        Browser_UI["Browser UI (React/TS)"]:::frontend
        subgraph "Web Workers"
            SIM_Worker["sim_worker.js"]:::frontend
            NET_Worker["net_worker.js"]:::frontend
        end
    end

    %% Engine & Data Layer
    subgraph "Engine & Data Layer"
        WASM_Sim["WASM Sim Engine"]:::engine
        Engine_Core["Engine Core (sim/core)"]:::engine
        Proto["Proto Definitions"]:::engine
        Assets_DB[(Assets DB)]:::engine
    end

    %% Backend Layer
    subgraph "Backend Layer"
        Go_Server["Go Server Binary"]:::backend
        CLI["CLI (wowsimcli)"]:::backend
    end

    %% Tools
    subgraph "Tools"
        Tools["External Scrapers/Tools"]:::tools
    end

    %% Build & CI
    subgraph "Build & CI"
        Makefile["Makefile & Docker"]:::build
    end

    %% Connections
    Browser_UI -->|"requests"| SIM_Worker
    SIM_Worker --> WASM_Sim
    WASM_Sim --> Engine_Core
    Engine_Core --> Assets_DB

    Browser_UI --> NET_Worker
    NET_Worker -->|"HTTP Proto"| Go_Server

    CLI --> Engine_Core

    Proto --> WASM_Sim
    Proto --> Go_Server
    Proto --> CLI

    Makefile --> Browser_UI
    Makefile --> Go_Server
    Makefile --> CLI

    Tools --> Assets_DB

    %% Click Events
    click Browser_UI "https://github.com/wowsims/wotlk/tree/master/ui/"
    click SIM_Worker "https://github.com/wowsims/wotlk/tree/master/ui/worker"
    click WASM_Sim "https://github.com/wowsims/wotlk/blob/master/sim/wasm/main.go"
    click Go_Server "https://github.com/wowsims/wotlk/blob/master/sim/web/main.go"
    click CLI "https://github.com/wowsims/wotlk/blob/master/cmd/wowsimcli/cli_main.go"
    click Proto "https://github.com/wowsims/wotlk/blob/master/proto/api.proto"
    click Assets_DB "https://github.com/wowsims/wotlk/tree/master/assets/database/"
    click Tools "https://github.com/wowsims/wotlk/tree/master/tools/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef engine fill:#90EE90,stroke:#000,stroke-width:1px
    classDef backend fill:#FFA500,stroke:#000,stroke-width:1px
    classDef tools fill:#FFFACD,stroke:#000,stroke-width:1px
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:1px
```
