# hum2a/26 architecture

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

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

## Overview

This is a hosted party quiz: guests join on phones and answer individually while a presenter’s big-screen stage follows the room; an administrator manages and rehearses the event. The API’s room routes coordinate room actions, while question packs provide quiz content. Distinct supporting capabilities include administrator sign-in, guest media, results/archive, and kart play. The README documents the overall experience; sampled excerpts show selected route and service calls, but do not establish every connection among subsystems.

Main entry points: [`apps/web/src/admin/admin-page.tsx`](https://github.com/hum2a/26/blob/master/apps/web/src/admin/admin-page.tsx) (Admin console), [`apps/api/src/room/routes.ts`](https://github.com/hum2a/26/blob/master/apps/api/src/room/routes.ts) (Room API), [`apps/web/src/join`](https://github.com/hum2a/26/tree/master/apps/web/src/join) (Room join), [`apps/web/src/play/guest-play.tsx`](https://github.com/hum2a/26/blob/master/apps/web/src/play/guest-play.tsx) (Question play)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guest["Guest play"]
  node_guest_ui["Guest experience<br/>[guest-page.tsx]"]
  node_join_ui["Room join"]
  node_answer_ui["Question play<br/>[guest-play.tsx]"]
  node_stage_ui["Projector stage<br/>[stage-page.tsx]"]
end

subgraph group_runtime["Room runtime"]
  node_room_routes["Room API<br/>[routes.ts]"]
  node_room_state[("Party room<br/>[party-room.ts]")]
  node_room_registry[("Room registry<br/>[registry.ts]")]
end

subgraph group_content["Game content"]
  node_question_runtime["Question runtime<br/>[runtime.ts]"]
  node_question_packs["Birthday question pack<br/>[manifest.ts]"]
  node_authoring["Question authoring<br/>[authoring.ts]"]
end

subgraph group_operations["Event operations"]
  node_admin_ui["Admin console<br/>[admin-page.tsx]"]
  node_auth_routes["Admin authentication<br/>[routes.ts]"]
  node_media_routes["Media API<br/>[routes.ts]"]
  node_media_store[("Media storage<br/>[store.ts]")]
  node_results["Results delivery<br/>[delivery.ts]"]
  node_archive[("Room archive<br/>[store.ts]")]
end

subgraph group_extensions["Additional modes"]
  node_kart["Kart game mode"]
  node_trolls["Troll effects<br/>[engine.ts]"]
end

node_guests(("Party guests"))
node_presenter(("Presenter"))
node_admin(("Administrator"))

node_guests -->|"join by code"| node_join_ui
node_join_ui -->|"enter lobby"| node_guest_ui
node_guests -->|"play on phones"| node_answer_ui
node_presenter -->|"present event"| node_stage_ui
node_admin -->|"manage event"| node_admin_ui
node_admin_ui -->|"sign in"| node_auth_routes
node_room_routes -->|"dispatch room actions"| node_room_state
node_room_routes -.->|"resolve rooms"| node_room_registry
node_admin_ui -->|"manage and rehearse"| node_room_routes
node_stage_ui -->|"follow room"| node_room_routes
node_answer_ui -->|"submit answers"| node_room_routes
node_question_packs -.->|"supply questions"| node_question_runtime
node_authoring -->|"define questions"| node_question_packs
node_admin_ui -.->|"manage media"| node_media_routes
node_media_routes -->|"read and write"| node_media_store
node_admin -.->|"review results"| node_results
node_results -.->|"deliver archived results"| node_archive
node_admin_ui -.->|"configure kart mode"| node_kart
node_room_state -.->|"apply room effects"| node_trolls

click node_guest_ui "https://github.com/hum2a/26/blob/master/apps/web/src/guest/guest-page.tsx"
click node_join_ui "https://github.com/hum2a/26/tree/master/apps/web/src/join"
click node_answer_ui "https://github.com/hum2a/26/blob/master/apps/web/src/play/guest-play.tsx"
click node_stage_ui "https://github.com/hum2a/26/blob/master/apps/web/src/stage/stage-page.tsx"
click node_room_routes "https://github.com/hum2a/26/blob/master/apps/api/src/room/routes.ts"
click node_room_state "https://github.com/hum2a/26/blob/master/apps/api/src/room/party-room.ts"
click node_room_registry "https://github.com/hum2a/26/blob/master/apps/api/src/room/registry.ts"
click node_question_runtime "https://github.com/hum2a/26/blob/master/apps/api/src/questions/runtime.ts"
click node_question_packs "https://github.com/hum2a/26/blob/master/apps/api/src/questions/packs/birthday/manifest.ts"
click node_authoring "https://github.com/hum2a/26/blob/master/apps/api/src/questions/authoring.ts"
click node_admin_ui "https://github.com/hum2a/26/blob/master/apps/web/src/admin/admin-page.tsx"
click node_auth_routes "https://github.com/hum2a/26/blob/master/apps/api/src/auth/routes.ts"
click node_media_routes "https://github.com/hum2a/26/blob/master/apps/api/src/media/routes.ts"
click node_media_store "https://github.com/hum2a/26/blob/master/apps/api/src/media/store.ts"
click node_results "https://github.com/hum2a/26/blob/master/apps/api/src/results/delivery.ts"
click node_archive "https://github.com/hum2a/26/blob/master/apps/api/src/archive/store.ts"
click node_kart "https://github.com/hum2a/26/tree/master/apps/api/src/room/kart"
click node_trolls "https://github.com/hum2a/26/blob/master/apps/api/src/troll/engine.ts"

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_guest_ui,node_join_ui,node_answer_ui,node_stage_ui toneBlue
class node_room_routes,node_room_state,node_room_registry toneAmber
class node_question_runtime,node_question_packs,node_authoring toneMint
class node_admin_ui,node_auth_routes,node_media_routes,node_media_store,node_results,node_archive toneRose
class node_kart,node_trolls,node_guests,node_presenter,node_admin toneIndigo
```

## Components

### Guest play

- [Guest experience](https://github.com/hum2a/26/blob/master/apps/web/src/guest/guest-page.tsx): `apps/web/src/guest/guest-page.tsx`
- [Room join](https://github.com/hum2a/26/tree/master/apps/web/src/join): `apps/web/src/join`
- [Question play](https://github.com/hum2a/26/blob/master/apps/web/src/play/guest-play.tsx): `apps/web/src/play/guest-play.tsx`
- [Projector stage](https://github.com/hum2a/26/blob/master/apps/web/src/stage/stage-page.tsx): `apps/web/src/stage/stage-page.tsx`

### Room runtime

- [Room API](https://github.com/hum2a/26/blob/master/apps/api/src/room/routes.ts): `apps/api/src/room/routes.ts`
- [Party room](https://github.com/hum2a/26/blob/master/apps/api/src/room/party-room.ts): `apps/api/src/room/party-room.ts`
- [Room registry](https://github.com/hum2a/26/blob/master/apps/api/src/room/registry.ts): `apps/api/src/room/registry.ts`

### Game content

- [Question runtime](https://github.com/hum2a/26/blob/master/apps/api/src/questions/runtime.ts): `apps/api/src/questions/runtime.ts`
- [Birthday question pack](https://github.com/hum2a/26/blob/master/apps/api/src/questions/packs/birthday/manifest.ts): `apps/api/src/questions/packs/birthday/manifest.ts`
- [Question authoring](https://github.com/hum2a/26/blob/master/apps/api/src/questions/authoring.ts): `apps/api/src/questions/authoring.ts`

### Event operations

- [Admin console](https://github.com/hum2a/26/blob/master/apps/web/src/admin/admin-page.tsx): `apps/web/src/admin/admin-page.tsx`
- [Admin authentication](https://github.com/hum2a/26/blob/master/apps/api/src/auth/routes.ts): `apps/api/src/auth/routes.ts`
- [Media API](https://github.com/hum2a/26/blob/master/apps/api/src/media/routes.ts): `apps/api/src/media/routes.ts`
- [Media storage](https://github.com/hum2a/26/blob/master/apps/api/src/media/store.ts): `apps/api/src/media/store.ts`
- [Results delivery](https://github.com/hum2a/26/blob/master/apps/api/src/results/delivery.ts): `apps/api/src/results/delivery.ts`
- [Room archive](https://github.com/hum2a/26/blob/master/apps/api/src/archive/store.ts): `apps/api/src/archive/store.ts`

### Additional modes

- [Kart game mode](https://github.com/hum2a/26/tree/master/apps/api/src/room/kart): `apps/api/src/room/kart`
- [Troll effects](https://github.com/hum2a/26/blob/master/apps/api/src/troll/engine.ts): `apps/api/src/troll/engine.ts`

### Other components

- **Party guests**
- **Presenter**
- **Administrator**

## Connections

- Party guests → Room join: join by code (evidence: `README.md`)
- Room join → Guest experience: enter lobby (evidence: `README.md`)
- Party guests → Question play: play on phones (evidence: `README.md`)
- Presenter → Projector stage: present event (evidence: `README.md`)
- Administrator → Admin console: manage event (evidence: `README.md`)
- Admin console → Admin authentication: sign in (evidence: `README.md`)
- Room API → Party room: dispatch room actions (evidence: `apps/api/src/room/routes.ts`)
- Room API → Room registry: resolve rooms
- Admin console → Room API: manage and rehearse (evidence: `README.md`)
- Projector stage → Room API: follow room (evidence: `README.md`)
- Question play → Room API: submit answers (evidence: `README.md`)
- Birthday question pack → Question runtime: supply questions
- Question authoring → Birthday question pack: define questions (evidence: `apps/api/src/questions/authoring.ts`)
- Admin console → Media API: manage media
- Media API → Media storage: read and write (evidence: `apps/api/src/media/routes.ts`)
- Administrator → Results delivery: review results
- Results delivery → Room archive: deliver archived results
- Admin console → Kart game mode: configure kart mode
- Party room → Troll effects: apply room effects
