Hackathon Selection Test

A 12-question, 25-minute test of logical thinking, critical thinking and teamwork judgment (4 questions and 40 points each). Students take it at / in Uzbek (Latin), and the teacher reviews results and generates teams at /admin (in English).

Built with Next.js 16 (App Router), Tailwind and Drizzle ORM on PostgreSQL (Supabase), deployed on Vercel.

1. Create the Supabase databases

Use two free Supabase projects: one for development and one for production (the real test).

1. On supabase.com, create a New project. Pick a region close to your Vercel functions (and set the same region in Vercel → Project → Settings → Functions). Choose a database password and keep it.

2. When the project is ready, click Connect at the top of the project page and choose Transaction pooler. Copy that connection string:

   postgresql://postgres.<project-ref>:[YOUR-PASSWORD]@aws-0-<region>.pooler.supabase.com:6543/postgres
   

   Replace [YOUR-PASSWORD] with the database password. URL-encode special characters (@ → %40, # → %23, / → %2F, ? → %3F). Forgot it? Project Settings → Database → Reset database password.

   Use the transaction pooler (port 6543), not the direct connection: it works over IPv4 (the direct connection is IPv6-only, which Vercel can't reach) and is made for many short-lived serverless connections.

Free projects pause after a week without activity. A paused project refuses connections until you click Restore in its dashboard, which takes a minute or two. Open both projects a day before the session.

2. Run it locally

Needs Node.js 24 (22.18 or newer also works: the scripts run TypeScript files directly).

git clone https://github.com/theshoxjaxon/quiz.git
cd quiz
npm install
cp .env.example .env.local    # set ADMIN_PASSWORD, and DATABASE_URL = the DEVELOPMENT project's pooler string
npm run setup                 # creates the tables (from drizzle/) and loads the 12 questions
npm run build && npm start    # serves on port 3000

npm start and npm run dev run npm run setup first, so the database is always up to date. Without DATABASE_URL they stop with instructions. Setup prints which database it uses (host and name only, never the password).

• Students open http://<this-computer's-IP>:3000.
• Teacher opens /admin. The browser asks for a login: any username, plus the ADMIN_PASSWORD you set.
• After code changes, run npm run build again and restart npm start.

Before the session (running on a laptop)

1. Keep the Mac awake. In a separate Terminal window, run caffeinate -dimsu and leave it open until the test is over.
2. Firewall. The macOS firewall works per app, not per port. Allow incoming connections for node in System Settings → Network → Firewall → Options, or click Allow when macOS asks the first time the server starts. That opens port 3000 to the network.
3. Laptop IP. Run ipconfig getifaddr en0 (Wi-Fi) and check http://<that-IP>:3000 from a phone. The IP can change between days, so check it on the day.
4. Supabase awake. Open the project's dashboard; restore it if it's paused.
5. Test run with 2–3 devices. Register, answer, submit, then open /admin, generate teams, and lock and unlock them.
6. Clear the test data: npm run db:reset -- --yes-wipe-remote. A Supabase database always counts as remote, so reset refuses without that flag. It removes all students, submissions and the team lock, and it's safe while the server is running.

3. Deploy to Vercel

1. Create the production Supabase project and copy its transaction pooler string (section 1).

2. Create the tables and load the questions in production, from your computer. Do this once now, and again after changing questions or the schema:

   DATABASE_URL="<production pooler string>" npm run setup
   

   A DATABASE_URL given on the command line wins over .env.local. The first line printed should be Database: aws-0-<region>.pooler.supabase.com:6543/postgres (remote). Re-running is safe: it only applies migrations the database hasn't had yet and reloads the questions, keeping students and submissions.

3. Set two environment variables in Vercel (Project → Settings → Environment Variables):

   Name	Value
   ADMIN_PASSWORD	the teacher's password for /admin
   DATABASE_URL	the production transaction pooler string (port 6543)

4. Deploy: import the GitHub repo in Vercel (the defaults are fine), or run vercel --prod. If a page fails with "DATABASE_URL is not set", the variable is missing: add it and redeploy.

• Clearing test data in production: DATABASE_URL="<production pooler string>" npm run db:reset -- --yes-wipe-remote.
• Preview deployments use the same DATABASE_URL as production unless you scope it: give the Production environment the production string and Preview the development one.
• Keep the production string out of .env.local. Anything there is used by npm run dev, npm run setup and npm run db:reset on your computer.
• The Before the session steps are for a laptop. On Vercel, steps 4–6 still apply.

This is the beginning of the README. Read the rest at the original. Read the full README ↗