# shadrackkimutai/questly architecture

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

- Interactive diagram: https://gitdiagram.com/shadrackkimutai/questly
- Repository: https://github.com/shadrackkimutai/questly

## Overview

Questly is a self-hosted, real-time quiz platform: a host configures and starts a game, players join with a room code and answer questions, and the host can review results. The map separates the web client, socket event handling, game runtime, and quiz/results management. The README documents quiz types, media, language support, and file-based configuration; sampled source confirms portions of socket game and manager behavior. Some unsampled route and service wiring is therefore represented only where the tree and documented capabilities support it.

Main entry points: [`packages/web/src/features/game/contexts/socket-context.tsx`](https://github.com/shadrackkimutai/questly/blob/main/packages/web/src/features/game/contexts/socket-context.tsx) (Socket client), [`packages/socket/src/index.ts`](https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/index.ts) (Socket server entry), [`packages/socket/src/services/game/index.ts`](https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/services/game/index.ts) (Game service), [`packages/web/src/pages`](https://github.com/shadrackkimutai/questly/tree/main/packages/web/src/pages) (Player and host pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_browser["Web application<br/>[main.tsx]"]
  node_game_pages["Player and host pages"]
  node_game_ui["Game interface"]
  node_game_state["Client game state"]
  node_socket_client["Socket client<br/>[socket-context.tsx]"]
end

subgraph group_socket["Socket service"]
  node_socket_entry["Socket server entry<br/>[index.ts]"]
  node_socket_handlers["Game handlers<br/>[game.ts]"]
  node_quiz_handlers["Quiz handlers<br/>[quiz.ts]"]
  node_manager_handlers["Manager handlers<br/>[manager.ts]"]
  node_results_handlers["Results handlers<br/>[results.ts]"]
  node_shared_types["Shared game contracts"]
end

subgraph group_runtime["Game runtime"]
  node_registry["Game registry<br/>[registry.ts]"]
  node_game_service["Game service<br/>[index.ts]"]
  node_round_manager["Round manager<br/>[round-manager.ts]"]
  node_player_manager["Player manager<br/>[player-manager.ts]"]
end

subgraph group_management["Quiz and results management"]
  node_quiz_editor["Quiz editor"]
  node_quiz_editor_state["Editor state"]
  node_host_config_ui["Host configuration"]
  node_results_ui["Results review"]
  node_result_export["PDF export<br/>[exportResultPdf.ts]"]
  node_manager_service["Manager authentication<br/>[manager.ts]"]
  node_config_service["Configuration service<br/>[config.ts]"]
end

node_players(("Players"))
node_host(("Host"))
node_config_files["Quiz and game files"]

node_players -->|"join game"| node_game_pages
node_host -->|"manage game"| node_game_pages
node_browser -->|"routes"| node_game_pages
node_game_pages -->|"render"| node_game_ui
node_game_ui -->|"send events"| node_socket_client
node_socket_client -->|"connects"| node_socket_entry
node_socket_entry -->|"dispatches"| node_socket_handlers
node_socket_entry -->|"dispatches"| node_quiz_handlers
node_socket_entry -->|"dispatches"| node_manager_handlers
node_socket_entry -->|"dispatches"| node_results_handlers
node_socket_handlers -->|"game actions"| node_game_service
node_game_service -->|"manages games"| node_registry
node_game_service -->|"runs rounds"| node_round_manager
node_game_service -->|"manages players"| node_player_manager
node_round_manager -->|"reads players"| node_player_manager
node_socket_client -->|"updates"| node_game_state
node_host_config_ui -->|"sends settings"| node_socket_client
node_quiz_editor -->|"edits"| node_quiz_editor_state
node_quiz_editor_state -->|"submits quiz"| node_socket_client
node_quiz_handlers -->|"quiz operations"| node_config_service
node_manager_handlers -->|"authenticates"| node_manager_service
node_manager_handlers -->|"loads config"| node_config_service
node_config_service -->|"reads and writes"| node_config_files
node_results_handlers -->|"result operations"| node_config_service
node_results_ui -->|"exports"| node_result_export
node_results_ui -->|"requests results"| node_socket_client
node_shared_types -.->|"defines contracts"| node_socket_handlers
node_shared_types -.->|"defines contracts"| node_game_state

click node_browser "https://github.com/shadrackkimutai/questly/blob/main/packages/web/src/main.tsx"
click node_game_pages "https://github.com/shadrackkimutai/questly/tree/main/packages/web/src/pages"
click node_game_ui "https://github.com/shadrackkimutai/questly/tree/main/packages/web/src/features/game/components"
click node_game_state "https://github.com/shadrackkimutai/questly/tree/main/packages/web/src/features/game/stores"
click node_socket_client "https://github.com/shadrackkimutai/questly/blob/main/packages/web/src/features/game/contexts/socket-context.tsx"
click node_quiz_editor "https://github.com/shadrackkimutai/questly/tree/main/packages/web/src/features/quiz/components"
click node_quiz_editor_state "https://github.com/shadrackkimutai/questly/blob/main/packages/web/src/features/quiz/contexts/quiz-editor-context.tsx"
click node_host_config_ui "https://github.com/shadrackkimutai/questly/tree/main/packages/web/src/features/manager/components/configurations"
click node_results_ui "https://github.com/shadrackkimutai/questly/tree/main/packages/web/src/features/manager/components/ResultModal"
click node_result_export "https://github.com/shadrackkimutai/questly/blob/main/packages/web/src/features/manager/utils/exportResultPdf.ts"
click node_socket_entry "https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/index.ts"
click node_socket_handlers "https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/handlers/game.ts"
click node_quiz_handlers "https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/handlers/quiz.ts"
click node_manager_handlers "https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/handlers/manager.ts"
click node_results_handlers "https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/handlers/results.ts"
click node_registry "https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/services/registry.ts"
click node_game_service "https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/services/game/index.ts"
click node_round_manager "https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/services/game/round-manager.ts"
click node_player_manager "https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/services/game/player-manager.ts"
click node_manager_service "https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/services/manager.ts"
click node_config_service "https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/services/config.ts"
click node_shared_types "https://github.com/shadrackkimutai/questly/tree/main/packages/common/src/types/game"

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_browser,node_game_pages,node_game_ui,node_game_state,node_socket_client toneBlue
class node_socket_entry,node_socket_handlers,node_quiz_handlers,node_manager_handlers,node_results_handlers,node_shared_types toneAmber
class node_registry,node_game_service,node_round_manager,node_player_manager toneMint
class node_quiz_editor,node_quiz_editor_state,node_host_config_ui,node_results_ui,node_result_export,node_manager_service,node_config_service toneRose
class node_players,node_host,node_config_files toneIndigo
```

## Components

### Web client

- [Web application](https://github.com/shadrackkimutai/questly/blob/main/packages/web/src/main.tsx): `packages/web/src/main.tsx`
- [Player and host pages](https://github.com/shadrackkimutai/questly/tree/main/packages/web/src/pages): `packages/web/src/pages`
- [Game interface](https://github.com/shadrackkimutai/questly/tree/main/packages/web/src/features/game/components): `packages/web/src/features/game/components`
- [Client game state](https://github.com/shadrackkimutai/questly/tree/main/packages/web/src/features/game/stores): `packages/web/src/features/game/stores`
- [Socket client](https://github.com/shadrackkimutai/questly/blob/main/packages/web/src/features/game/contexts/socket-context.tsx): `packages/web/src/features/game/contexts/socket-context.tsx`

### Socket service

- [Socket server entry](https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/index.ts): `packages/socket/src/index.ts`
- [Game handlers](https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/handlers/game.ts): `packages/socket/src/handlers/game.ts`
- [Quiz handlers](https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/handlers/quiz.ts): `packages/socket/src/handlers/quiz.ts`
- [Manager handlers](https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/handlers/manager.ts): `packages/socket/src/handlers/manager.ts`
- [Results handlers](https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/handlers/results.ts): `packages/socket/src/handlers/results.ts`
- [Shared game contracts](https://github.com/shadrackkimutai/questly/tree/main/packages/common/src/types/game): `packages/common/src/types/game`

### Game runtime

- [Game registry](https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/services/registry.ts): `packages/socket/src/services/registry.ts`
- [Game service](https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/services/game/index.ts): `packages/socket/src/services/game/index.ts`
- [Round manager](https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/services/game/round-manager.ts): `packages/socket/src/services/game/round-manager.ts`
- [Player manager](https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/services/game/player-manager.ts): `packages/socket/src/services/game/player-manager.ts`

### Quiz and results management

- [Quiz editor](https://github.com/shadrackkimutai/questly/tree/main/packages/web/src/features/quiz/components): `packages/web/src/features/quiz/components`
- [Editor state](https://github.com/shadrackkimutai/questly/blob/main/packages/web/src/features/quiz/contexts/quiz-editor-context.tsx): `packages/web/src/features/quiz/contexts/quiz-editor-context.tsx`
- [Host configuration](https://github.com/shadrackkimutai/questly/tree/main/packages/web/src/features/manager/components/configurations): `packages/web/src/features/manager/components/configurations`
- [Results review](https://github.com/shadrackkimutai/questly/tree/main/packages/web/src/features/manager/components/ResultModal): `packages/web/src/features/manager/components/ResultModal`
- [PDF export](https://github.com/shadrackkimutai/questly/blob/main/packages/web/src/features/manager/utils/exportResultPdf.ts): `packages/web/src/features/manager/utils/exportResultPdf.ts`
- [Manager authentication](https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/services/manager.ts): `packages/socket/src/services/manager.ts`
- [Configuration service](https://github.com/shadrackkimutai/questly/blob/main/packages/socket/src/services/config.ts): `packages/socket/src/services/config.ts`

### Other components

- **Players**
- **Host**
- **Quiz and game files**

## Connections

- Players → Player and host pages: join game
- Host → Player and host pages: manage game
- Web application → Player and host pages: routes
- Player and host pages → Game interface: render
- Game interface → Socket client: send events
- Socket client → Socket server entry: connects
- Socket server entry → Game handlers: dispatches
- Socket server entry → Quiz handlers: dispatches
- Socket server entry → Manager handlers: dispatches
- Socket server entry → Results handlers: dispatches
- Game handlers → Game service: game actions
- Game service → Game registry: manages games
- Game service → Round manager: runs rounds
- Game service → Player manager: manages players
- Round manager → Player manager: reads players
- Socket client → Client game state: updates
- Host configuration → Socket client: sends settings
- Quiz editor → Editor state: edits
- Editor state → Socket client: submits quiz
- Quiz handlers → Configuration service: quiz operations
- Manager handlers → Manager authentication: authenticates
- Manager handlers → Configuration service: loads config
- Configuration service → Quiz and game files: reads and writes
- Results handlers → Configuration service: result operations
- Results review → PDF export: exports
- Results review → Socket client: requests results
- Shared game contracts → Game handlers: defines contracts
- Shared game contracts → Client game state: defines contracts