8000 GitHub - pd60193/Category-Quiz · GitHub
[go: up one dir, main page]

Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

Category Quiz — Mystery Trivia

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.


Quick start

npm install
npm run dev

The client proxies /api and /media to the API server during development.

Production build + run

npm run build        # builds client/dist and server/dist
npm start            # Express serves API + client bundle on :3001

npm start sets SERVE_CLIENT=1 NODE_ENV=production; open http://localhost:3001. To run behind a different port: PORT=8080 npm start.

Environment variables

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.
QUIZ_APP_ROOT Override repo root (for when the built server lives elsewhere than config/ + data/).

Repo layout

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

Configuration

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.

config/quiz.json

{
  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. External https://… URLs also work.

config/teams.json

{
  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.

data/session.json (runtime, don't hand-edit)

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.


API reference

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

Event-day checklist

  1. Finalise config/quiz.json and config/teams.json.
  2. Drop any local images/audio/video into client/public/media/.
  3. npm install && npm run build.
  4. Dry run on the actual projector: npm start, open http://localhost:3001, walk through a batch end-to-end, hit POST /api/state/reset when you're done.
  5. Stash data/session.json before the real event so a fresh start is guaranteed.

See plan.md for the full architecture, visual design tokens, and phased build history.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0