🎓

QuizApp

Real-time multiplayerova kvizova platforma

Technicka prezentacia projektu

Prehlad aplikacie

QuizApp umoznuje hostitelom vytvarat interaktivne kvizy a hracom suazit v realnom case. Hry sa spustaju cez 6-ciferny PIN alebo QR kod a nevyzaduju registraciu hracov.

Klucove cisla

5 typov otazok
7 hernych faz (lobby → finished)
32 REST API endpointov
24+ Socket.IO real-time eventov
~14 900 riadkov TypeScript kodu
162 zdrojovych suborov

Host (organizator)

Vytvara a spravuje kvizy
Spusta hru a riadi priebeh
Vidi leaderboard a statistiky
Nezdielanie vysledkov cez verejny link

Hrac (ucastnik)

Pripaja sa cez PIN / QR kod
Odpoveda na otazky v realnom case
Vidi skore, rank a streak
Nevyzaduje registraciu

Typy otazok

✅ Multiple Choice

Jedna spravna odpoved z 2-8 moznosti. Farebne a tvarove odlisenie odpovedov.

⚪ True / False

Binarna volba - pravda alebo nepravda. Jednoduche a rychle otazky.

☑ Multi-Select

Viacero spravnych odpovedov. Podpora parcialneho bodoveho hodnotenia alebo "all or nothing".

⇅ Ordering

Drag-and-drop zoradenie do spravneho poradia. Parcialny kredit za kazdu spravnu poziciu.

🔢 Number Guess

Ciselna odpoved s toleranciou. Skore proporcionalne vzdialenosti od spravnej hodnoty.

Herny priebeh

  LOBBY  →  STARTING  →  QUESTION  →  ANSWERS  →  RESULT  →  LEADERBOARD  →  FINISHED
    |                                    |                                          |
    |   Hraci sa                    Countdown                               Opakovanie
    |   pripajaju                   + odpovede                              pre dalsiu
    |   cez PIN                     hracov                                  otazku
  

Scoring system

Zakladne body za spravnu odpoved
Casovy bonus za rychlejsiu odpoved
Streak bonus za serie spravnych odpovedov
Parcialny kredit pre multi-select a ordering

Host ovladanie

Automaticky postup medzi fazami
Manualne preskocenie (override)
Kick hraca z hry
Casovac 5-120 sekund na otazku

Hracske funkcie

Animovane zobrazenie skore
Streak indikator
Podium animacia top 3
Confetti efekt pre vitaza

Dalsie funkcionality

🔐 Autentifikacia

JWT tokeny (host 24h, hrac 4h)
Registracia s email verifikaciou
Role: user, admin, superadmin
Hraci bez registracie

📝 Sprava kvizov

WYSIWYG editor s auto-save
Public / Private viditelnost
Duplikacia kvizov
Import / Export .quiz.txt

📊 Historia a statistiky

Prehlad odohanych hier
Per-question answer distribucne grafy
Ranking progresny chart
Zdielatelny public link

🔒 Admin panel

Sprava uzivatelov (CRUD)
Aktivacia / deaktivacia uctov
Reset hesiel a zmena roli
Dashboard s KPI statistikami

🔃 Reconnection

Automaticke znovupripojenie
Obnovenie herneho stavu
Session storage perzistencia
JWT token pre reconnect

📦 Deployment

Docker Compose (PostgreSQL)
Docker Compose (SQLite)
Nginx reverse proxy
MailPit pre testovanie emailov

Architektura

Monorepo s cisto oddelenym frontend, backend a shared types.

Client (SPA)

React 18 • Vite • Tailwind CSS

~99 suborov, ~10 200 LOC

Server (API + WS)

Express • Socket.IO • Kysely

~47 suborov, ~6 000 LOC

Shared Types

TypeScript type definitions

9 suborov, ~500 LOC

