# sakh1l/quizhub architecture

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

- Interactive diagram: https://gitdiagram.com/sakh1l/quizhub
- Repository: https://github.com/sakh1l/quizhub
- Video tour (about a minute): https://gitdiagram.com/sakh1l/quizhub/video

## Overview

QuizHub is a single-binary, real-time multiplayer trivia game. Hosts authenticate, manage reusable quizzes, open a room, and control game pacing; players join by code, answer timed questions, and see results and rankings. The server coordinates HTTP handlers, persistent SQLite state, and WebSocket updates, while embedded browser clients provide the host and player experiences. The README documents major product flows; unsampled admin and question-handler details are represented at their known source paths, with links limited to documented relationships.

Main entry points: [`internal/handlers/handler.go`](https://github.com/sakh1l/quizhub/blob/main/internal/handlers/handler.go) (Route registry), [`internal/ws/hub.go`](https://github.com/sakh1l/quizhub/blob/main/internal/ws/hub.go) (WebSocket hub), [`cmd/server/main.go`](https://github.com/sakh1l/quizhub/blob/main/cmd/server/main.go) (HTTP server), [`internal/handlers/room.go`](https://github.com/sakh1l/quizhub/blob/main/internal/handlers/room.go) (Room and joining)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Browser clients"]
  node_adminui["Admin panel<br/>[admin.js]"]
  node_playerui["Player app<br/>[app.js]"]
  node_webassets["Embedded assets<br/>[embed.go]"]
end

subgraph group_domain["Quiz and game"]
  node_auth["Admin access<br/>[auth.go]"]
  node_quizlibrary["Quiz library<br/>[quizzes.go]"]
  node_questions["Question management<br/>[questions.go]"]
  node_room["Room and joining<br/>[room.go]"]
  node_game["Game and scoring<br/>[game.go]"]
  node_qr["Join QR code<br/>[qr.go]"]
  node_models["Domain models<br/>[models.go]"]
end

subgraph group_runtime["Server runtime"]
  node_server["HTTP server<br/>[main.go]"]
  node_handlers["Route registry<br/>[handler.go]"]
  node_middleware["HTTP middleware<br/>[middleware.go]"]
  node_hub["WebSocket hub<br/>[hub.go]"]
end

subgraph group_persistence["Persistence"]
  node_db[("SQLite state<br/>[db.go]")]
end

node_host(("Host"))
node_player(("Player"))

node_host -->|"operates"| node_adminui
node_player -->|"uses"| node_playerui
node_adminui -.->|"calls API"| node_handlers
node_playerui -->|"calls API"| node_handlers
node_playerui -.->|"receives updates"| node_hub
node_adminui -.->|"receives updates"| node_hub
node_server -->|"registers routes"| node_handlers
node_server -->|"opens store"| node_db
node_server -->|"starts hub"| node_hub
node_server -->|"wraps requests"| node_middleware
node_server -->|"serves assets"| node_webassets
node_handlers -->|"routes auth"| node_auth
node_handlers -->|"routes room"| node_room
node_handlers -->|"routes game"| node_game
node_handlers -->|"routes questions"| node_questions
node_handlers -->|"routes quizzes"| node_quizlibrary
node_handlers -->|"routes QR"| node_qr
node_room -->|"reads and writes"| node_db
node_room -->|"broadcasts events"| node_hub
node_room -->|"uses types"| node_models
node_game -->|"reads and writes"| node_db
node_game -->|"broadcasts events"| node_hub
node_game -->|"uses types"| node_models
node_quizlibrary -->|"manages quizzes"| node_db
node_quizlibrary -->|"uses types"| node_models
node_hub -.->|"sends events"| node_adminui
node_hub -.->|"sends events"| node_playerui

click node_adminui "https://github.com/sakh1l/quizhub/blob/main/web/static/admin.js"
click node_playerui "https://github.com/sakh1l/quizhub/blob/main/web/static/app.js"
click node_server "https://github.com/sakh1l/quizhub/blob/main/cmd/server/main.go"
click node_handlers "https://github.com/sakh1l/quizhub/blob/main/internal/handlers/handler.go"
click node_middleware "https://github.com/sakh1l/quizhub/blob/main/internal/middleware/middleware.go"
click node_auth "https://github.com/sakh1l/quizhub/blob/main/internal/handlers/auth.go"
click node_quizlibrary "https://github.com/sakh1l/quizhub/blob/main/internal/handlers/quizzes.go"
click node_questions "https://github.com/sakh1l/quizhub/blob/main/internal/handlers/questions.go"
click node_room "https://github.com/sakh1l/quizhub/blob/main/internal/handlers/room.go"
click node_game "https://github.com/sakh1l/quizhub/blob/main/internal/handlers/game.go"
click node_qr "https://github.com/sakh1l/quizhub/blob/main/internal/handlers/qr.go"
click node_models "https://github.com/sakh1l/quizhub/blob/main/internal/models/models.go"
click node_hub "https://github.com/sakh1l/quizhub/blob/main/internal/ws/hub.go"
click node_db "https://github.com/sakh1l/quizhub/blob/main/internal/db/db.go"
click node_webassets "https://github.com/sakh1l/quizhub/blob/main/web/embed.go"

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_adminui,node_playerui,node_webassets toneBlue
class node_auth,node_quizlibrary,node_questions,node_room,node_game,node_qr,node_models toneAmber
class node_server,node_handlers,node_middleware,node_hub toneMint
class node_db toneRose
class node_host,node_player toneIndigo
```

## Components

### Browser clients

- [Admin panel](https://github.com/sakh1l/quizhub/blob/main/web/static/admin.js): `web/static/admin.js`
- [Player app](https://github.com/sakh1l/quizhub/blob/main/web/static/app.js): `web/static/app.js`
- [Embedded assets](https://github.com/sakh1l/quizhub/blob/main/web/embed.go): `web/embed.go`

### Quiz and game

- [Admin access](https://github.com/sakh1l/quizhub/blob/main/internal/handlers/auth.go): `internal/handlers/auth.go`
- [Quiz library](https://github.com/sakh1l/quizhub/blob/main/internal/handlers/quizzes.go): `internal/handlers/quizzes.go`
- [Question management](https://github.com/sakh1l/quizhub/blob/main/internal/handlers/questions.go): `internal/handlers/questions.go`
- [Room and joining](https://github.com/sakh1l/quizhub/blob/main/internal/handlers/room.go): `internal/handlers/room.go`
- [Game and scoring](https://github.com/sakh1l/quizhub/blob/main/internal/handlers/game.go): `internal/handlers/game.go`
- [Join QR code](https://github.com/sakh1l/quizhub/blob/main/internal/handlers/qr.go): `internal/handlers/qr.go`
- [Domain models](https://github.com/sakh1l/quizhub/blob/main/internal/models/models.go): `internal/models/models.go`

### Server runtime

- [HTTP server](https://github.com/sakh1l/quizhub/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [Route registry](https://github.com/sakh1l/quizhub/blob/main/internal/handlers/handler.go): `internal/handlers/handler.go`
- [HTTP middleware](https://github.com/sakh1l/quizhub/blob/main/internal/middleware/middleware.go): `internal/middleware/middleware.go`
- [WebSocket hub](https://github.com/sakh1l/quizhub/blob/main/internal/ws/hub.go): `internal/ws/hub.go`

### Persistence

- [SQLite state](https://github.com/sakh1l/quizhub/blob/main/internal/db/db.go): `internal/db/db.go`

### Other components

- **Host**
- **Player**

## Connections

- Host → Admin panel: operates (evidence: `README.md`)
- Player → Player app: uses (evidence: `README.md`)
- Admin panel → Route registry: calls API (evidence: `README.md`)
- Player app → Route registry: calls API (evidence: `web/static/app.js`)
- Player app → WebSocket hub: receives updates (evidence: `README.md`)
- Admin panel → WebSocket hub: receives updates (evidence: `README.md`)
- HTTP server → Route registry: registers routes (evidence: `cmd/server/main.go`)
- HTTP server → SQLite state: opens store (evidence: `cmd/server/main.go`)
- HTTP server → WebSocket hub: starts hub (evidence: `cmd/server/main.go`)
- HTTP server → HTTP middleware: wraps requests (evidence: `cmd/server/main.go`)
- HTTP server → Embedded assets: serves assets (evidence: `cmd/server/main.go`)
- Route registry → Admin access: routes auth (evidence: `internal/handlers/handler.go`)
- Route registry → Room and joining: routes room (evidence: `internal/handlers/handler.go`)
- Route registry → Game and scoring: routes game (evidence: `internal/handlers/handler.go`)
- Route registry → Question management: routes questions (evidence: `internal/handlers/handler.go`)
- Route registry → Quiz library: routes quizzes (evidence: `internal/handlers/handler.go`)
- Route registry → Join QR code: routes QR (evidence: `internal/handlers/handler.go`)
- Room and joining → SQLite state: reads and writes (evidence: `internal/handlers/room.go`)
- Room and joining → WebSocket hub: broadcasts events (evidence: `internal/handlers/room.go`)
- Room and joining → Domain models: uses types (evidence: `internal/handlers/room.go`)
- Game and scoring → SQLite state: reads and writes (evidence: `internal/handlers/game.go`)
- Game and scoring → WebSocket hub: broadcasts events (evidence: `internal/handlers/game.go`)
- Game and scoring → Domain models: uses types (evidence: `internal/handlers/game.go`)
- Quiz library → SQLite state: manages quizzes (evidence: `internal/handlers/quizzes.go`)
- Quiz library → Domain models: uses types (evidence: `internal/handlers/quizzes.go`)
- WebSocket hub → Admin panel: sends events (evidence: `README.md`)
- WebSocket hub → Player app: sends events (evidence: `README.md`)
