# atr0jan/bsidessd-hacker-jeopardy architecture

> Architecture diagram of the GitHub repository atr0jan/bsidessd-hacker-jeopardy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/atr0jan/bsidessd-hacker-jeopardy
- Repository: https://github.com/atr0jan/bsidessd-hacker-jeopardy

## Overview

This is a network-hosted, multiplayer Jeopardy game. The host adds teams and selects modes in the lobby, then runs clues and judges answers in the admin panel while a separate board displays game updates. The server routes browser views and broadcasts game events; the game logic manages rounds, scores, and clue state. README-documented capabilities also include Daily Doubles, Wheel of Chaos, Final Jeopardy, tie breakers, and results export. Source excerpts show the core event handling; some view-to-server relationships are documented in the README rather than shown in both endpoints.

Main entry points: [`app.py`](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/app.py) (Flask and events), [`static/js/board.js`](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/static/js/board.js) (Viewer board), [`static/js/admin.js`](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/static/js/admin.js) (Host controls), [`static/js/lobby.js`](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/static/js/lobby.js) (Team lobby)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Game setup"]
  node_lobby["Team lobby<br/>[lobby.js]"]
  node_lobby_view["Lobby view<br/>[lobby.html]"]
  node_clue_content["Clue content<br/>[clues.json]"]
end

subgraph group_hosting["Host controls"]
  node_admin["Host controls<br/>[admin.js]"]
  node_admin_view["Admin view<br/>[admin.html]"]
end

subgraph group_audience["Audience display"]
  node_board["Viewer board<br/>[board.js]"]
  node_board_view["Board view<br/>[board.html]"]
  node_sound_assets["Game sounds"]
end

subgraph group_runtime["Game runtime"]
  node_server["Flask and events<br/>[app.py]"]
  node_engine["Game state<br/>[game_logic.py]"]
  node_history["Game history<br/>[app.py]"]
  node_saved_results["Last results"]
end

node_host(("Host"))
node_players(("Players"))

node_host -->|"sets teams"| node_lobby
node_lobby -->|"starts game"| node_server
node_server -->|"renders"| node_lobby_view
node_server -->|"renders"| node_admin_view
node_server -->|"renders"| node_board_view
node_host -->|"judges clues"| node_admin
node_admin -->|"sends verdicts"| node_server
node_server -->|"broadcasts updates"| node_board
node_players -->|"views game"| node_board
node_admin -->|"reveals clues"| node_board
node_server -->|"updates state"| node_engine
node_server -->|"loads"| node_clue_content
node_board -->|"plays"| node_sound_assets
node_server -->|"records verdicts"| node_history
node_host -->|"exports standings"| node_server
node_server -->|"saves on reset"| node_saved_results

click node_lobby "https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/static/js/lobby.js"
click node_lobby_view "https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/templates/lobby.html"
click node_clue_content "https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/data/clues.json"
click node_admin "https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/static/js/admin.js"
click node_admin_view "https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/templates/admin.html"
click node_board "https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/static/js/board.js"
click node_board_view "https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/templates/board.html"
click node_sound_assets "https://github.com/atr0jan/bsidessd-hacker-jeopardy/tree/main/static/sounds"
click node_server "https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/app.py"
click node_engine "https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/game_logic.py"
click node_history "https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/app.py"
click node_saved_results "https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/last_game_results.json"

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_lobby,node_lobby_view,node_clue_content toneBlue
class node_admin,node_admin_view toneAmber
class node_board,node_board_view,node_sound_assets toneMint
class node_server,node_engine,node_history,node_saved_results toneRose
class node_host,node_players toneIndigo
```

## Components

### Game setup

- [Team lobby](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/static/js/lobby.js): `static/js/lobby.js`
- [Lobby view](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/templates/lobby.html): `templates/lobby.html`
- [Clue content](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/data/clues.json): `data/clues.json`

### Host controls

- [Host controls](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/static/js/admin.js): `static/js/admin.js`
- [Admin view](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/templates/admin.html): `templates/admin.html`

### Audience display

- [Viewer board](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/static/js/board.js): `static/js/board.js`
- [Board view](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/templates/board.html): `templates/board.html`
- [Game sounds](https://github.com/atr0jan/bsidessd-hacker-jeopardy/tree/main/static/sounds): `static/sounds`

### Game runtime

- [Flask and events](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/app.py): `app.py`
- [Game state](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/game_logic.py): `game_logic.py`
- [Game history](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/app.py): `app.py`
- [Last results](https://github.com/atr0jan/bsidessd-hacker-jeopardy/blob/main/last_game_results.json): `last_game_results.json`

### Other components

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

## Connections

- Host → Team lobby: sets teams (evidence: `readme.md`)
- Team lobby → Flask and events: starts game (evidence: `static/js/lobby.js`)
- Flask and events → Lobby view: renders (evidence: `app.py`)
- Flask and events → Admin view: renders (evidence: `app.py`)
- Flask and events → Board view: renders (evidence: `app.py`)
- Host → Host controls: judges clues (evidence: `readme.md`)
- Host controls → Flask and events: sends verdicts (evidence: `static/js/admin.js`)
- Flask and events → Viewer board: broadcasts updates (evidence: `app.py`)
- Players → Viewer board: views game (evidence: `readme.md`)
- Host controls → Viewer board: reveals clues (evidence: `readme.md`)
- Flask and events → Game state: updates state (evidence: `app.py`)
- Flask and events → Clue content: loads (evidence: `app.py`)
- Viewer board → Game sounds: plays (evidence: `static/js/board.js`)
- Flask and events → Game history: records verdicts (evidence: `app.py`)
- Host → Flask and events: exports standings (evidence: `app.py`)
- Flask and events → Last results: saves on reset (evidence: `app.py`)
