Skip to content
xByteAPublic

Repository files navigation

PUA ICPC Community

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.

Requirements

  • Node.js 20 or later
  • MongoDB 6 or later, local or hosted

Start locally

Open two terminals in VS Code, with the project folder as the workspace.

  1. In Terminal 1, configure and start the API:

    cd .\Backend
    if (!(Test-Path .env)) { Copy-Item .env.example .env }

    Open Backend/.env and replace JWT_SECRET with a random value of at least 32 characters. Ensure MongoDB is running and MONGODB_URI points to it, then run:

    npm install
    npm run dev

    The API listens on http://localhost:5000. Check http://localhost:5000/api/health.

  2. In Terminal 2, start the frontend:

    cd .\Frontend
    if (!(Test-Path .env)) { Copy-Item .env.example .env }

    Set VITE_GOOGLE_CLIENT_ID in Frontend/.env to the Google Web OAuth client ID, then start Vite:

    npm install
    npm run dev

    Open http://localhost:5173. Set VITE_API_URL in Frontend/.env if the API is hosted elsewhere.

  3. 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.

Environment variables

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

Google sign-in setup

  1. 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.
  2. Add the exact frontend origins under Authorized JavaScript origins, including http://localhost:5173 for local development and https://icpc-pua.vercel.app for production. Google Identity Services uses its popup flow here, so no client secret or redirect URI is needed.
  3. Set the same web client ID in Backend/.env as GOOGLE_CLIENT_ID and in Frontend/.env as VITE_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.
  4. For deployment, configure GOOGLE_CLIENT_ID in the backend's Vercel environment and VITE_GOOGLE_CLIENT_ID in 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.

API overview

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.

Tests and production build

cd Backend
npm test
cd Frontend
npm run build

Releases

Packages

Contributors

Languages