Brain Arena · IEDC Hub Tournaments

Live, offline, tournament-style logic games for college events.

The host taps Start and every connected phone gets the same puzzle at the same moment. Speed and correctness feed a live leaderboard that every device can see, along with a department-vs-department board. It all runs on one laptop's Wi-Fi hotspot with no internet, so nobody can ask an AI for the answer.

Big screen (projector)	Host console

---

What's inside

Games, all generated from a seed and checked on the server. Each has an easy, medium and hard level.

Game	What students do	Fairness
Anagram Blitz	Unscramble 6–8 words from themed packs (Tech, Campus, Food, Science), or from the host's own custom words	Dictionary anagrams also count (notes → stone)
Mini Sudoku	6×6 (easy and medium) or 9×9 (hard), with pencil marks, undo and conflict highlighting	Every puzzle has exactly one solution
Word Hunt	Wordle-style: 5 letters, 6 tries, the same word for everyone	Colours are computed on the server, so the word never reaches phones
Number Crunch	Reach the target with + − × ÷ by tapping tiles, Countdown style	Every target is guaranteed reachable
N-Queen	Classic N-Queens on 6×6 (easy), 8×8 (medium) or 10×10 (hard), with a fixed queen and blocked cells, ✕ notes and clash highlighting	Every board has exactly one completion, so a memorised textbook answer doesn't help

Scoring:

• Solve: 1000 × difficulty.
• Speed bonus: up to +500.
• First blood: +100.
• Wrong Sudoku or N-Queen check: −25.
• Partial credit (up to 300) when time runs out.
• Ties go to whoever was faster overall.

Formats: Classic (total points) and Knockout (the bottom X% is out after each round and spectates).

Every device sees the leaderboard:

• During a round: a live rank strip plus the top 10 after you finish.
• Between rounds: the answer reveal, round results, the full leaderboard with your row pinned, and Dept wars.
• At the end: a podium with funny titles ("So Close It Hurts", "Vibes Only", …).

Anti-cheat:

• Internet probe: if a phone can reach the internet (mobile data or a VPN), play freezes until it can't, and the host is told.
• Leaving the game: leaving for more than 1.5 s mid-round is a strike. Strikes go warn → −200 → round lock.
• Server-side answers: answers are only ever on the laptop. Copying and long-press menus are disabled in games.

Student ID + PIN:

• Students join with full name, Student ID (or admission / roll no., up to 10 characters), semester and department.
• On the next screen they create a 4-digit PIN the first time, or enter it later. There's no "forgot PIN"; the browser offers to save it.
• The same Student ID on another phone (with the right PIN) continues with the same score.
• PINs are scrypt-hashed on the laptop; 5 wrong tries lock the ID for 10 minutes. The host can unlock or reset a PIN from the Students tab.

Monthly leaderboard (/leaderboard):

• Every tournament is recorded on the laptop when the host shows the podium. The Monthly tab lets the host include/exclude, rename or delete them.
• Points add up per Student ID across the month; this month and previous months are shown, with a "Last updated" time.
• On the event Wi-Fi the page is live from the laptop. Online it shows config/leaderboard/monthly.json: download it from the Monthly tab, commit, push, and Vercel rebuilds (how). No Student IDs are published.

Host console:

• Playlist builder.
• Start, pause, end round, podium.
• Kick, unblock or adjust points.
• Cheat-flag feed.
• Network doctor: QR per network, players per IP, and a warning if the laptop itself has internet.
• CSV export.

Robustness:

• Crash safety: snapshots and an event log on disk. Restart and everything is restored.
• Clock sync: clocks are synced to the server, so countdowns line up.
• Reconnects: phones rejoin on reconnect with their device token, and a duplicate tab gets bumped.

Design: a "back-bench notebook" look:

• graph paper and marker outlines,
• sticker buttons and taped paper slips,
• highlighter accents,
• Bulbu, the doodled lightbulb who sweats when the timer runs low,
• doodle avatars made from 2,250 combinations,
• sounds synthesised in the browser, with no audio files.

