Junction Volunteers · Hackathon edition

A standalone challenge sandbox for improving volunteer recruiting. This is not the live Junction platform. It has fresh Git history, no real applications, no production credentials, and no connection to Junction deployments.

Built with Next.js, React, TypeScript, Clerk, PostgreSQL and Drizzle. The source includes applicant search and profiles, recruiting reservations, team rosters, recruiter assignment, event workspaces, and a registration form builder with opening and closing dates.

Start locally

Requirements: Node.js 22, npm, Docker Compose, and your own Clerk development application. If you already have local PostgreSQL 17 or 18, use a dedicated empty database instead of Docker.

1. Fork or clone this repository, then run:

npm ci
cp .env.example .env.local
docker compose up -d --wait

2. Create your own Clerk application. Enable email verification code sign-in, and copy its development publishable key (pk_test_…) and secret key (sk_test_…) into .env.local. Keep the localhost URL and database settings from the example. Never use Junction's accounts, keys or database.

3. Set up the schema and fictional demo:

npm run db:migrate
npm run demo:setup
npm run dev

4. Open http://localhost:3000/sign-in and sign in using one of these designated Clerk test addresses, using the development verification code 424242:

Account	Email	Access
Demo Admin	junction-volunteers-admin+clerk_test@example.com	Super Admin: all demo workspaces, teams and forms
Demo Recruiter	junction-volunteers-recruiter+clerk_test@example.com	Recruiting access for the demo Event Experience team
Demo Visitor	junction-volunteers-outsider+clerk_test@example.com	No recruiting access; use for permission tests

These accounts are created in your own Clerk development instance. No real mailbox or invitation email is used. If email codes are unavailable, enable that sign-in method in your Clerk settings. Development test codes must never be used as a production authentication mechanism. See Clerk test email documentation.

The seed creates 18 fictional applicants, 3 teams and sample recruiting history. Re-running it preserves previous demo work. The demo admin can create additional event workspaces and publish sample registration forms. New workspaces start empty. All names, contacts and answers used in a demo must be fictional.

docker compose stop stops the database while retaining your demo data. docker compose down -v permanently removes only this Compose project's demo database volume; use it deliberately when resetting your sandbox.

What to build

See CHALLENGE.md for product context, suggested improvements and a submission checklist. Choose a focused improvement and demonstrate the complete flow on desktop and phone.

Tests

npm run typecheck
npm run lint
npm test
npm run build

Without a test database, database integration suites are skipped. To run them, create a separate empty test database and export DATABASE_URL, APP_ENV=test and RUN_IMPORT_INTEGRATION=true, then run migrations and tests. Do not point integration tests at your normal demo database. The GitHub Actions workflow creates disposable PostgreSQL and runs the full backend checks without Clerk secrets.

Browser suites under tests/*.spec.ts use Playwright and a running local app. Most use synthetic API responses. They do not replace testing sign-in and data persistence against your own development services.

Code map

• components/, app/(platform)/: recruiter dashboard and application UI.
• app/api/: server endpoints, imports, exports and access checks.
• lib/recruiting.ts: reservations, ownership, status changes and placements.
• lib/auth.ts, lib/membership.ts, lib/workspaces.ts: sign-in and workspace permissions.
• lib/registration-forms.ts: form publishing and public submissions.
• lib/schema.ts, drizzle/: database schema and migrations.
• scripts/seed-demo.ts, tests/: fictional fixtures and regression tests.

Sandbox boundaries

Use your own development Clerk instance and local/test database. This copy rejects APP_ENV=production, and environment markers prevent using a production-marked database from development or preview. There is no authentication bypass. Do not disable access checks to simplify a demo.

For a hosted demo, use your own isolated preview deployment, preview database, Clerk test keys and correct APP_URL. The database marker and APP_ENV must both be preview. This repository is not connected to Junction's Vercel or Neon projects, and contributions never deploy to the live platform automatically.

Real volunteer photos were replaced by original abstract SVG placeholders. The Junction wordmark identifies the challenge and is not part of any general code licence. Font licences are in public/fonts/. Historical event dates and public website links in the inherited UI are sample context, not current operational instructions. Do not submit test registrations to the live website.

See SECURITY.md for scope and CONTRIBUTING.md for submissions. See LICENSE for permitted use.