MUN Hub

MUN Hub is a curated marketplace for Model United Nations conferences in India. Delegates discover a MUN, register and pay in one place. Organizers apply to host, set their conference up, get it verified and go live, then run registrations, communications, check-in and results. MUN Hub staff review applications and content before anything is published, and handle support and payment exceptions.

Product specs live in docs/prd/ (start with MUN_Marketplace_PRD.md). Design and implementation notes live in docs/superpowers/, and operations docs in docs/operations/.

Architecture

 browser ──► munhub.in / www           Vercel (web/ build)
         ──► app. publish. admin.      Cloudflare Worker "munhub-web"   (web/, static SPA)
             *.munhub.in (MUN pages)
                    │  fetch, credentials: include
                    ▼
             api.munhub.in              Cloudflare Worker "munhub-api"   (server/, Hono)
                    │  + cron every 5 min → lib/jobs
                    ▼
             Hyperdrive "munhub-db" ──► Neon Postgres

Directory	What it is
web/	Vite + React 19 + React Router v7 (data router) + TanStack Query SPA. One build serves every host; web/src/lib/host-routing.ts maps each subdomain to its area (delegate, organizer, admin, per-MUN page). Tailwind v4, shadcn-style components in web/src/components/ui.
server/	Hono API under /api/v1 (plus /webhooks). src/worker.ts is the Cloudflare entry (fetch + scheduled), src/index.ts the Node entry for local development.
lib/	Framework-agnostic domain logic shared by the API and tests: Drizzle schema and client (lib/db), actions, lifecycle and verification state machines, auth, payments, notifications, background jobs.
drizzle/	SQL migrations generated by drizzle-kit.
E2E/	Playwright end-to-end suite (see E2E/README.md).
docs/	PRDs, design specs, plans, operations runbooks.

Some ground rules for code in server/ and lib/:

• On Workers, custom env vars and secrets are never in process.env. Read them with getRuntimeEnv('NAME') from lib/runtime-env.ts.
• Don't cache database clients or other I/O objects at module scope. Workers ties them to one request; lib/db/client.ts handles scoping.
• Identity comes from the session only. Never trust a client-supplied user id or role.
• Registration capacity, payment and confirmation run in row-locked transactions. There are no refunds in the product; payment problems become payment exceptions for an admin to resolve.

Sign-in

• Delegates sign up and sign in with email and password (POST /api/v1/auth/users, POST /api/v1/auth/session). They reset a forgotten password by emailed link.
• Organizers have no password. They request a 6-digit code by email (POST /api/v1/auth/organizers/code) and exchange it for a session (POST /api/v1/auth/organizers/session). The first code for a new email creates the organizer account.
• Staff (admin/operations) sign in with a password on admin.munhub.in.

Sessions are an HTTP-only cookie. In production its domain is .munhub.in, so one sign-in covers every subdomain.

Local setup

Prerequisites: Node.js 22+, npm, Docker, and Google Chrome (for E2E).

# 1. Dependencies (three separate installs)
npm ci
npm --prefix server ci
npm --prefix web ci

# 2. Database: Postgres 16 in Docker, then schema and demo data
npm run db:up
npm run db:migrate:local
npm run db:seed:local

# 3. API config: local values only
cp .env.example server/.env
#   then set PAYMENT_FIELD_KEY (the file shows how to generate one)

# 4. Run (two shells)
cd server && npx tsx --env-file=.env src/index.ts     # API on http://localhost:3001
cd web && npx vite                                     # web on http://localhost:5174

The web app calls http://localhost:3001/api/v1 unless VITE_API_URL is set. Seeded demo accounts share the password munhub-demo: [email protected], [email protected], [email protected] (owns Oxford MUN 2027). Organizers sign in with an email code. Locally the email is printed to the API console.

The repo-root .env on team machines points at production Neon. Use the :local database scripts, which force the Docker database. Never copy .env into server/.env or server/.dev.vars. Details: docs/operations/ENVIRONMENTS.md.

To run the API in the Workers runtime instead of Node, including the cron jobs, see "Run the Worker locally" in docs/operations/RUNBOOK.md.

Scripts

Run from the repo root.

Script	What it does
npm run typecheck	TypeScript for lib + server integration tests, E2E, server and web
npm run lint	oxlint for web (with its config) and for lib, server and E2E
npm run check	typecheck + lint
npm test	Vitest (unit + API integration tests) against the local database
npm run test:ci	Same, one file at a time (use this when Postgres runs out of connections)
npm run test:e2e	Playwright suite (test:e2e:ui, test:e2e:report too)
npm run db:up	Start Docker Postgres
npm run db:migrate:local / db:seed:local	Migrate / seed the Docker database, whatever .env says
npm run db:generate	Generate a migration from lib/db/schema.ts
npm run db:migrate / db:seed / db:push / db:studio	Use .env's DATABASE_URL. Check what it points at first.

In web/: npx vite (dev), npx vite build, npx tsc -b --noEmit, npx oxlint. In server/: npm run typecheck, npx wrangler dev.

Testing

• Unit and integration tests (lib/**/*.test.ts, server/**/*.test.ts) use Vitest and a real Postgres. vitest.setup.ts loads the committed .env.test, which points at the Docker database, so tests never touch .env. Run a subset with npx vitest run <files> --no-file-parallelism.
• End-to-end tests drive the real SPA and API with Playwright against the local database. The suite starts its own servers on ports 3101/5175 and refuses to run against a non-local database. The API reads server/.env. See E2E/README.md.
• CI (.github/workflows/ci.yml) runs typecheck, lint, the web build, a Worker bundle and the Vitest suite on every push and pull request to main. The E2E suite runs nightly and on manual dispatch.

Deployment

Production is deployed manually through the Deploy (production) GitHub Actions workflow (.github/workflows/deploy.yml) after approval. It runs migrations on Neon and then wrangler deploy for munhub-api and munhub-web. munhub.in/www deploy through Vercel's Git integration. Configuration, secrets, backups, monitoring, rollback and the incident checklist are in docs/operations/RUNBOOK.md. Staging is described in docs/operations/ENVIRONMENTS.md.