Vibe Hackathon (team competition) at /competitions/vibecoding/: teams of 2–4 build a real one-page site on their phones by asking an AI (Google Gemini), tile by tile, with hidden automated checks; then they solve a sliding puzzle, publish their site on the event network and handle a "client's change request". Save Points, Go Back, Project Notes, hints, a live projector wall, voting and awards. Friendly words at first; the real ones (prompt, commit, revert, deploy) are revealed at the end. See docs/competitions/ and the event-day runbook.

---

Changing text and settings

All wording (titles, descriptions, buttons, funny messages), the department list, scoring numbers, timings and word lists live in config/. Edit a file there and every screen updates. No app code to touch. config/README.md has a "change X → edit file Y" table.

---

Running an event

👉 Read docs/EVENT_DAY.md. It's the checklist for hosts.

Short version (Windows laptop):

1. pnpm pack:arena on a dev machine, then copy dist/brain-arena/ to the laptop. The laptop only needs Node.js 20+.
2. Once, as admin: run setup-hotspot.ps1. It raises the Mobile Hotspot limit to 128 (WifiMaxPeers), keeps the hotspot awake, opens the firewall and sets up the loopback adapter, so the hotspot has no internet.
3. On the day, double-click start-arena.bat. It turns on the hotspot and starts the server.
4. Students join the Wi-Fi and open http://192.168.137.1:4000 (the address never changes, so print the QR).
5. Host: http://localhost:4000/host/ (the PIN is in the terminal). Projector: http://localhost:4000/screen/.

For more phones than the laptop's Wi-Fi card can handle, you can add Wi-Fi sharing repeater phones (same URL) or USB Wi-Fi dongles (one QR per network). The guide covers both.

---

Deploy the online site (Vercel)

The web app is a static export, so Vercel can host the online half: the landing page, solo practice and the installable PWA. Live events still run on the laptop. Vercel can't host the arena server, because it needs a long-running WebSocket process.

1. In Vercel, choose Add New → Project and import ajayda24/iedc-hub-tournaments.
2. Set Root Directory to apps/web and leave "Include files outside the root directory" on. Everything else comes from apps/web/vercel.json: a pnpm workspace install, next build --webpack and output out/, deployed as a plain static site (framework "Other").
3. If an old deploy fails with routes-manifest.json couldn't be found, set Settings → Build & Deployment → Framework Preset to Other and redeploy.
4. No environment variables are needed. Every push to main redeploys.

---

Development

pnpm install
pnpm dev            # arena on :4000 + Next dev server on :3000
                    # open http://localhost:3000/host/ (PIN printed by the arena), /screen/, /play/
pnpm check          # typecheck + unit tests: run before every push
pnpm test           # engine + arena unit tests (Vitest)
pnpm build          # static web export (apps/web/out, precompressed) + arena bundle
pnpm start          # arena serving the built app on :4000
pnpm test:e2e       # Playwright: real arena + browsers (needs `pnpm build` first)
pnpm bots --n 80    # 80 simulated students who actually solve puzzles (dry run / load test)
pnpm pack:arena     # dist/brain-arena: single-folder build for the event laptop
pnpm vibecoding:bots     # Vibe Hackathon load test: 15 simulated teams + a forced restart (mock AI)
pnpm vibecoding:models   # which Gemini models your key can use
pnpm vibecoding:quality  # can the real models build every tile? (24 beginner prompts)

Measured locally with pnpm bots --n 80 over four rounds:

• the arena process used ~2% CPU and ~140 MB RAM,
• the leaderboard reflected a submit after p50 ~300 ms / p95 < 500 ms (updates are throttled to 2 per second),
• first load on a phone is about 165 KB of gzipped JS, and game screens are split into their own chunks.

Project map

config/            ✏️  ALL text, settings, word lists and the published leaderboard (edit here, no code)
  copy/                words on every screen, one file per screen
  leaderboard/         monthly.json, what the website's /leaderboard shows
  words/               Word Hunt and Anagram word lists
