A responsive events and training platform for the PUA ICPC community. The project is split into a React/Vite frontend and an Express/Mongoose REST API.
The Stitch reference requires a Google sign-in and could not be viewed from this workspace. The first implementation follows the requested visual direction (warm cream, cyan/purple/yellow/pink accents, bold type, black outlines and simple shadows); exported reference images can be used to refine it.
- Node.js 20 or later
- MongoDB 6 or later, local or hosted
Open two terminals in VS Code, with the project folder as the workspace.
-
In Terminal 1, configure and start the API:
cd .\Backend if (!(Test-Path .env)) { Copy-Item .env.example .env }
Open
Backend/.envand replaceJWT_SECRETwith a random value of at least 32 characters. Ensure MongoDB is running andMONGODB_URIpoints to it, then run:npm install npm run dev
The API listens on
http://localhost:5000. Checkhttp://localhost:5000/api/health. -
In Terminal 2, start the frontend:
cd .\Frontend if (!(Test-Path .env)) { Copy-Item .env.example .env }
Set
VITE_GOOGLE_CLIENT_IDinFrontend/.envto the Google Web OAuth client ID, then start Vite:npm install npm run dev
Open
http://localhost:5173. SetVITE_API_URLinFrontend/.envif the API is hosted elsewhere. -
Create a user account in the frontend, then grant it admin access from
Backend:npm run make-admin -- user@example.com
Sign out and back in to refresh the account role. Admins can create and publish events, set an optional registration deadline and attendance points, generate or replace an event QR code, review attendance, and delete events after typing the exact event name. Check-in opens at the event start and closes at the event end. Deletion archives the event and disables its QR while retaining attendance and awarded-points history.
| Variable | Application | Description |
|---|---|---|
PORT |
Backend | API port (default 5000) |
MONGODB_URI |
Backend | MongoDB connection URI |
JWT_SECRET |
Backend | Secret used to sign seven-day bearer tokens; at least 32 characters |
CLIENT_ORIGIN |
Backend | Allowed browser origin (default http://localhost:5173) |
GOOGLE_CLIENT_ID |
Backend | Google OAuth web client ID used to verify GIS ID tokens |
VITE_API_URL |
Frontend | API base URL (default http://localhost:5000/api) |
VITE_GOOGLE_CLIENT_ID |
Frontend | Public Google OAuth web client ID used by Google Identity Services |
- In Google Cloud Console, create or select a project, configure the OAuth consent screen for an External audience, and create an OAuth client ID with application type Web application. Publish the consent screen to production; Google limits apps in testing to configured test users.
- Add the exact frontend origins under Authorized JavaScript origins, including
http://localhost:5173for local development andhttps://icpc-pua.vercel.appfor production. Google Identity Services uses its popup flow here, so no client secret or redirect URI is needed. - Set the same web client ID in
Backend/.envasGOOGLE_CLIENT_IDand inFrontend/.envasVITE_GOOGLE_CLIENT_ID. The client ID is public and is safe to expose to the frontend; do not add a Google client secret to either app. - For deployment, configure
GOOGLE_CLIENT_IDin the backend's Vercel environment andVITE_GOOGLE_CLIENT_IDin the frontend's Vercel environment, then redeploy both projects. These values must match.
The browser sends only Google's ID token to POST /api/auth/google; the backend verifies the token signature and audience and requires a verified email before linking or creating an account. No university-email or hosted-domain restriction is applied. New Google accounts use the existing user role (the application's student role), start without a password, and continue through the username onboarding flow. Existing accounts keep their password and role when a verified Google identity is linked.
All routes are prefixed by /api; protected routes use Authorization: Bearer <token>.
| Method | Route | Access | Purpose |
|---|---|---|---|
POST |
/auth/register |
Public | Create a user account |
POST |
/auth/login |
Public | Sign in |
POST |
/auth/google |
Public | Verify a Google ID token, link/create the account, and sign in |
GET |
/auth/me |
User | Get the current account |
PUT |
/auth/student-id |
User | Set a missing student ID once |
PUT |
/auth/password |
User | Change password after verifying the current password |
GET |
/events |
Public | List published upcoming events |
GET |
/events?status=past&q=...&category=... |
Public | Search/filter published past events |
GET |
/events/:id-or-slug |
Public | Get a published event |
POST |
/events/:id/registrations |
User | Register; offline registrations get an opaque ticket ID |
DELETE |
/events/:id/registrations |
User | Cancel a future event registration |
GET |
/events/my |
User | List the current user's registrations |
GET |
/events/leaderboard |
Public | Rank members by verified attendance points (top 100) |
GET |
/events/leaderboard/me |
User | Get personal rank, total, and verified attendance history |
GET |
/events/:userId/profile |
Public | View a member's public profile, rank, points, and attendance history |
GET |
/events/:id/check-in?token=... |
User | Verify the event QR and the user's registration; return attendance status |
POST |
/events/:id/check-in |
User | Record attendance once during the configured event window |
GET |
/roadmaps |
Public | List published roadmaps without exposing training cycles |
GET |
/roadmaps/:slug |
Public | View a published roadmap and its learning path topics/resources |
GET |
/roadmaps/:roadmapSlug/progress |
Student | View the signed-in student's solved problems for this roadmap |
PUT |
/roadmaps/:roadmapSlug/progress |
Student | Save or clear a solved state for a problem in one of the roadmap topics |
GET |
/roadmaps/:slug/cycles |
User | List published cycles for the roadmap |
GET |
/roadmaps/:slug/cycles/:cycleId |
User | View a cycle and sessions after verifying it belongs to the roadmap |
POST |
/roadmaps/:slug/cycles/:cycleId/enroll |
Student | Enroll once while registration is open and capacity remains |
GET |
/roadmaps/my |
User | View enrolled cycles and separate session-progress/attendance summaries |
GET |
/admin/roadmaps/:roadmapId/nodes |
Admin | List learning path topics |
POST |
/admin/roadmaps/:roadmapId/nodes |
Admin | Add a learning topic and its resources |
PUT |
/admin/roadmaps/:roadmapId/nodes/:nodeId |
Admin | Edit a topic and dependencies |
DELETE |
/admin/roadmaps/:roadmapId/nodes/:nodeId |
Admin | Delete a topic and safely remove its prerequisite references |
GET |
/admin/events |
Admin | List all events |
POST |
/admin/events |
Admin | Create a draft or published event |
PUT |
/admin/events/:id |
Admin | Edit an event |
POST |
/admin/events/:id/check-in-qr |
Admin | Generate a rotatable, opaque QR code for the published event |
GET |
/admin/events/:id/registrations |
Admin | View event attendees |
Responses use JSON; errors have the shape { "error": { "message": "..." } }. New accounts must provide a unique 4–20 digit student ID; existing accounts without one can set it once in Settings. The academic year shown in Settings is derived from the ID's first four digits. Student IDs are returned only by authenticated account endpoints, not public member profiles or the leaderboard. MongoDB unique indexes prevent duplicate account and event registrations. Each event QR contains a random token; only its SHA-256 hash is stored by the API. Regenerating the QR invalidates the previous code. Check-in opens at the event start and closes at the event end; the admin dashboard does not expose custom check-in window fields. Registration deadlines are optional. Attendance points default to 0. An atomic update records the registered student's attendance and snapshots the points awarded on that registration record; the unique student/event registration is the auditable reward transaction and prevents duplicate awards, including concurrent requests. Later event point changes apply only to future check-ins and do not rewrite historical awards. The leaderboard derives totals only from verified student attendance records and uses dense ranking by total points (equal point totals share a rank); within a tie, display order is attendance count, name, then user ID. Logout clears the stateless JWT from the browser; it expires after seven days.
Learning path topics open their practice set from the topic tree, grouped into Easy, Medium, and Hard. Signed-in students can check problems as solved; each student's progress is stored per roadmap in the database. In the admin topic editor, enter problems one per line as title | difficulty | https://example.com, where difficulty is Easy, Medium, or Hard. URL-only and older title | URL entries remain accepted and default to Medium.
cd Backend
npm testcd Frontend
npm run build