A 1920s Sherlock Holmes-themed quizmaster tool for running categorised mystery trivia nights. Multi-media questions (markdown + KaTeX + image/audio/video), multi-team scoring with negative marks, batched reveal-then-mark flow, and server-side persistence that survives refreshes and restarts.
npm install
npm run dev- Client (Vite dev server): http://localhost:5173
- API server (Express): http://localhost:3001
The client proxies /api and /media to the API server during development.
npm run build # builds client/dist and server/dist
npm start # Express serves API + client bundle on :3001npm start sets SERVE_CLIENT=1 NODE_ENV=production; open http://localhost:3001.
To run behind a different port: PORT=8080 npm start.
| Variable | Purpose |
|---|---|
PORT |
API (and prod) listen port. Default 3001. |
SERVE_CLIENT |
Set to 1 to have Express serve client/dist/ with SPA fallback. Implied by NODE_ENV=production. |
Override repo root (for when the built server lives elsewhere than config/ + data/). |
category-quiz/
├── client/ # Vite + React + TS
│ ├── src/
│ │ ├── components/ # BrassPanel, GasLampGlow, WaxSeal, InkStamp, CategoryTile, Leaderboard, MarkingGrid, MediaGallery, …
│ │ ├── pages/ # HomePage, BatchPage, MarkPage, ReviewPage
│ │ ├── store/ # Zustand slices: config, session, currentBatch
│ │ ├── lib/ # api.ts, markdown.ts (markdown-it + KaTeX)
│ │ └── styles/ # tokens.css, global.css
│ └── public/media/ # bundled images/audio/video
├── server/ # Express + TS
│ └── src/
│ ├── index.ts # bootstrap + SPA serving
│ ├── routes/ # config.ts, state.ts
│ ├── session.ts # atomic JSON writes + score math
│ └── paths.ts # repo-root resolution
├── shared/types.ts # shared TypeScript contracts (client + server)
├── config/
│ ├── quiz.json # categories + questions (hand-edited)
│ └── teams.json # team names + members
├── data/
│ └── session.json # runtime game state (gitignored; survives restarts)
├── plan.md # full architecture + build plan
└── package.json # npm workspaces root
All quiz content and teams live in config/ as hand-edited JSON. Edit, save, restart the server. The server validates both files at boot and refuses to start on malformed input.
{
title: string; // shown as chapter heading
batchSize: number; // default reveal-then-mark batch size (≥1)
categories: Category[];
}
type Category = {
id: string; // unique; stable across runs
name: string; // display name
icon?: string; // emoji/glyph for the tile
blurb?: string; // flavour text under the category name
questions: Question[];
}
type Question = {
id: string; // unique across the whole quiz
prompt: string; // markdown + KaTeX; $inline$, $$block$$
answer: string; // markdown + KaTeX
points: number; // awarded on correct mark
negativePoints?: number; // deducted on incorrect mark (default 0)
media?: MediaItem[]; // optional; multiple allowed
}
type MediaItem = {
type: 'image' | 'audio' | 'video';
src: string; // `/media/foo.jpg` (served from client/public/media) or an https URL
caption?: string;
}Authoring notes:
- Math:
$expr$for inline,$$expr$$for block. Example:$\frac{d}{dx}(x^2) = 2x$. - Markdown: full CommonMark (bold, italics, lists, blockquotes, fenced code).
- Ordering: questions are revealed in the order they appear in the file — no randomisation.
- Local media: drop files into
client/public/media/and reference as/media/filename.ext. Externalhttps://…URLs also work.
{
teams: Team[];
}
type Team = {
id: string; // unique; stable across runs
name: string; // display name
members: string[]; // shown in the team card
color?: string; // hex; used for scoreboard accents
}Adding a team to teams.json mid-event is safe — the server assigns the new team a score of 0 without touching existing scores or history.
Maintained by the server. Atomic writes via tmp-file rename so a kill mid-write can't corrupt state.
type Session = {
asked: string[]; // question IDs already revealed
scores: Record<TeamId, number>; // cumulative
batches: Batch[]; // history, for review
currentBatch: string[] | null; // selected but not yet marked
};
type Batch = {
id: string; // `batch-<timestamp>`
questionIds: string[];
marks: Record<TeamId, Record<QuestionId, boolean | null>>; // true=correct, false=wrong, null=skip
delta: Record<TeamId, number>; // points awarded this batch
at: number; // ms epoch
};Delete the file (or hit POST /api/state/reset) to wipe the game and start over.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/health |
Liveness + quiz/team counts |
| GET | /api/config |
{ quiz, teams } |
| GET | /api/state |
Current Session |
| POST | /api/state/batch |
Set/replace currentBatch — body: { questionIds: string[] } |
| POST | /api/state/ask |
Append a question to asked — body: { questionId: string } |
| POST | /api/state/mark |
Commit marks → compute delta → update scores → archive batch. Body: { marks }. |
| POST | /api/state/reset |
Wipe session |
- Finalise
config/quiz.jsonandconfig/teams.json. - Drop any local images/audio/video into
client/public/media/. npm install && npm run build.- Dry run on the actual projector:
npm start, open http://localhost:3001, walk through a batch end-to-end, hitPOST /api/state/resetwhen you're done. - Stash
data/session.jsonbefore the real event so a fresh start is guaranteed.
See plan.md for the full architecture, visual design tokens, and phased build history.