# klydddd/mlbb-stream-overlays architecture

> Architecture diagram of the GitHub repository klydddd/mlbb-stream-overlays, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/klydddd/mlbb-stream-overlays
- Repository: https://github.com/klydddd/mlbb-stream-overlays

## Overview

MLBB Stream Overlay is a tournament broadcast controller: operators edit draft and match data, synchronized state updates browser overlays in real time, and OBS presents those overlays. A separate calibrated vision bot recognizes draft heroes and sends predictions to the display; an in-game stats bot supplies match events. Other capabilities include player-photo processing, tournament hero statistics, waiting-room scheduling, sponsors, and series scoring. The graph combines README-described workflows with the shown synchronization and controller calls; unsampled modules are represented only where documented, so some subsystem links remain unverified.

Main entry points: [`frontend/js/websocketClient.js`](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/websocketClient.js) (Room WebSocket Client), [`frontend/js/control.js`](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/control.js) (Overlay Controller), [`backend/server/server.py`](https://github.com/klydddd/mlbb-stream-overlays/blob/main/backend/server/server.py) (WebSocket Server), [`frontend/js/display.js`](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/display.js) (Team Overlay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control and Sync"]
  node_controller["Overlay Controller<br/>[control.js]"]
  node_sync["Room WebSocket Client<br/>[websocketClient.js]"]
  node_server["WebSocket Server<br/>[server.py]"]
  node_browserstate[("Browser Shared State")]
end

subgraph group_draft["Draft Recognition"]
  node_draftguard["Draft Rules Guard<br/>[draftGuard.js]"]
  node_draftdisplay["Draft Display<br/>[display.js]"]
  node_heroes["Hero Catalog and Rendering<br/>[hero.js]"]
  node_calibration["Multi-slot Calibration"]
  node_aibot["Draft Recognition Bot"]
end

subgraph group_overlays["Broadcast Overlays"]
  node_display["Team Overlay<br/>[display.js]"]
  node_gameoverlay["In-game Overlay<br/>[gameDisplay.js]"]
  node_animation["Overlay Animations<br/>[gameDisplayAnim.js]"]
  node_photos["Player Photo Controls<br/>[playerPhotos.js]"]
  node_bgremove["Photo Background Removal<br/>[bgRemoval.js]"]
  node_sponsors["Sponsor Display<br/>[sponsorStrip.js]"]
end

subgraph group_match["Match Operations"]
  node_waiting["Waiting Room Display<br/>[waiting.js]"]
  node_waitingctl["Waiting Room Controls"]
  node_ingamectl["In-game Controls<br/>[ingame.js]"]
  node_ingamestats["In-game Stats Bot"]
  node_series["Series Race Scoring<br/>[seriesRace.js]"]
  node_seriesctl["Series Race Controls"]
end

subgraph group_stats["Tournament Statistics"]
  node_statsctl["Tournament Stats Controls"]
  node_statscore["Game Record Rules<br/>[heroStatsCore.js]"]
  node_statsapi["Tournament Stats API<br/>[heroStatsApi.js]"]
  node_statsdisplay["Hero Stats Display"]
end

node_operator(("Tournament Operator"))
node_obs(("OBS Browser Source"))

node_operator -->|"edits overlay"| node_controller
node_controller -->|"checks picks"| node_draftguard
node_controller -->|"persists settings"| node_browserstate
node_controller -->|"sends updates"| node_sync
node_sync -->|"opens room socket"| node_server
node_server -->|"relays messages"| node_sync
node_calibration -.->|"configures scan slots"| node_aibot
node_aibot -->|"sends predictions"| node_server
node_sync -->|"delivers updates"| node_display
node_display -->|"renders hero picks"| node_heroes
node_sync -->|"delivers updates"| node_gameoverlay
node_gameoverlay -->|"plays transitions"| node_animation
node_photos -->|"removes backgrounds"| node_bgremove
node_sync -->|"delivers room data"| node_waiting
node_waitingctl -->|"sends room updates"| node_sync
node_ingamectl -.->|"sends match updates"| node_sync
node_ingamestats -->|"sends match stats"| node_server
node_seriesctl -->|"sets race length"| node_series
node_statsctl -->|"builds game records"| node_statscore
node_statsctl -->|"logs and fetches games"| node_statsapi
node_statsdisplay -->|"fetches tournament data"| node_statsapi
node_sponsors -->|"mounts sponsor strip"| node_gameoverlay
node_sponsors -->|"mounts sponsor strip"| node_display
node_obs -->|"shows browser overlay"| node_display
node_obs -->|"shows browser overlay"| node_gameoverlay

click node_controller "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/control.js"
click node_sync "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/websocketClient.js"
click node_server "https://github.com/klydddd/mlbb-stream-overlays/blob/main/backend/server/server.py"
click node_draftguard "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/draftGuard.js"
click node_draftdisplay "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/display.js"
click node_heroes "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/hero.js"
click node_calibration "https://github.com/klydddd/mlbb-stream-overlays/blob/main/backend/calibration_multi.py"
click node_aibot "https://github.com/klydddd/mlbb-stream-overlays/blob/main/backend/ai_bot_multi_auto.py"
click node_display "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/display.js"
click node_gameoverlay "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/gameDisplay.js"
click node_animation "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/gameDisplayAnim.js"
click node_photos "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/playerPhotos.js"
click node_bgremove "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/bgRemoval.js"
click node_sponsors "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/sponsorStrip.js"
click node_waiting "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/waiting.js"
click node_waitingctl "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/waitingController.js"
click node_ingamectl "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/ingame.js"
click node_ingamestats "https://github.com/klydddd/mlbb-stream-overlays/blob/main/backend/ingame_stats_bot.py"
click node_series "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/seriesRace.js"
click node_seriesctl "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/seriesRaceController.js"
click node_statsctl "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/heroStatsController.js"
click node_statscore "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/heroStatsCore.js"
click node_statsapi "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/heroStatsApi.js"
click node_statsdisplay "https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/heroStatsDisplay.js"

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_controller,node_sync,node_server,node_browserstate,node_obs toneBlue
class node_draftguard,node_draftdisplay,node_heroes,node_calibration,node_aibot toneAmber
class node_display,node_gameoverlay,node_animation,node_photos,node_bgremove,node_sponsors toneMint
class node_waiting,node_waitingctl,node_ingamectl,node_ingamestats,node_series,node_seriesctl toneRose
class node_statsctl,node_statscore,node_statsapi,node_statsdisplay,node_operator toneIndigo
```

## Components

### Control and Sync

- [Overlay Controller](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/control.js): `frontend/js/control.js`
- [Room WebSocket Client](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/websocketClient.js): `frontend/js/websocketClient.js`
- [WebSocket Server](https://github.com/klydddd/mlbb-stream-overlays/blob/main/backend/server/server.py): `backend/server/server.py`
- **Browser Shared State**

### Draft Recognition

- [Draft Rules Guard](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/draftGuard.js): `frontend/js/draftGuard.js`
- [Draft Display](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/display.js): `frontend/js/display.js`
- [Hero Catalog and Rendering](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/hero.js): `frontend/js/hero.js`
- [Multi-slot Calibration](https://github.com/klydddd/mlbb-stream-overlays/blob/main/backend/calibration_multi.py): `backend/calibration_multi.py`
- [Draft Recognition Bot](https://github.com/klydddd/mlbb-stream-overlays/blob/main/backend/ai_bot_multi_auto.py): `backend/ai_bot_multi_auto.py`

### Broadcast Overlays

- [Team Overlay](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/display.js): `frontend/js/display.js`
- [In-game Overlay](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/gameDisplay.js): `frontend/js/gameDisplay.js`
- [Overlay Animations](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/gameDisplayAnim.js): `frontend/js/gameDisplayAnim.js`
- [Player Photo Controls](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/playerPhotos.js): `frontend/js/playerPhotos.js`
- [Photo Background Removal](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/bgRemoval.js): `frontend/js/bgRemoval.js`
- [Sponsor Display](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/sponsorStrip.js): `frontend/js/sponsorStrip.js`

### Match Operations

- [Waiting Room Display](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/waiting.js): `frontend/js/waiting.js`
- [Waiting Room Controls](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/waitingController.js): `frontend/js/waitingController.js`
- [In-game Controls](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/ingame.js): `frontend/js/ingame.js`
- [In-game Stats Bot](https://github.com/klydddd/mlbb-stream-overlays/blob/main/backend/ingame_stats_bot.py): `backend/ingame_stats_bot.py`
- [Series Race Scoring](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/seriesRace.js): `frontend/js/seriesRace.js`
- [Series Race Controls](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/seriesRaceController.js): `frontend/js/seriesRaceController.js`

### Tournament Statistics

- [Tournament Stats Controls](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/heroStatsController.js): `frontend/js/heroStatsController.js`
- [Game Record Rules](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/heroStatsCore.js): `frontend/js/heroStatsCore.js`
- [Tournament Stats API](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/heroStatsApi.js): `frontend/js/heroStatsApi.js`
- [Hero Stats Display](https://github.com/klydddd/mlbb-stream-overlays/blob/main/frontend/js/heroStatsDisplay.js): `frontend/js/heroStatsDisplay.js`

### Other components

- **Tournament Operator**
- **OBS Browser Source**

## Connections

- Tournament Operator → Overlay Controller: edits overlay (evidence: `README.md`)
- Overlay Controller → Draft Rules Guard: checks picks (evidence: `frontend/js/control.js`)
- Overlay Controller → Browser Shared State: persists settings (evidence: `frontend/js/control.js`)
- Overlay Controller → Room WebSocket Client: sends updates (evidence: `frontend/js/control.js`)
- Room WebSocket Client → WebSocket Server: opens room socket (evidence: `frontend/js/websocketClient.js`)
- WebSocket Server → Room WebSocket Client: relays messages (evidence: `README.md`)
- Multi-slot Calibration → Draft Recognition Bot: configures scan slots
- Draft Recognition Bot → WebSocket Server: sends predictions (evidence: `README.md`)
- Room WebSocket Client → Team Overlay: delivers updates (evidence: `frontend/js/display.js`)
- Team Overlay → Hero Catalog and Rendering: renders hero picks (evidence: `frontend/js/display.js`)
- Room WebSocket Client → In-game Overlay: delivers updates (evidence: `frontend/js/gameDisplay.js`)
- In-game Overlay → Overlay Animations: plays transitions (evidence: `frontend/js/gameDisplay.js`)
- Player Photo Controls → Photo Background Removal: removes backgrounds (evidence: `frontend/js/playerPhotos.js`)
- Room WebSocket Client → Waiting Room Display: delivers room data (evidence: `frontend/js/waiting.js`)
- Waiting Room Controls → Room WebSocket Client: sends room updates (evidence: `frontend/js/waitingController.js`)
- In-game Controls → Room WebSocket Client: sends match updates (evidence: `frontend/js/ingame.js`)
- In-game Stats Bot → WebSocket Server: sends match stats
- Series Race Controls → Series Race Scoring: sets race length (evidence: `frontend/js/seriesRaceController.js`)
- Tournament Stats Controls → Game Record Rules: builds game records (evidence: `frontend/js/heroStatsController.js`)
- Tournament Stats Controls → Tournament Stats API: logs and fetches games (evidence: `frontend/js/heroStatsController.js`)
- Hero Stats Display → Tournament Stats API: fetches tournament data (evidence: `frontend/js/heroStatsDisplay.js`)
- Sponsor Display → In-game Overlay: mounts sponsor strip (evidence: `frontend/js/gameDisplay.js`)
- Sponsor Display → Team Overlay: mounts sponsor strip
- OBS Browser Source → Team Overlay: shows browser overlay (evidence: `README.md`)
- OBS Browser Source → In-game Overlay: shows browser overlay (evidence: `README.md`)