CLIENT (React SPA) SERVER (Node.js) Port 5173 (dev) / 80 (prod) Port 3001 +--------------------------+ +---------------------------+ | | HTTP /api/* | | | React Router (13 pages) | <----------> | Express REST API | | Axios HTTP client | | 32 endpointov | | | | | | Socket.IO client | WebSocket | Socket.IO server | | useGameSocket hooks | <----------> | 24+ event handlerov | | | | | | Auth / Toast Context | | Game Engine (in-memory) | | Tailwind CSS styling | | State Manager + Cache | +--------------------------+ +-------------+-------------+ | +-------------+-------------+ | Kysely (Query Builder) | | SQLite / PostgreSQL | | 8 tabuliek, 5 migracii | +---------------------------+

Tech Stack

Frontend

Technologia	Ucel
React	UI framework
TypeScript	Typova bezpecnost
Vite	Build tool & dev server
Tailwind CSS	Utility-first styling
Socket.IO Client	WebSocket komunikacia
Axios	HTTP klient
React Router	Client-side routing
QRCode.React	QR kod generovanie

Backend

Technologia	Ucel
Express	HTTP framework
TypeScript	Typova bezpecnost
Socket.IO	Real-time komunikacia
Kysely	Type-safe SQL query builder
SQLite / PostgreSQL	Databaza (dual support)
JWT	Autentifikacia
Zod	Input validacia
Nodemailer	Email verifikacia

Backend - Modularna struktura

Game Engine

1 395 LOC

Databaza (DB)

1 456 LOC

Socket.IO

586 LOC

Historia

579 LOC

Auth

486 LOC

Quiz CRUD

484 LOC

Admin

484 LOC

Databazova schema

8 tabuliek: users, quizzes, questions, answers, game_sessions, players, player_answers, email_verification_codes

5 migracii: initial schema → question description → user roles → share token → number guess

API dizajn

REST pre CRUD operacie (kvizy, admin, historia)
Socket.IO pre real-time herny stav
Zod validacia na vsetkych vstupoch
Repository pattern pre databazovy pristup
Middleware pre auth, error handling, validaciu

Game Engine - jadro aplikacie

Stavovy automat (In-Memory)

Celkovy herny stav sa drzi v pamati (Map<sessionId, GameState>). Databaza sluzi len na perzistenciu.

Fazove prechody s auto-advance casovacmi
Konfigurovatelne casove limity (5-120s)
Automaticky cleanup po 5 minutach

Optimalizacie pre skalovanie

Batch DB zapisy - odpovede sa ukladaju do pamati a zapisuju sa davkovo az po skonceni otazky
Leaderboard cache s dirty flag - prepocet len pri zmene skore
Precomputed broadcast - leaderboard sa pocita 1x, nie N-krat
PostgreSQL pool - konfigurovatelna velkost (default 20)

Answer Checker

Univerzalny kontrolor spravnosti pre 5 typov:

Single: MC + T/F → presna zhoda
Multi-Select: parcialny kredit alebo all-or-nothing
Ordering: kredit per spravna pozicia
Number Guess: linearny kredit podla tolerancie

Reconnection

JWT player token ulozeny v SessionStorage
Pri reconnect: obnovenie Socket.IO rooms
Kompletna rekonstrukcia stavu hraca
Host aj hrac mozu reconnectnud kedykolvek

Frontend - komponentova architektura

Player game

1 300 LOC

Host game

1 177 LOC

Socket / RT

862 LOC

Quiz editor

790 LOC

Hooks

704 LOC

Efekty

596 LOC

Quiz mgmt

592 LOC

63 komponentov • 13 stranok • 7 custom hooks • 3 context providery

State Management

React Context - Auth, Toast, Socket (globalny)
Custom hooks - useQuizEditor (390 LOC), usePlayerGame, useHostGame
Socket hooks - useGameSocket (525 LOC) pre real-time state
SessionStorage - reconnection data

Vizualne efekty

PodiumAnimation - 3D podium s animaciou top 3
ConfettiExplosion - oslavny efekt
CountdownCircle - kruhovy odpocet
ScorePopup - animovane zobrazenie bodov
9 SVG shape komponentov pre odpovede

Real-time komunikacia

Socket.IO event flow

HOST SERVER PLAYER start-game → GameEngine.startGame() emit state-update → player:game-status emit player:question → zobraz otazku startCountdown() emit game:countdown → countdown kazdych 1s ← submit-answer ← player:submit-answer game:player-answered recordAnswer() emit answer-result → skore breakdown host:show-result → flushToDB() [batch] emit answer-distribution emit game:leaderboard → game:leaderboard emit player:state-update → per-player stav

Host → Server 7 eventov

start-game, next-question, show-answers, show-result, show-leaderboard, end-game, kick-player

Player → Server 2 eventy

join, submit-answer

Server → Klienti 14+ eventov

state-update, player-joined, countdown, time-up, answer-result, leaderboard, answer-distribution, finished, kicked...

Spolocne 1 event

reconnect-game (host aj hrac)

Odhad pracnosti - prehlad

Herny engine

100 cd

Sprava kvizov

47 cd

Historia / stats

24 cd

Testovanie

23 cd

Admin panel

22 cd

Auth + UI

22 cd

Infrastruktura

22 cd

Analyza / navrh

21 cd

Viz. efekty

13 cd

cd = clovekodni

Celkovy odhad

Scenar	Clovekodni	Trvanie
Optimisticky	250	~5 mesiacov
Realisticky	294	~6 mesiacov
Pesimisticky (+30%)	382	~7 mesiacov

Rozlozenie podla roli

Rola	Clovekodni	Podiel
BE Developer	115	39%
FE Developer	131	45%
Analytik / Tester	48	16%
Celkom	294	100%

Casovy plan - 9 faz vyvoja

Faza 1: Analyza a navrh 21 cd

Poziadavky, architektura, wireframy, DB schema • 2 tyzdne

Faza 2: Infrastruktura 22 cd

Monorepo, Express, React, Kysely, Docker • 2 tyzdne

Faza 3: Autentifikacia 22 cd

JWT, registracia, email verifikacia, login UI • 2 tyzdne

Faza 4: Sprava kvizov 47 cd

CRUD API, editor, import/export, 5 typov otazok • 3.5 tyzdna

Faza 5: Herny engine 100 cd

WebSocket, stavovy automat, scoring, reconnection • 7 tyzdnov

Faza 6: Vizualne efekty 13 cd

Shapes, podium, confetti, countdown animacie • 1 tyzden

Faza 7: Admin panel 22 cd

User management, role, KPI dashboard • 2 tyzdne

Faza 8: Historia 24 cd

Statistiky, grafy, zdielanie vysledkov • 2 tyzdne

Faza 9: Testovanie 23 cd

Integracne testy, mobile, deployment, bug fixes • 2 tyzdne

Kriticka cesta

Faza 5 (herny engine) je najdlhsia a tvori 34% celkoveho usilia. Vyzaduje uzku spolupracu BE a FE pre real-time synchronizaciu.

Porovnanie odhadov: Claude vs Codex

Odhad podla roli (clovekodni)

Faza	Claude	Codex
Analyza + navrh	21	10–17
Core backend + DB	44	18–25
Real-time engine	100	22–32
Frontend (editor, dashboard, hra)	57	39–55
Admin panel	22	14–19
Historia + statistiky	24	16–26
QA, testovanie	23	22–29
Vizualne efekty	3	–
Celkom	294	142–205

Kalendarne trvanie

	Claude	Codex
Realisticky odhad	~6 mesiacov	~2.5–3.5 mesiaca
Predpoklad	vrr. rezerv a rizik	min. zavislosti

Hlavne rozdiely

Real-time engine: Claude 100 cd vs Codex 22-32 cd – najvacsi rozdiel, Claude zapocital full reconnection + edge cases
Rizikova rezerva: Claude +30% pesimisticky scenar, Codex uvadza cisty vyvoj
Infrastruktura: Claude pocita 22 cd na setup, Codex predpoklada hotovu infra

Realita: vyvoj s AI

3 dni po veceroch, par promptov denne
Vysledok: ~14 900 LOC, plne funkcny produkt
Oproti odhadu: 50-100x rychlejsie

Zhrnutie

Funkcionalita

5 typov otazok s roznym scoringom
Real-time multiplayer cez WebSocket
Komplexny quiz editor s auto-save
Admin panel s user managementom
Historia hier a zdielatelne vysledky
Docker-ready deployment

Technicke silne stranky

Full TypeScript (client + server + shared)
Type-safe DB cez Kysely
Dual DB podpora (SQLite + PG)
Batch DB operacie pre skalovanie
Leaderboard cache s dirty flag
Robustna reconnection logika

Odhad vs realita

Claude: 294 cd (~6 mesiacov)
Codex: 142-205 cd (~2.5-3.5 mesiaca)
Realita s AI: 3 dni po veceroch
~14 900 LOC, 162 suborov
AI ako multiplikator produktivity

QuizApp je stredne az vysoko komplexny projekt, ktoreho hlavnou vyzvou je real-time herny engine s WebSocket komunikaciou, stavovym automatom a viacerymi typmi otazok s roznym scoring algoritmom.

🚀

Dakujem za pozornost

Otazky?

React 18 Express Socket.IO TypeScript Kysely Real-time