# eitaar/wahoot architecture

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

- Interactive diagram: https://gitdiagram.com/eitaar/wahoot
- Repository: https://github.com/eitaar/wahoot

## Overview

Wahoot is a browser-based third-party Kahoot client. Its primary flow validates a game PIN, collects or generates a nickname, joins the live game, and presents game/question state for answering. The graph also preserves the documented configurable modules and the session-token API. Source evidence is strongest for PIN entry and the reusable Kahoot protocol client; several UI/game-stage and module implementations are indexed but not excerpted, so those links are omitted where their runtime calls are unknown.

Main entry points: [`lib/kahoot/client.js`](https://github.com/eitaar/wahoot/blob/master/lib/kahoot/client.js) (Connection and game state), [`pages/pin.vue`](https://github.com/eitaar/wahoot/blob/master/pages/pin.vue) (PIN and nickname), [`lib/kahoot/game-service.js`](https://github.com/eitaar/wahoot/blob/master/lib/kahoot/game-service.js) (Game lookup), [`lib/kahoot/errors.js`](https://github.com/eitaar/wahoot/blob/master/lib/kahoot/errors.js) (Client errors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Join experience"]
  node_pin_page["PIN and nickname<br/>[pin.vue]"]
  node_nickname_service["Nickname generator<br/>[pin.vue]"]
  node_client_store["Client state store<br/>[client.js]"]
end

subgraph group_play["Live game"]
  node_instructions["Game instructions<br/>[instructions.vue]"]
  node_game_start["Game start<br/>[start.vue]"]
  node_get_ready["Question ready<br/>[getready.vue]"]
  node_game_block["Question play<br/>[gameblock.vue]"]
  node_answered["Answer status<br/>[answered.vue]"]
  node_game_result["Game results<br/>[result.vue]"]
  node_test_client["Client playground<br/>[client.vue]"]
  node_flood_page["Multi-client page<br/>[flood.vue]"]
end

subgraph group_kahoot["Kahoot client"]
  node_kahoot_client["Connection and game state<br/>[client.js]"]
  node_game_service["Game lookup<br/>[game-service.js]"]
  node_protocol["Message protocol<br/>[protocol.js]"]
  node_events["Event hub<br/>[events.js]"]
  node_errors["Client errors<br/>[errors.js]"]
end

subgraph group_server["Session service"]
  node_token_api["Game-token API<br/>[getGameToken.js]"]
  node_session_util["Session token derivation<br/>[kahoot-session.js]"]
end

subgraph group_modules["User modules"]
  node_module_settings["Module settings<br/>[moduleConfig.js]"]
  node_module_controls["Module controls<br/>[modules.vue]"]
  node_settings_ui["Settings panel<br/>[setting.vue]"]
end

node_player(("Player"))
node_kahoot_service(("Kahoot game service"))

node_player -->|"enters PIN"| node_pin_page
node_pin_page -->|"checks PIN"| node_kahoot_client
node_pin_page -->|"fetches names"| node_nickname_service
node_nickname_service -->|"requests names"| node_kahoot_service
node_pin_page -->|"joins game"| node_kahoot_client
node_kahoot_client -->|"looks up game"| node_game_service
node_game_service -->|"fetches session"| node_kahoot_service
node_kahoot_client -->|"builds messages"| node_protocol
node_kahoot_client -->|"emits events"| node_events
node_kahoot_client -->|"raises errors"| node_errors
node_game_service -->|"raises errors"| node_errors
node_protocol -->|"raises errors"| node_errors
node_kahoot_client -->|"opens WebSocket"| node_kahoot_service
node_kahoot_service -->|"sends game events"| node_kahoot_client
node_kahoot_client -->|"stores client"| node_client_store
node_pin_page -->|"navigates to"| node_instructions
node_player -->|"uses test UI"| node_test_client
node_test_client -->|"joins and answers"| node_kahoot_client
node_player -->|"uses multi-client UI"| node_flood_page
node_flood_page -->|"joins sessions"| node_kahoot_service
node_player -->|"requests token"| node_token_api
node_token_api -->|"gets session"| node_session_util
node_session_util -->|"fetches session"| node_kahoot_service
node_player -->|"configures features"| node_module_controls
node_module_controls -.->|"uses settings"| node_module_settings
node_player -.->|"opens settings"| node_settings_ui
node_module_settings -->|"controls join options"| node_pin_page
node_instructions -.->|"continues to"| node_game_start
node_game_start -.->|"advances to"| node_get_ready
node_get_ready -.->|"advances to"| node_game_block
node_game_block -.->|"submits answer"| node_answered
node_answered -.->|"shows result"| node_game_result

click node_pin_page "https://github.com/eitaar/wahoot/blob/master/pages/pin.vue"
click node_nickname_service "https://github.com/eitaar/wahoot/blob/master/pages/pin.vue"
click node_instructions "https://github.com/eitaar/wahoot/blob/master/pages/game/instructions.vue"
click node_game_start "https://github.com/eitaar/wahoot/blob/master/pages/game/start.vue"
click node_get_ready "https://github.com/eitaar/wahoot/blob/master/pages/game/getready.vue"
click node_game_block "https://github.com/eitaar/wahoot/blob/master/pages/game/gameblock.vue"
click node_answered "https://github.com/eitaar/wahoot/blob/master/pages/game/answered.vue"
click node_game_result "https://github.com/eitaar/wahoot/blob/master/pages/game/result.vue"
click node_kahoot_client "https://github.com/eitaar/wahoot/blob/master/lib/kahoot/client.js"
click node_game_service "https://github.com/eitaar/wahoot/blob/master/lib/kahoot/game-service.js"
click node_protocol "https://github.com/eitaar/wahoot/blob/master/lib/kahoot/protocol.js"
click node_events "https://github.com/eitaar/wahoot/blob/master/lib/kahoot/events.js"
click node_errors "https://github.com/eitaar/wahoot/blob/master/lib/kahoot/errors.js"
click node_token_api "https://github.com/eitaar/wahoot/blob/master/server/api/getGameToken.js"
click node_session_util "https://github.com/eitaar/wahoot/blob/master/server/utils/kahoot-session.js"
click node_module_settings "https://github.com/eitaar/wahoot/blob/master/stores/moduleConfig.js"
click node_module_controls "https://github.com/eitaar/wahoot/blob/master/components/modules.vue"
click node_settings_ui "https://github.com/eitaar/wahoot/blob/master/components/setting.vue"
click node_client_store "https://github.com/eitaar/wahoot/blob/master/stores/client.js"
click node_test_client "https://github.com/eitaar/wahoot/blob/master/pages/client.vue"
click node_flood_page "https://github.com/eitaar/wahoot/blob/master/pages/flood.vue"

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_pin_page,node_nickname_service,node_client_store toneBlue
class node_instructions,node_game_start,node_get_ready,node_game_block,node_answered,node_game_result,node_test_client,node_flood_page toneAmber
class node_kahoot_client,node_game_service,node_protocol,node_events,node_errors toneMint
class node_token_api,node_session_util toneRose
class node_module_settings,node_module_controls,node_settings_ui,node_player,node_kahoot_service toneIndigo
```

## Components

### Join experience

- [PIN and nickname](https://github.com/eitaar/wahoot/blob/master/pages/pin.vue): `pages/pin.vue`
- [Nickname generator](https://github.com/eitaar/wahoot/blob/master/pages/pin.vue): `pages/pin.vue`
- [Client state store](https://github.com/eitaar/wahoot/blob/master/stores/client.js): `stores/client.js`

### Live game

- [Game instructions](https://github.com/eitaar/wahoot/blob/master/pages/game/instructions.vue): `pages/game/instructions.vue`
- [Game start](https://github.com/eitaar/wahoot/blob/master/pages/game/start.vue): `pages/game/start.vue`
- [Question ready](https://github.com/eitaar/wahoot/blob/master/pages/game/getready.vue): `pages/game/getready.vue`
- [Question play](https://github.com/eitaar/wahoot/blob/master/pages/game/gameblock.vue): `pages/game/gameblock.vue`
- [Answer status](https://github.com/eitaar/wahoot/blob/master/pages/game/answered.vue): `pages/game/answered.vue`
- [Game results](https://github.com/eitaar/wahoot/blob/master/pages/game/result.vue): `pages/game/result.vue`
- [Client playground](https://github.com/eitaar/wahoot/blob/master/pages/client.vue): `pages/client.vue`
- [Multi-client page](https://github.com/eitaar/wahoot/blob/master/pages/flood.vue): `pages/flood.vue`

### Kahoot client

- [Connection and game state](https://github.com/eitaar/wahoot/blob/master/lib/kahoot/client.js): `lib/kahoot/client.js`
- [Game lookup](https://github.com/eitaar/wahoot/blob/master/lib/kahoot/game-service.js): `lib/kahoot/game-service.js`
- [Message protocol](https://github.com/eitaar/wahoot/blob/master/lib/kahoot/protocol.js): `lib/kahoot/protocol.js`
- [Event hub](https://github.com/eitaar/wahoot/blob/master/lib/kahoot/events.js): `lib/kahoot/events.js`
- [Client errors](https://github.com/eitaar/wahoot/blob/master/lib/kahoot/errors.js): `lib/kahoot/errors.js`

### Session service

- [Game-token API](https://github.com/eitaar/wahoot/blob/master/server/api/getGameToken.js): `server/api/getGameToken.js`
- [Session token derivation](https://github.com/eitaar/wahoot/blob/master/server/utils/kahoot-session.js): `server/utils/kahoot-session.js`

### User modules

- [Module settings](https://github.com/eitaar/wahoot/blob/master/stores/moduleConfig.js): `stores/moduleConfig.js`
- [Module controls](https://github.com/eitaar/wahoot/blob/master/components/modules.vue): `components/modules.vue`
- [Settings panel](https://github.com/eitaar/wahoot/blob/master/components/setting.vue): `components/setting.vue`

### Other components

- **Player**
- **Kahoot game service**

## Connections

- Player → PIN and nickname: enters PIN (evidence: `pages/pin.vue`)
- PIN and nickname → Connection and game state: checks PIN (evidence: `pages/pin.vue`)
- PIN and nickname → Nickname generator: fetches names (evidence: `pages/pin.vue`)
- Nickname generator → Kahoot game service: requests names (evidence: `pages/pin.vue`)
- PIN and nickname → Connection and game state: joins game (evidence: `pages/pin.vue`)
- Connection and game state → Game lookup: looks up game (evidence: `lib/kahoot/client.js`)
- Game lookup → Kahoot game service: fetches session (evidence: `lib/kahoot/game-service.js`)
- Connection and game state → Message protocol: builds messages (evidence: `lib/kahoot/client.js`)
- Connection and game state → Event hub: emits events (evidence: `lib/kahoot/client.js`)
- Connection and game state → Client errors: raises errors (evidence: `lib/kahoot/client.js`)
- Game lookup → Client errors: raises errors (evidence: `lib/kahoot/game-service.js`)
- Message protocol → Client errors: raises errors (evidence: `lib/kahoot/protocol.js`)
- Connection and game state → Kahoot game service: opens WebSocket (evidence: `lib/kahoot/client.js`)
- Kahoot game service → Connection and game state: sends game events (evidence: `lib/kahoot/client.js`)
- Connection and game state → Client state store: stores client
- PIN and nickname → Game instructions: navigates to (evidence: `pages/pin.vue`)
- Player → Client playground: uses test UI (evidence: `pages/client.vue`)
- Client playground → Connection and game state: joins and answers (evidence: `pages/client.vue`)
- Player → Multi-client page: uses multi-client UI (evidence: `pages/flood.vue`)
- Multi-client page → Kahoot game service: joins sessions (evidence: `pages/flood.vue`)
- Player → Game-token API: requests token (evidence: `server/api/getGameToken.js`)
- Game-token API → Session token derivation: gets session (evidence: `server/api/getGameToken.js`)
- Session token derivation → Kahoot game service: fetches session (evidence: `server/utils/kahoot-session.js`)
- Player → Module controls: configures features (evidence: `README.md`)
- Module controls → Module settings: uses settings
- Player → Settings panel: opens settings
- Module settings → PIN and nickname: controls join options (evidence: `pages/pin.vue`)
- Game instructions → Game start: continues to
- Game start → Question ready: advances to
- Question ready → Question play: advances to
- Question play → Answer status: submits answer
- Answer status → Game results: shows result
