Italiarena
Italiarena is a language-learning game: live 1v1 quiz matches plus daily word games, in Italian and German.
I moved to Turin as an international student and Italian was the hardest part — every app I tried felt like homework, so I stopped using them. Italiarena is the practice I actually wanted: quick, competitive matches instead of flashcards. It's for anyone landing in Italy and needing to pick up the language fast.
Play the live app →
Always open source
Italiarena is open source because learning tools are better when people can inspect the product, fix rough edges, and improve the experience together. Contributions are welcome.
The project is licensed under MIT. If you want to contribute, start with CONTRIBUTING.md, open an issue, or send a focused pull request.
The hosted backend and question database are not part of this repository. That keeps the live game fair and protects the content behind the product. You can still contribute meaningfully to the app layer — UI, accessibility, match flow, settings, statistics, and client-side behavior.
What makes it different
| Idea | How it shows up in the app |
|---|
| Short, focused matches | Ten timed questions per round — grammar, vocabulary, fill-in-the-blank, and idioms |
| Real opponents | Matchmaking pairs players by language and level (CEFR A1–C1) |
| No dead waiting | Play vs bot for an instant ghost match, or search for a human opponent |
| Speed matters | Faster correct answers score more; a tie after 10 questions goes to one sudden-death round |
| Daily games | Wordle, Word Wheel (a clue for every letter) and a 60-second article Sprint (der·die·das / il·lo·la), one scored round a day per level |
| Learn from mistakes | Post-match review, mistakes that come back on spaced review days until they stick, 🔊 pronunciation, and optional AI-generated explanations (Groq) |
| Friends | Friend requests, challenges, and today's scores side by side (scores only, never answers) |
| Community quality control | Players can report bad questions; admins review a flagged/submission queue |
| Push reminders | Opt-in web push at the player's chosen hour: a streak at risk, reviews due, or a daily match (cron + service worker) |
| Works like an app on your phone | Add to home screen on iOS and Android for a full-screen experience |
Supported languages: Italian and German (switch from the header; one level per language).
Architecture
Next.js (App Router) on Vercel, backed by Supabase (Postgres + Auth + Realtime). No separate game server — a game_sessions row is the match state, and both players' browsers just stay in sync with that row.
app/ Routes, layouts, server actions — auth, matchmaking, admin
components/ UI by feature: match, matchmaking, dashboard, statistics, admin, settings
hooks/ useGameLoop (pacing) + useServerMatchSync (staying in sync)
lib/ Scoring, bot simulation, match-sync protocol, AI explanations, auth
store/ Zustand store — all in-match state
utils/ Supabase clients (browser, server, middleware)
public/ Static assets, PWA icons, sound effects
Schema and migrations live outside this repo (supabase/README.md); the sync protocol that talks to them is fully readable in lib/match-sync-client.ts and hooks/useServerMatchSync.ts.
How a match stays in sync, briefly:
- One player's browser is the sync leader and writes "start round N" to the session row; both clients only trust what they read back from the database.
- State reaches the other player three ways at once — a realtime broadcast (fastest), a DB-change subscription that triggers an instant poll, and a 1.5-second poll as a fallback. Any one dropping a message just costs a poll cycle, not a stuck match.
- Round timing is stamped by Postgres, not either device — clients estimate their clock offset once at match start, so skewed phone clocks still flip screens at the same instant and scoring stays fair.
- Answers and scores are computed by RPCs on the server, not trusted from the client — a tampered client can't write a fake score or the opponent's answer.
- Server actions were pulled out of this hot path on purpose: one browser tab runs them in a single serial queue, so a slow one (like a report submit) used to stall the next round for minutes. Everything latency-sensitive now goes browser → Supabase directly.
- Tied after 10 questions → one sudden-death question, same sync mechanism.
Development
Prerequisites
Setup
git clone https://github.com/armanalis/italiarena.git
cd italiarena
npm install
Create .env.local from the example:
cp .env.example .env.local
Fill in the Supabase values for a project you are authorized to use. For most contributions, pointing at the hosted demo backend is enough to work on UI and client behavior — ask in an issue if you are unsure.
Run locally
npm run dev
Open http://localhost:3000.
Useful commands
npm run build # production build (runs test:unit first; a failing test stops the deploy)
npm run lint # ESLint
npm run audit:questions # sanity-check the question bank for data issues
npm test # every test: scripts/test-*.ts, then the SQL suite
npm run test:sql # SQL suite only (needs the private supabase/migrations and test files)
This is the beginning of the README. Read the rest at the original. Read the full README ↗
