# cherry9001/tiktok-live-bar architecture

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

- Interactive diagram: https://gitdiagram.com/cherry9001/tiktok-live-bar
- Repository: https://github.com/cherry9001/tiktok-live-bar

## Overview

ÔNG CHÚ MMO turns TikTok LIVE activity into an interactive Unity dance floor. An operator connects a live username in the browser panel; the Node bridge receives TikFinity events, normalizes and applies game/master rules, tracks session activity, and broadcasts events to the Unity client, which renders participants and effects. The panel also configures rules and provides demo controls. README capabilities include DJ media, rankings, and chroma key. Bridge internals are evidenced by sampled source; Unity behavior and some branches are based on README and the file tree.

Main entry points: [`TikTokBridge/server.js`](https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/server.js) (Bridge server), [`UnityProject/Assets/Scripts/TikTokGameController.cs`](https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/TikTokGameController.cs) (Game event controller), [`TikTokBridge/public/control.js`](https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/public/control.js) (Control panel), [`UnityProject/Assets/Scripts/PlayerManager.cs`](https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/PlayerManager.cs) (Player management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operation["Live operation"]
  node_control["Control panel<br/>[control.js]"]
  node_control_ui["Panel interface<br/>[control.html]"]
end

subgraph group_bridge["Event bridge"]
  node_bridge_server["Bridge server<br/>[server.js]"]
  node_tikfinity_normalizer["TikFinity normalizer"]
  node_event_normalizer["Event normalizer<br/>[normalize-event.js]"]
  node_security["Event security<br/>[security.js]"]
  node_master_rules["Master rules<br/>[rules.js]"]
  node_game_config["Game configuration<br/>[game.json]"]
  node_gift_config["Gift configuration<br/>[gifts.json]"]
  node_master_config["Master configuration<br/>[master.json]"]
  node_demo["Test Lab demo<br/>[server.js]"]
end

subgraph group_game["Unity game"]
  node_unity_socket["Game WebSocket client"]
  node_game_controller["Game event controller"]
  node_player_manager["Player management<br/>[PlayerManager.cs]"]
  node_player_actor["Dance floor actors<br/>[PlayerActor.cs]"]
  node_avatar_service["Viewer avatars<br/>[AvatarService.cs]"]
  node_gift_effects["Gift effects"]
  node_leaderboard["Top gifter podium<br/>[PlayerManager.cs]"]
  node_stage_lighting["Stage lighting"]
  node_chromakey["Chroma key"]
end

subgraph group_media["Stage media"]
  node_dj_music["DJ music player"]
  node_dj_video["DJ video screen<br/>[DjVideoScreen.cs]"]
end

node_operator(("Live operator"))
node_viewers(("TikTok viewers"))
node_tikfinity["TikFinity Desktop"]

node_operator -->|"operates"| node_control_ui
node_control_ui -->|"drives"| node_control
node_control -->|"sends commands"| node_bridge_server
node_bridge_server -->|"connects to"| node_tikfinity
node_tikfinity -->|"streams events"| node_bridge_server
node_bridge_server -->|"normalizes messages"| node_tikfinity_normalizer
node_bridge_server -->|"normalizes events"| node_event_normalizer
node_bridge_server -->|"sanitizes and guards"| node_security
node_bridge_server -->|"applies rules"| node_master_rules
node_bridge_server -->|"reads"| node_game_config
node_bridge_server -->|"reads"| node_gift_config
node_bridge_server -->|"reads and writes"| node_master_config
node_control -->|"saves rules"| node_bridge_server
node_viewers -->|"send activity"| node_tikfinity
node_bridge_server -->|"broadcasts events"| node_unity_socket
node_unity_socket -->|"delivers events"| node_game_controller
node_game_controller -->|"updates players"| node_player_manager
node_player_manager -->|"manages actors"| node_player_actor
node_player_manager -->|"loads avatars"| node_avatar_service
node_game_controller -->|"triggers gift effects"| node_gift_effects
node_game_controller -->|"updates scores"| node_leaderboard
node_game_controller -->|"drives stage"| node_stage_lighting
node_operator -->|"starts demo"| node_demo
node_demo -->|"emits test events"| node_bridge_server
node_dj_music -.->|"plays on stage"| node_viewers
node_dj_video -.->|"displays on stage"| node_viewers
node_chromakey -.->|"outputs keyed scene"| node_viewers

click node_control "https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/public/control.js"
click node_control_ui "https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/public/control.html"
click node_bridge_server "https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/server.js"
click node_tikfinity_normalizer "https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/src/tiktok/normalize-tikfinity-event.js"
click node_event_normalizer "https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/src/tiktok/normalize-event.js"
click node_security "https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/src/security.js"
click node_master_rules "https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/src/master/rules.js"
click node_game_config "https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/config/game.json"
click node_gift_config "https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/config/gifts.json"
click node_master_config "https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/config/master.json"
click node_unity_socket "https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/TikTokWebSocketClient.cs"
click node_game_controller "https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/TikTokGameController.cs"
click node_player_manager "https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/PlayerManager.cs"
click node_player_actor "https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/PlayerActor.cs"
click node_avatar_service "https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/AvatarService.cs"
click node_gift_effects "https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/GiftEffectManager.cs"
click node_leaderboard "https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/PlayerManager.cs"
click node_stage_lighting "https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/ClubPulseController.cs"
click node_chromakey "https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/RuntimeBootstrap.cs"
click node_dj_music "https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/MusicPlaylistPlayer.cs"
click node_dj_video "https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/DjVideoScreen.cs"
click node_demo "https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/server.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_control,node_control_ui,node_viewers toneBlue
class node_bridge_server,node_tikfinity_normalizer,node_event_normalizer,node_security,node_master_rules,node_game_config,node_gift_config,node_master_config,node_demo toneAmber
class node_unity_socket,node_game_controller,node_player_manager,node_player_actor,node_avatar_service,node_gift_effects,node_leaderboard,node_stage_lighting,node_chromakey toneMint
class node_dj_music,node_dj_video toneRose
class node_operator,node_tikfinity toneIndigo
```

## Components

### Live operation

- [Control panel](https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/public/control.js): `TikTokBridge/public/control.js`
- [Panel interface](https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/public/control.html): `TikTokBridge/public/control.html`

### Event bridge

- [Bridge server](https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/server.js): `TikTokBridge/server.js`
- [TikFinity normalizer](https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/src/tiktok/normalize-tikfinity-event.js): `TikTokBridge/src/tiktok/normalize-tikfinity-event.js`
- [Event normalizer](https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/src/tiktok/normalize-event.js): `TikTokBridge/src/tiktok/normalize-event.js`
- [Event security](https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/src/security.js): `TikTokBridge/src/security.js`
- [Master rules](https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/src/master/rules.js): `TikTokBridge/src/master/rules.js`
- [Game configuration](https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/config/game.json): `TikTokBridge/config/game.json`
- [Gift configuration](https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/config/gifts.json): `TikTokBridge/config/gifts.json`
- [Master configuration](https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/config/master.json): `TikTokBridge/config/master.json`
- [Test Lab demo](https://github.com/cherry9001/tiktok-live-bar/blob/main/TikTokBridge/server.js): `TikTokBridge/server.js`

### Unity game

- [Game WebSocket client](https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/TikTokWebSocketClient.cs): `UnityProject/Assets/Scripts/TikTokWebSocketClient.cs`
- [Game event controller](https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/TikTokGameController.cs): `UnityProject/Assets/Scripts/TikTokGameController.cs`
- [Player management](https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/PlayerManager.cs): `UnityProject/Assets/Scripts/PlayerManager.cs`
- [Dance floor actors](https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/PlayerActor.cs): `UnityProject/Assets/Scripts/PlayerActor.cs`
- [Viewer avatars](https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/AvatarService.cs): `UnityProject/Assets/Scripts/AvatarService.cs`
- [Gift effects](https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/GiftEffectManager.cs): `UnityProject/Assets/Scripts/GiftEffectManager.cs`
- [Top gifter podium](https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/PlayerManager.cs): `UnityProject/Assets/Scripts/PlayerManager.cs`
- [Stage lighting](https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/ClubPulseController.cs): `UnityProject/Assets/Scripts/ClubPulseController.cs`
- [Chroma key](https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/RuntimeBootstrap.cs): `UnityProject/Assets/Scripts/RuntimeBootstrap.cs`

### Stage media

- [DJ music player](https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/MusicPlaylistPlayer.cs): `UnityProject/Assets/Scripts/MusicPlaylistPlayer.cs`
- [DJ video screen](https://github.com/cherry9001/tiktok-live-bar/blob/main/UnityProject/Assets/Scripts/DjVideoScreen.cs): `UnityProject/Assets/Scripts/DjVideoScreen.cs`

### Other components

- **Live operator**
- **TikTok viewers**
- **TikFinity Desktop**

## Connections

- Live operator → Panel interface: operates
- Panel interface → Control panel: drives
- Control panel → Bridge server: sends commands
- Bridge server → TikFinity Desktop: connects to
- TikFinity Desktop → Bridge server: streams events
- Bridge server → TikFinity normalizer: normalizes messages
- Bridge server → Event normalizer: normalizes events
- Bridge server → Event security: sanitizes and guards
- Bridge server → Master rules: applies rules
- Bridge server → Game configuration: reads
- Bridge server → Gift configuration: reads
- Bridge server → Master configuration: reads and writes
- Control panel → Bridge server: saves rules
- TikTok viewers → TikFinity Desktop: send activity
- Bridge server → Game WebSocket client: broadcasts events
- Game WebSocket client → Game event controller: delivers events
- Game event controller → Player management: updates players
- Player management → Dance floor actors: manages actors
- Player management → Viewer avatars: loads avatars
- Game event controller → Gift effects: triggers gift effects
- Game event controller → Top gifter podium: updates scores
- Game event controller → Stage lighting: drives stage
- Live operator → Test Lab demo: starts demo
- Test Lab demo → Bridge server: emits test events
- DJ music player → TikTok viewers: plays on stage
- DJ video screen → TikTok viewers: displays on stage
- Chroma key → TikTok viewers: outputs keyed scene