apps/
  web/             📱  everything on a screen: phones, host console, projector, practice, leaderboard
    app/               one folder per URL (/play, /host, /screen, …)
    src/screens/       the page screens        src/games/   one view per game
    src/ui/            shared pieces           src/net/     connection to the arena
  arena/           💻  the laptop server: rounds, scoring, PINs, history, crash safety
    src/competitions/  team competitions (Vibe Hackathon): AI gateway, check runner, published sites
packages/shared/   🧩  game engines + rules shared by both: protocol, scoring, monthly board
  src/competitions/  the pure rules of each competition (Vibe Hackathon: tiles, checks, scoring, puzzle)
scripts/           🛠️  build helpers; scripts/event-kit/ holds the .bat/.ps1 files for the laptop
e2e/               ✅  end-to-end tests (a real arena + browser)
docs/              📖  EVENT_DAY.md (host checklist), ADD_A_GAME.md, screenshots
dist/brain-arena/  📦  the built event kit (gitignored). Its arena-data/ is the real event data

Each folder has a short README with a file-by-file map: config, apps/web, apps/arena, packages/shared, scripts.

Where does a change go?

I want to…	Go to
Change wording, departments, points, timings	config/
Change how a page looks or behaves	apps/web/src/screens/ (page) or apps/web/src/ui/ (shared piece)
Change a game's puzzles or answer checking	packages/shared/src/games/<id>/
Change a game's look on the phone	apps/web/src/games/<Name>View.tsx
Change round flow, scoring rules in play, PINs, history	apps/arena/src/
Add a game	docs/ADD_A_GAME.md
Change Vibe Hackathon's tiles, scoring, AI models	config/competitions/vibecoding/ (tasks, scoring, models .json)
Add a team competition	docs/competitions/ADD_A_COMPETITION.md
Change the laptop start/hotspot scripts	scripts/event-kit/

Keeping it working: run pnpm check before pushing (GitHub also runs it on every push, see .github/workflows/ci.yml). For bigger changes, also pnpm build and pnpm test:e2e.

How it works

• Same build, two homes.
  • Online (e.g. Vercel): the landing page, solo practice that works offline once installed, and content updates through the service worker.
  • At the event: the laptop serves the same static files over plain http on the LAN, so phones need nothing pre-installed.
  • The installed online PWA links across to the LAN URL instead of connecting directly. Browsers block ws:// from https pages, and service workers need HTTPS.
• Server-authoritative rounds.
  • Puzzles are generated with a fresh seed when the host starts a round.
  • Players only get the public part, and only once the countdown ends.
  • Every move is checked and timestamped by the arena.
• Adding a game. An engine in packages/shared/src/games/<id>/ plus a view in apps/web/src/games/. The full checklist is in docs/ADD_A_GAME.md.
• Content. All text and constants live in config/ (see above). Word lists come from the MIT word-list package. Edit config/words/wordhunt-answers.txt or config/words/anagram-packs.source.json, then run pnpm content:build.

---

Roadmap ideas

More games:

• Emoji Rebus: guess the movie from emojis, very funny on a projector.
• Code Breaker: Mastermind-style.
• Odd One Out quick-fire.
• Memory Flash.
• Lights Out.
• Mini Nonogram.
• Sequence Sniper: what comes next.
• Riddle Rush.
• Reaction trap: "don't tap red".

Spice:

• power-ups (Freeze the top 3 for 3 s, Hint),
• team relay rounds,
• spectator reactions flying across the big screen,
• PDF winner certificates.

Platform:

• an online mode,
• syncing the monthly leaderboard automatically (a database instead of a committed file),
• a daily puzzle,
• a satellite-relay mode (--upstream) for a second laptop,
• an Android host app.

Known limits

• A web page can detect internet and freeze play, but it can't switch off a phone's mobile data. It also can't see a second phone or a friend helping. Walk around!
• Wake Lock (keeping screens on) needs HTTPS, so it isn't available on the LAN. Ask students to raise their screen timeout.
• The 128-peer registry setting is Windows' cap. The laptop's Wi-Fi card decides the real number, so do a dry run.
• setup-hotspot.ps1 / start-hotspot.ps1 are written for Windows 10/11 and need a quick test on your laptop.