Quizzy
© 2024 Yağmur Özden. All rights reserved.
Proprietary software. Unauthorized copying or distribution is prohibited.
Running
Quizzy is two processes: the Next.js frontend on :3000 and the Socket.io game
server on :3001. Both must be running.
Local development
npm install
npm run dev:all # both processes
Docker
One image contains both processes.
# Everything in one container
docker run -p 3000:3000 -p 3001:3001 <dockerhub-user>/quizzy:latest
# Or one container per process
docker compose up
Open http://localhost:3000.
Serving other machines. Two things are host-dependent:
| Variable | Where it applies | Why |
|---|
CLIENT_URL | socket container, runtime | CORS allow-list. Defaults to localhost only, so set it to the origin people actually open, e.g. http://192.168.1.20:3000. |
NEXT_PUBLIC_SOCKET_URL | web image, build time | Normally leave unset — the client then derives the socket URL from the page's own hostname, which keeps the image portable. Set it only when the socket server runs on a different host or behind a TLS proxy. |
CLIENT_URL=http://192.168.1.20:3000 docker compose up
Room persistence
Rooms live in the socket server's memory. Without persistence configured, a
redeploy or a crash ends every match in progress. Pick a backend with one of:
| Variable | Backend | Use it for |
|---|
REDIS_URL | Redis | Production. Snapshots expire after 2h, matching the stale-room sweep. |
QUIZZY_STORE_FILE | JSON file | A single-instance deploy, or a dev box that wants matches to survive a restart. Written atomically via a temp file and rename. |
| neither | in-memory | Local development. Matches do not survive a restart. |
REDIS_URL=redis://localhost:6379 node server/server.js
QUIZZY_STORE_FILE=./.data/rooms.json node server/server.js
Snapshots are written behind broadcast(), so what the players were last told
is what is stored. A restored question restarts its clock rather than resuming
it — the players were not there for the time the server was down.
This buys restart durability, not horizontal scaling: two instances would
each keep their own working set and their own timers. Running more than one
needs per-room sticky routing plus the socket.io Redis adapter.
Analytics
Aggregate gameplay counters, for content quality rather than growth metrics:
which categories get picked, which questions are answered wrong far too often
(usually a miskeyed answer rather than a hard subject), and how long a match
runs. Read them with:
QUIZZY_STORE_FILE=./.data/rooms.json node scripts/analytics-report.js
Set ANALYTICS_TOKEN to also expose GET /analytics?token=... on the socket
server. Without that variable the route does not exist — an
unauthenticated default would publish the whole question-quality dataset,
including which answers people get wrong.
No personal data is recorded. No player id, profile id, name, socket id,
room code or IP — only counters keyed by question id, category and game mode.
tests/analytics_test.js asserts this by scanning the stored bytes.
Tests
npm test # every tests/*_test.js, sequentially
node tests/steal_flow_test.js # one suite on its own
python tests/quizzy_e2e.py # Playwright UI suite
python tests/steal_ui_check.py # drives a real match to a steal window
All three need the servers running. CI runs the first two on every push.
Project Title: QUIZZY
Role: Senior Full-Stack Software Architect & Game Designer.
Objective: Develop a real-time, browser-based competitive quiz game titled "Quizzy".
- Project Context & Vision
We are building a web application called Quizzy that adopts the minimalist and clean "room/lobby" UI logic of Codenames, but features a high-stakes, multiple-choice quiz mechanic. The focus is on real-time team collaboration, strategic voting, and a "steal" mechanic that keeps the competition intense until the last second.
- Technical Stack
Frontend: Next.js (App Router), Tailwind CSS, Lucide-react (for icons).
Backend/Real-time: Node.js + Socket.io.
Data Management: No database for Phase 1. Store all room data in a server-side rooms object (In-memory storage).
Game Flow & Rules
Phase A: Entry & Lobby (Codenames Aesthetics)
Home: A minimalist "Create Room" or "Join Room" (via code) screen.
Lobby: Team selection (Blue vs. Red). Each team capacity: 1-3 players.
Captaincy: If a team has 2+ players, an automatic "Captain Election" vote starts within the team UI.
The Coin Toss: Once teams are locked, an automated coin toss occurs. The winning captain selects a category from 4 options: General Culture, Sports, History, Cinema & Music.
Phase B: Gameplay Mechanics
Question Structure: High-difficulty questions with 5 options (A-E). Options must be tricky and conceptually close to each other to spark debate.
Team Voting: Team members vote on options in real-time. Their selections are visible to their teammates (e.g., small colored bubbles or initials next to the choices). After 60s, the option with the most votes is automatically submitted.
Scoring & Turns:
Correct Answer: 5 Points.
Incorrect Answer: The selected option is disabled (marked with a red X), and the turn passes to the opposing team.
Steal Bonus: If the opposing team correctly answers the inherited question (with fewer options remaining), they earn 10 Points.
Win Condition: First team to reach 100 Points wins the match.
Output Structure (Development Steps for the Agent)
Please proceed with the following sequence:
Folder Structure: Set up a workspace where Next.js and the Socket.io server can run concurrently (e.g., using a custom server or a separate Node process).
Server Logic: Create server.js to handle real-time events: room creation/joining, team assignment, voting synchronization, and turn-based game state.
Frontend State: Implement a useGame hook or React Context to sync the server's state with the UI (scores, timers, active players, and vote distribution).
UI Components: Build the Lobby and Question screens using Quizzy's aesthetic: pastel colors (soft blues/reds), clean typography, and card-based layouts inspired by Codenames.
Example Data Set (Target Difficulty)
Ensure the question pool matches this level of "confusing" complexity:
Question: "Which of the following structures was built before the Conquest of Istanbul (1453)?"
Options: A) Rumeli Fortress, B) Anatolian Fortress, C) Tiled Kiosk, D) Fatih Mosque, E) Theodosius Cistern.
Note: Use distractors that feel plausible to require team consensus. Instruction for the Agent: "Start by initializing the project structure and the Socket.io server. Focus on building a robust 'Room and Team' management system first. Let's make sure real-time team selection and captain voting work perfectly before building the quiz engine. Use Quizzy as the primary branding throughout the app."
