# firebirdrender/commodorepet_tank architecture

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

- Interactive diagram: https://gitdiagram.com/firebirdrender/commodorepet_tank
- Repository: https://github.com/firebirdrender/commodorepet_tank

## Overview

TANK! is a networked multiplayer tank battle. Players use the browser lobby to create or join a room, wait for an opponent, then enter the WASM game, which exchanges inputs and match state over WebSocket. The server manages rooms and connections, runs deterministic game simulation, and can launch bot opponents; clients render and control the game. README capabilities include lobby events, spectators, and bot modes. Wiring for some unsampled modules is based on documented responsibilities and filenames, so uncertain call links are omitted.

Main entry points: [`server/ws_handler.go`](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/ws_handler.go) (WebSocket handler), [`client/game.go`](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/client/game.go) (Game client), [`web/app.js`](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/web/app.js) (Lobby UI), [`server/room_api.go`](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/room_api.go) (Room API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lobby["Lobby and rooms"]
  node_webapp["Lobby UI<br/>[app.js]"]
  node_roomapi["Room API<br/>[room_api.go]"]
  node_hub["Room hub<br/>[hub.go]"]
  node_room["Room state<br/>[room.go]"]
  node_sse["Room events<br/>[room_api.go]"]
end

subgraph group_server["Server runtime"]
  node_servermain["HTTP entry<br/>[main.go]"]
  node_ws["WebSocket handler<br/>[ws_handler.go]"]
  node_inputguard["Input validation<br/>[input_guard.go]"]
  node_tokenstore[("Rejoin tokens<br/>[token_store.go]")]
  node_match["Match runtime<br/>[match.go]"]
  node_delta["State deltas<br/>[delta.go]"]
  node_botmanager["Bot manager<br/>[bot_manager.go]"]
end

subgraph group_simulation["Game simulation"]
  node_engine["Deterministic engine<br/>[game.go]"]
  node_board["Board and entities<br/>[board.go]"]
end

subgraph group_clients["Game clients and bots"]
  node_browser["Browser game<br/>[main.go]"]
  node_clientgame["Game client<br/>[game.go]"]
  node_clientnet["Client networking<br/>[network.go]"]
  node_render["Rendering and input<br/>[renderer.go]"]
  node_audio["Audio and effects<br/>[audio.go]"]
  node_bot["Reference bot<br/>[main.go]"]
  node_botai["Bot strategy<br/>[ai.go]"]
  node_botsdk["Bot protocol SDK<br/>[client.go]"]
end

node_player(("Player"))
node_botprocess(("Bot subprocess"))

node_player -->|"uses lobby"| node_webapp
node_webapp -->|"creates or joins"| node_roomapi
node_roomapi -->|"manages rooms"| node_hub
node_roomapi -->|"updates seats"| node_room
node_webapp -->|"subscribes events"| node_sse
node_sse -->|"notifies status"| node_webapp
node_servermain -->|"registers routes"| node_roomapi
node_servermain -->|"serves WebSocket"| node_ws
node_ws -->|"checks tokens"| node_tokenstore
node_ws -->|"looks up room"| node_hub
node_ws -->|"validates input"| node_inputguard
node_ws -->|"starts match"| node_match
node_match -->|"advances simulation"| node_engine
node_engine -->|"updates state"| node_board
node_match -->|"encodes updates"| node_delta
node_browser -->|"starts game"| node_clientgame
node_clientgame -->|"exchanges state"| node_clientnet
node_clientgame -->|"renders and reads controls"| node_render
node_clientgame -->|"plays effects"| node_audio
node_clientnet -->|"WebSocket messages"| node_ws
node_botmanager -->|"reserves bot seat"| node_room
node_botmanager -->|"spawns process"| node_botprocess
node_botprocess -->|"runs executable"| node_bot
node_bot -->|"uses protocol client"| node_botsdk
node_bot -->|"decides actions"| node_botai
node_botsdk -->|"WebSocket messages"| node_ws

click node_webapp "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/web/app.js"
click node_roomapi "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/room_api.go"
click node_hub "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/hub.go"
click node_room "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/room.go"
click node_sse "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/room_api.go"
click node_servermain "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/cmd/server/main.go"
click node_ws "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/ws_handler.go"
click node_inputguard "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/input_guard.go"
click node_tokenstore "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/token_store.go"
click node_match "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/match.go"
click node_delta "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/delta.go"
click node_engine "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/engine/game.go"
click node_board "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/engine/board.go"
click node_browser "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/cmd/client/main.go"
click node_clientgame "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/client/game.go"
click node_clientnet "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/client/network.go"
click node_render "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/client/renderer.go"
click node_audio "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/client/audio.go"
click node_botmanager "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/bot_manager.go"
click node_bot "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/cmd/bot-go/main.go"
click node_botai "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/cmd/bot-go/ai.go"
click node_botsdk "https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/bot-sdk-go/client.go"

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_webapp,node_roomapi,node_hub,node_room,node_sse toneBlue
class node_servermain,node_ws,node_inputguard,node_tokenstore,node_match,node_delta,node_botmanager toneAmber
class node_engine,node_board toneMint
class node_browser,node_clientgame,node_clientnet,node_render,node_audio,node_bot,node_botai,node_botsdk toneRose
class node_player,node_botprocess toneIndigo
```

## Components

### Lobby and rooms

- [Lobby UI](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/web/app.js): `web/app.js`
- [Room API](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/room_api.go): `server/room_api.go`
- [Room hub](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/hub.go): `server/hub.go`
- [Room state](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/room.go): `server/room.go`
- [Room events](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/room_api.go): `server/room_api.go`

### Server runtime

- [HTTP entry](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/cmd/server/main.go): `cmd/server/main.go`
- [WebSocket handler](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/ws_handler.go): `server/ws_handler.go`
- [Input validation](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/input_guard.go): `server/input_guard.go`
- [Rejoin tokens](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/token_store.go): `server/token_store.go`
- [Match runtime](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/match.go): `server/match.go`
- [State deltas](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/delta.go): `server/delta.go`
- [Bot manager](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/server/bot_manager.go): `server/bot_manager.go`

### Game simulation

- [Deterministic engine](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/engine/game.go): `engine/game.go`
- [Board and entities](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/engine/board.go): `engine/board.go`

### Game clients and bots

- [Browser game](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/cmd/client/main.go): `cmd/client/main.go`
- [Game client](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/client/game.go): `client/game.go`
- [Client networking](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/client/network.go): `client/network.go`
- [Rendering and input](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/client/renderer.go): `client/renderer.go`
- [Audio and effects](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/client/audio.go): `client/audio.go`
- [Reference bot](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/cmd/bot-go/main.go): `cmd/bot-go/main.go`
- [Bot strategy](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/cmd/bot-go/ai.go): `cmd/bot-go/ai.go`
- [Bot protocol SDK](https://github.com/firebirdrender/commodorepet_tank/blob/NetTank/bot-sdk-go/client.go): `bot-sdk-go/client.go`

### Other components

- **Player**
- **Bot subprocess**

## Connections

- Player → Lobby UI: uses lobby
- Lobby UI → Room API: creates or joins
- Room API → Room hub: manages rooms
- Room API → Room state: updates seats
- Lobby UI → Room events: subscribes events
- Room events → Lobby UI: notifies status
- HTTP entry → Room API: registers routes
- HTTP entry → WebSocket handler: serves WebSocket
- WebSocket handler → Rejoin tokens: checks tokens
- WebSocket handler → Room hub: looks up room
- WebSocket handler → Input validation: validates input
- WebSocket handler → Match runtime: starts match
- Match runtime → Deterministic engine: advances simulation
- Deterministic engine → Board and entities: updates state
- Match runtime → State deltas: encodes updates
- Browser game → Game client: starts game
- Game client → Client networking: exchanges state
- Game client → Rendering and input: renders and reads controls
- Game client → Audio and effects: plays effects
- Client networking → WebSocket handler: WebSocket messages
- Bot manager → Room state: reserves bot seat
- Bot manager → Bot subprocess: spawns process
- Bot subprocess → Reference bot: runs executable
- Reference bot → Bot protocol SDK: uses protocol client
- Reference bot → Bot strategy: decides actions
- Bot protocol SDK → WebSocket handler: WebSocket messages