# kvega-210/rowdyhacks-demo architecture

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

- Interactive diagram: https://gitdiagram.com/kvega-210/rowdyhacks-demo
- Repository: https://github.com/kvega-210/rowdyhacks-demo

## Overview

HEIST HAVOC is a 2–30-player party heist game: a host runs the shared game while players use phones as controllers. Players join by scanning a QR code, race through minigames to drain a shared vault, sabotage or duel rivals, and finish with standings when the vault is empty. The graph focuses on the documented current version, v3, and its authoritative Java game server, phone and host clients, and major game systems. The sampled excerpts show selected server and client responsibilities; links for other documented capabilities use the README, not inspection of their implementations.

Main entry points: [`v3/server/src/main/java/heist/game/GameEngine.java`](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/game/GameEngine.java) (Game engine), [`v3/client/phone/app.js`](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/client/phone/app.js) (Phone app), [`v3/server/src/main/java/heist/HeistServer.java`](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/HeistServer.java) (Game server), [`v3/client/host/app.js`](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/client/host/app.js) (Host screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Player Interfaces"]
  node_phone["Phone app<br/>[app.js]"]
  node_host["Host screen<br/>[app.js]"]
end

subgraph group_engine["Game Runtime"]
  node_server["Game server<br/>[HeistServer.java]"]
  node_rooms["Room management<br/>[RoomManager.java]"]
  node_game_engine["Game engine<br/>[GameEngine.java]"]
  node_protocol["WebSocket protocol<br/>[protocol.js]"]
  node_balance["Game balance<br/>[Balance.java]"]
  node_keys["Signed vault keys<br/>[KeySigner.java]"]
end

subgraph group_features["Heist Gameplay"]
  node_minigames["Minigames"]
  node_modifiers["Game modifiers"]
  node_rival_duels["Rival duels"]
  node_wagers["Wagers"]
  node_presage["Nerves feedback<br/>[nerves.js]"]
end

subgraph group_services["Persistence and Integrations"]
  node_events["Event logging<br/>[EventLog.java]"]
  node_event_store[("Event storage<br/>[EventStore.java]")]
  node_voice["Voice and AI<br/>[Tts.java]"]
end

node_players(("Players"))
node_host_operator(("Host operator"))

node_players -->|"control game"| node_phone
node_host_operator -->|"run game"| node_host
node_phone -->|"send intents"| node_server
node_host -->|"control room"| node_server
node_server -->|"send updates"| node_phone
node_server -->|"send updates"| node_host
node_server -.->|"manage rooms"| node_rooms
node_rooms -->|"create game"| node_game_engine
node_game_engine -->|"read settings"| node_balance
node_game_engine -->|"record events"| node_events
node_game_engine -->|"verify keys"| node_keys
node_events -.->|"persist events"| node_event_store
node_phone -->|"play challenges"| node_minigames
node_game_engine -.->|"assign challenges"| node_minigames
node_game_engine -.->|"apply modifiers"| node_modifiers
node_game_engine -->|"run duels"| node_rival_duels
node_game_engine -.->|"offer wagers"| node_wagers
node_phone -.->|"report nerves"| node_presage
node_game_engine -.->|"request narration"| node_voice

click node_phone "https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/client/phone/app.js"
click node_host "https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/client/host/app.js"
click node_minigames "https://github.com/kvega-210/rowdyhacks-demo/tree/main/v3/client/minigames"
click node_modifiers "https://github.com/kvega-210/rowdyhacks-demo/tree/main/v3/client/modifiers"
click node_rival_duels "https://github.com/kvega-210/rowdyhacks-demo/tree/main/v3/client/rival"
click node_wagers "https://github.com/kvega-210/rowdyhacks-demo/tree/main/v3/client/wagers"
click node_presage "https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/client/presage/nerves.js"
click node_server "https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/HeistServer.java"
click node_rooms "https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/rooms/RoomManager.java"
click node_game_engine "https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/game/GameEngine.java"
click node_protocol "https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/shared/protocol.js"
click node_balance "https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/config/Balance.java"
click node_keys "https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/keys/KeySigner.java"
click node_events "https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/db/EventLog.java"
click node_event_store "https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/db/EventStore.java"
click node_voice "https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/api/Tts.java"

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_phone,node_host toneBlue
class node_server,node_rooms,node_game_engine,node_protocol,node_balance,node_keys toneAmber
class node_minigames,node_modifiers,node_rival_duels,node_wagers,node_presage toneMint
class node_events,node_event_store,node_voice toneRose
class node_players,node_host_operator toneIndigo
```

## Components

### Player Interfaces

- [Phone app](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/client/phone/app.js): `v3/client/phone/app.js`
- [Host screen](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/client/host/app.js): `v3/client/host/app.js`

### Game Runtime

- [Game server](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/HeistServer.java): `v3/server/src/main/java/heist/HeistServer.java`
- [Room management](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/rooms/RoomManager.java): `v3/server/src/main/java/heist/rooms/RoomManager.java`
- [Game engine](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/game/GameEngine.java): `v3/server/src/main/java/heist/game/GameEngine.java`
- [WebSocket protocol](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/shared/protocol.js): `v3/shared/protocol.js`
- [Game balance](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/config/Balance.java): `v3/server/src/main/java/heist/config/Balance.java`
- [Signed vault keys](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/keys/KeySigner.java): `v3/server/src/main/java/heist/keys/KeySigner.java`

### Heist Gameplay

- [Minigames](https://github.com/kvega-210/rowdyhacks-demo/tree/main/v3/client/minigames): `v3/client/minigames`
- [Game modifiers](https://github.com/kvega-210/rowdyhacks-demo/tree/main/v3/client/modifiers): `v3/client/modifiers`
- [Rival duels](https://github.com/kvega-210/rowdyhacks-demo/tree/main/v3/client/rival): `v3/client/rival`
- [Wagers](https://github.com/kvega-210/rowdyhacks-demo/tree/main/v3/client/wagers): `v3/client/wagers`
- [Nerves feedback](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/client/presage/nerves.js): `v3/client/presage/nerves.js`

### Persistence and Integrations

- [Event logging](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/db/EventLog.java): `v3/server/src/main/java/heist/db/EventLog.java`
- [Event storage](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/db/EventStore.java): `v3/server/src/main/java/heist/db/EventStore.java`
- [Voice and AI](https://github.com/kvega-210/rowdyhacks-demo/blob/main/v3/server/src/main/java/heist/api/Tts.java): `v3/server/src/main/java/heist/api/Tts.java`

### Other components

- **Players**
- **Host operator**

## Connections

- Players → Phone app: control game (evidence: `README.md`)
- Host operator → Host screen: run game (evidence: `README.md`)
- Phone app → Game server: send intents (evidence: `README.md`)
- Host screen → Game server: control room (evidence: `README.md`)
- Game server → Phone app: send updates (evidence: `README.md`)
- Game server → Host screen: send updates (evidence: `README.md`)
- Game server → Room management: manage rooms
- Room management → Game engine: create game
- Game engine → Game balance: read settings
- Game engine → Event logging: record events
- Game engine → Signed vault keys: verify keys
- Event logging → Event storage: persist events
- Phone app → Minigames: play challenges (evidence: `README.md`)
- Game engine → Minigames: assign challenges
- Game engine → Game modifiers: apply modifiers
- Game engine → Rival duels: run duels (evidence: `README.md`)
- Game engine → Wagers: offer wagers
- Phone app → Nerves feedback: report nerves
- Game engine → Voice and AI: request narration
