WordHunt - From Weekend Hack to a Platform With 22 Milestones

WordHunt started as a single word search game. The kind of thing you build in a weekend to test a new tech stack. Then people started playing it. Then teachers asked if they could use it in class. Then it needed multiplayer. Then achievements. Then guilds. Then a mobile app.

92 closed issues across 22 milestones later, it's a full educational gaming platform at wordhunt.pl.

What It Actually Is

A collection of word games designed for language learning. The core loop: pick a game, play against time or other players, learn vocabulary along the way. Everything works in Polish, English, and German.

The games share a common content pack system - curated word lists with translations, categories, and images. Build one content pack and it works across all game types.

The Games

Each game is its own milestone with 3-5 issues. The architecture is modular - every game implements a shared interface for scoring, matchmaking, and content loading.

Speed Quiz - 4 answers, pick the right translation. 20 questions, 10 seconds per answer, combo multiplier for streaks. Solo and multiplayer where first correct click wins.

Anagram - Scrambled letters, arrange them correctly. Category and image hints. Designed for younger kids (6-8).

Hangman - Classic hangman with a WordHunt mascot instead of the traditional figure. Kid-friendly. Multiplayer mode where one player picks the word.

Memory - Match word to translation or image. Grid sizes from 4x4 to 6x5. Spatial memory meets vocabulary.

Crossword - Auto-generated crosswords from content pack descriptions. This one needed a grid generation algorithm - fitting intersecting words into a fixed-size grid with maximum density. Three difficulty levels.

Word Chain - Each word must start with the last letter of the previous one. 10-15 second timer. Needs an extended dictionary beyond the content packs.

Word Builder - From a pool of 12-16 letters, find as many valid words as possible in 3 minutes. Scoring scales with word length. The most creative game - no single correct answer. Required a full dictionary for validation, which was the largest technical scope of any game.

The Platform Features

Guild System (8 issues)

Cross-game guilds of 5-20 players. Guild XP from member activity. Guild Challenges (weekly goals). Guild Wars where teams compete. Five guild levels with unlocking perks. You need player level 5+ to create a guild. This was the foundation for long-term engagement across all games.

Live Classroom (7 issues)

This came from teacher requests. A teacher creates a live session, students join via code, and the teacher launches games that appear simultaneously on all student screens. Live leaderboard updates. Session summaries with exportable results.

The WebSocket infrastructure here was tricky - a teacher controlling 30 student sessions simultaneously, each running a different game state, all needing sub-second sync. Redis pub/sub handles the fan-out.

Achievement System (3 issues)

Badges for milestones: first game, daily streaks, polyglot awards, guild master. Standard gamification but tied into the guild XP system so achievements contribute to guild progression.

Teacher Dashboard (4 issues)

Panel for managing classes, assigning games as homework, tracking student progress over time. Integration with the content pack system so teachers can create custom word lists for their curriculum.

Technical Challenges

Polish Language NLP

Word validation in Polish is significantly harder than English. Polish has 7 grammatical cases, each changing word endings. "Kot" (cat) becomes "kota", "kotu", "kotem", "kocie" depending on context. The dictionary needs to recognize all valid forms.

I built a custom morphological analyzer that handles declension and conjugation. It runs server-side to prevent client-side cheating. The dictionary has over 300,000 word forms.

Real-Time Multiplayer

WebSocket connections for live games. The matchmaking system considers player skill (ELO-based), connection quality, and regional latency. Redis handles game state with sub-100ms update cycles.

One subtle problem: clock synchronization between players. A 200ms latency difference gives one player a real advantage in Speed Quiz. We compensate by using server-side timestamps for all scoring, with the client doing optimistic updates for feel.

Anti-Cheat

When there's a leaderboard, people cheat. The game logic runs entirely server-side. Clients send actions, the server validates them. Dictionary lookups happen on the server. Timing is server-authoritative.

We still catch people using browser dev tools to intercept WebSocket messages and send fake actions. The validation layer rejects anything that doesn't match the game state machine.

Mobile (16 issues across 4 milestones)

Capacitor wrapping the React app for iOS and Android. Push notifications via FCM/APNs. Offline mode with cached content packs. Biometric login. In-app purchases tied to the existing premium system. App Store and Google Play submission with COPPA/GDPR-K compliance for kids.

The CI/CD pipeline uses GitHub Actions + Fastlane for automated builds and store uploads.

Infrastructure

The entire platform runs in Docker containers. Backend services, WebSocket servers, the NLP pipeline, Redis, PostgreSQL - all defined in docker-compose with health checks, restart policies, and resource limits. Local development is identical to production - same containers, same configs.

Cloudflare sits in front of everything. The static frontend deploys to Cloudflare Pages with automatic builds on git push. API and WebSocket traffic routes through Cloudflare's proxy for DDoS protection and SSL. The WebSocket upgrade goes through Cloudflare's tunnel - took some debugging to get the connection upgrade headers right, but once configured it handles thousands of concurrent game sessions without issues.

Monitoring runs on Grafana with Prometheus. Dashboards show active game sessions, WebSocket connection count, matchmaking queue depth, API response times by endpoint, and Redis memory usage. Alerts fire when WebSocket connections spike (possible abuse) or when matchmaking queue time exceeds 30 seconds.

Every service logs in structured JSON. Request tracing follows a session ID from the initial HTTP request through the WebSocket lifecycle to the final score submission. Makes debugging multiplayer desync issues much easier - you can reconstruct the exact sequence of events across both players.

The database runs automated backups with point-in-time recovery. Schema migrations are versioned, tested in staging, and reversible. Zero-downtime deployments using rolling container updates.

No paid infrastructure beyond domain registration. PostgreSQL, Redis, Node.js, Cloudflare free tier, GitHub Actions free tier. The full stack runs on commodity hardware and open source tooling.

Monetization

Free tier with ads (kid-safe contextual ads only). Premium tier removes ads and unlocks extra content. Teacher tier with classroom management features. Stripe and Przelewy24 for payments.

SEO & Growth

Programmatic landing pages for topics (/tematy/zwierzeta). Each content collection gets its own page with schema markup. Printable PDF worksheets for teachers - these drive organic search traffic from "wykreslanka do druku" (word search to print) queries.

Social sharing after each game with a score card - the daily challenge results are designed to be shared, similar to how Wordle results spread.

Current State

The platform handles daily active players across all game types. Development runs on the OLAB cluster. The next focus is expanding the mobile experience and adding more game types from the milestone backlog.

All 92 issues are closed. All 22 milestones are tracked. It's the most structured side project I've ever run - probably because it grew organically and needed that structure to stay manageable.