Hatch

Open-source hackathon management system.

Hatch provides everything you need to run a hackathon: participant registration, team formation, admin management, and a dramatic countdown timer for the big screen.

Architecture

Hatch is a Turborepo monorepo with two independently deployable Next.js apps sharing a Supabase backend:

App	Port	Description
apps/participant	3000	Participant portal — registration, team create/join, status
apps/admin	3001	Admin dashboard — manage participants, teams, settings, timer

Shared packages:

Package	Description
@hatch/supabase	Database types, client helpers, SQL migrations, query functions
@hatch/types	Shared TypeScript types and Zod validation schemas
@hatch/ui	Shared UI components (Button, Card, Input, Badge, CountdownDisplay)
@hatch/typescript-config	Shared tsconfig presets
@hatch/eslint-config	Shared ESLint configuration

Tech Stack

• Frontend: Next.js 15 (App Router) + Tailwind CSS v4
• Backend: Supabase (PostgreSQL + Auth + Realtime)
• Auth: Email/password + OAuth (Google, GitHub)
• Animations: GSAP for countdown timer
• Monorepo: Turborepo + pnpm workspaces
• Deployment: Vercel (two separate projects)

Getting Started

Prerequisites

• Node.js 20+
• pnpm 10+
• A Supabase project (or local Supabase CLI)

Setup

1. Clone and install:

git clone https://github.com/Open-Document-Alliance/Hatch.git
cd Hatch
pnpm install

2. Configure environment variables:

Copy .env.example to .env.local in each app:

cp .env.example apps/participant/.env.local
cp .env.example apps/admin/.env.local

Edit each .env.local with your Supabase project URL and anon key.

3. Run database migrations:

In the Supabase SQL Editor, run the migration files in order:

packages/supabase/migrations/00001_create_profiles.sql
packages/supabase/migrations/00002_create_teams.sql
packages/supabase/migrations/00003_create_timers.sql
packages/supabase/migrations/00004_create_settings.sql
packages/supabase/migrations/00005_create_rls_policies.sql
packages/supabase/migrations/00006_seed.sql

4. Create your first admin:

After registering via the participant portal, promote yourself to admin:

UPDATE profiles SET role = 'admin' WHERE email = 'your@email.com';

5. Start development:

pnpm dev

This starts both apps concurrently:

• Participant portal: http://localhost:3000
• Admin dashboard: http://localhost:3001

Features

Participant Portal

• Registration — Email/password or OAuth (Google/GitHub)
• Team creation — Create a team and get a 6-character join code
• Team joining — Enter a join code to join an existing team
• Team management — View members, leave team
• Portal gating — Automatically shows "closed" page when admins disable registration

Admin Dashboard

• Participants — View all registrations, toggle check-in status
• Teams — View all teams with members, mark as complete
• Check-in — Focused search + check-in view for event day
• Settings — Toggle portal on/off, set time windows, configure capacity limits (max signups, max teams, team size range)
• Countdown Timer — Create timers, start/reset, cast to big screen

Countdown Timer

• Full-screen castable display at /timer/[id]/display (no auth required)
• Synced across screens via Supabase Realtime
• GSAP animations that intensify as the deadline approaches:
  • Last 1 hour — Subtle glow pulse
  • Last 10 minutes — Warm orange digits
  • Last 1 minute — Red pulse, border flash
  • Last 10 seconds — Dramatic scale bounce, screen flash

Deployment

Both apps deploy independently to Vercel:

1. Create two Vercel projects, each pointing to the repo
2. Set the Root Directory to apps/participant or apps/admin
3. Add the Supabase environment variables
4. Deploy

Database Schema

• profiles — User profiles (extends Supabase Auth), includes team assignment and check-in status
• teams — Teams with auto-generated 6-character join codes
• timers — Countdown timers with deadline and start time
• hackathon_settings — Singleton config for portal toggle, capacity limits, and time windows

All business rules are enforced at the database level via RLS policies and PostgreSQL functions.

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE.