MiniQuiz

MiniQuiz is a small full-stack trivia game with a TypeScript Express backend, a React + Vite frontend, and SQLite persistence via Prisma.

Features

• Start timed quiz sessions with configurable duration.
• Answer multiple-choice questions and receive instant validation and explanations.
• Server-authoritative scoring with session persistence.
• Submit high scores to a persistent leaderboard.
• Auto-generated Swagger reference at /api/docs.
• Shared TypeScript types between server and client.

Project Layout

miniquiz-vibecoded/
  package.json            # root scripts (install, dev, build, test)
  .env.example            # environment variables
  server/                 # Express API + Prisma ORM
  web/                    # React + Vite frontend

Getting Started

1. Environment

   cp .env.example server/.env
   cp .env.example .env

   Adjust DATABASE_URL or PORT if needed.

2. Install dependencies

   npm install
   npm run prisma:generate
   npm run prisma:migrate
   npm run prisma:seed

3. Run in development

   npm run dev

   • Backend: http://localhost:3010
   • Frontend: http://localhost:5170 (Vite proxies /api to the backend).

4. Build for production

   npm run build
   npm start

   Express serves the static client from server/dist/client when CLIENT_DIST is configured (defaults are already wired in index.ts).

Testing

• Run all tests: npm test
• Backend tests (server): Vitest + Supertest hit the Express app. Tests bootstrap the SQLite schema automatically and write to server/prisma/test.db.
• Frontend tests (web): Vitest + Testing Library; DOM helpers are set up via web/vitest.setup.ts.

API Notes

• Swagger docs: http://localhost:3010/api/docs
• Question options are JSON-encoded arrays in SQLite and never expose correctIndex to the client.
• POST /api/answers/validate accepts an optional sessionId. When provided, the server records authoritative correctness for that session. POST /api/scores/apply ignores the client-provided correct flag and recomputes scoring using stored validation data.
• Scores award +10 points per correct answer and keep totalAnswered, correctCount, and currentScore in sync with the Answered table.

Frontend Flow

1. /start starts a 60-second session and redirects to /play.
2. /play loads question batches (3 at a time), validates answers, and forwards results to /update.
3. /update applies scoring, shows the live timer and score, and routes to the next question or /summary.
4. /summary displays the final score and lets the user submit their name to the leaderboard.
5. /leaderboard shows the top 20 scores ordered by score (DESC) and timestamp (ASC).

Development Tips

• The Prisma seed script (npm run prisma:seed) loads a dozen starter questions so the game works immediately.
• Static client assets are served automatically when they exist; otherwise Express hosts only the API.
• Shared API contracts live in server/src/types/api.ts and are re-exported for the frontend at web/src/types/api.ts.