The Hack Western application platform is a comprehensive web-based system for managing all aspects of a university hackathon event, from initial registration through application review to live event coordination. The platform serves three primary user roles—applicants, organizers, and event attendees—across distinct temporal phases: pre-event (applications and review), event day (live portal and scavenger hunt), and post-event.
This overview provides a high-level architectural introduction to the codebase. For specific subsystem details, see: Scavenger Hunt System, Application Submission System, Live Event Portal, Review and Administration System, Authentication System, Homepage and Marketing, Database Architecture, API Layer and tRPC.
Sources: src/pages/index.tsx1-65 package.json1-130
The platform is built as a monolithic Next.js application with a type-safe tRPC API layer communicating with a PostgreSQL database. All business logic executes server-side through tRPC routers, with client components using React Query for data fetching and caching.
Sources: src/pages/index.tsx1-65 src/server/api/routers/application.ts1-395 src/server/api/routers/scavenger-hunt.ts1-769 src/server/db/schema.ts1-500
The platform is built with the following primary technologies. See page 1.1 for a detailed breakdown.
| Category | Key Technologies |
|---|---|
| Framework | Next.js 15.5.9, React 19, TypeScript 5.8 |
| API | tRPC (end-to-end type-safe), Zod (validation) |
| Database | PostgreSQL, Drizzle ORM 0.41, drizzle-kit |
| Auth | NextAuth 4.24, @auth/drizzle-adapter, bcrypt |
| UI | Tailwind CSS, Radix UI primitives, Framer Motion, Lucide React |
| Forms | react-hook-form, @hookform/resolvers |
| External | Resend (email), AWS S3 / R2 (file storage), Google APIs (Sheets/Calendar) |
| Testing | Vitest, @electric-sql/pglite (in-process PG for tests) |
Sources: package.json21-85 package.json87-114
The system implements three distinct user types through the userType enum in the database schema. Access is enforced in src/server/api/trpc.ts via procedure-level middleware.
User Role to tRPC Procedure Mapping
publicProcedure: No authentication required (e.g., viewing scavenger hunt item catalogue)protectedProcedure: Requires a valid NextAuth session (e.g., viewing own application, redeeming rewards)protectedOrganizerProcedure: Requires user.type === "organizer" (e.g., scanning QR codes, reviewing applications)Server-side page-level redirects are handled by utility functions in src/utils/redirect.ts: authRedirectOrganizer, authRedirectHacker, hackerLoginRedirect, notVerifiedRedirect, and isVerifiedRedirect.
Sources: src/utils/redirect.ts1-201 src/server/api/root.ts1-35
The platform is organized into several major subsystems, each with dedicated routers, database tables, and UI components:
| Subsystem | Database Tables | tRPC Router | Primary Pages | Importance |
|---|---|---|---|---|
| Scavenger Hunt | scavengerHuntItemsscavengerHuntScansscavengerHuntRewardsscavengerHuntRedemptions | scavengerHuntRouter | /live?tab=home/scan/redeem | 72.86 (highest) |
| Applications | applications | applicationRouter | /apply?step=* | Critical |
| Reviews | reviews | reviewRouter | /review | Critical |
| Authentication | usersaccountssessionsverificationTokens | NextAuth API routes | /login/register/verify | Essential |
| Live Event | (content-based) | N/A | /live?tab=schedule/map/menu | Important |
| Promotional | N/A | N/A | / (homepage) | Public |
Scavenger Hunt System (#2): A gamification platform where attendees scan QR codes at activities, meals, and workshops to earn points, which they can redeem for prizes. This is the highest-priority system (importance: 72.86) and dominates the live event experience.
Application Submission System (#3): A 9-step form system (character, basics, info, application, links, agreements, canvas, optional, review) with auto-save functionality and validation. Applications progress through a state machine: IN_PROGRESS → PENDING_REVIEW → IN_REVIEW → ACCEPTED/REJECTED/WAITLISTED.
Review System (#5): Organizers rate applications on three dimensions (originality, technicality, passion) with a requirement of REQUIRED_REVIEWS=2 per application. The system includes assignment algorithms and completion tracking.
Live Event Portal (#4): A tab-based dashboard providing schedules, maps, menus, sponsor information, and serving as the primary interface for the scavenger hunt during the event.
Authentication System (#6): NextAuth-based authentication supporting credential login, OAuth providers (Google, GitHub, Discord), email verification, and password reset flows.
Sources: src/server/db/schema.ts1-500 src/server/api/routers/scavenger-hunt.ts1-769 src/server/api/routers/application.ts1-395 Diagram 1 from high-level analysis
The platform operates across three distinct temporal phases with different active subsystems:
Duration: September - October
Active Systems: Authentication, Application Portal, Auto-Save
User Actions: Register account → Complete 9-step application → Submit for review
Key components active:
applicationRouter.save() - Saves partial application dataapplicationRouter.submit() - Validates and submits complete applicationDuration: Mid-October - Early November
Active Systems: Review Portal, Admin Dashboard
User Actions (Organizers): Review applications → Rate on 3 dimensions → Manage acceptance status
Key components active:
reviewRouter.save() - Persists ratings and commentsreviewRouter.getNextId() - Assignment algorithmapplicationRouter.bulkUpdateStatusByEmails() - Batch status updatesDuration: November 21-23 (3 days)
Active Systems: Live Portal, Scavenger Hunt, Scanning, Redemption
User Actions: Scan activity QR codes → Earn points → Redeem rewards → View schedules/maps
Key components active:
scavengerHuntRouter.scan() - Awards points for scansscavengerHuntRouter.redeem() - Processes reward redemptionsSources: src/pages/apply.tsx src/pages/review.tsx src/pages/live.tsx Diagram 6 from high-level analysis
All client-server communication flows through the tRPC API layer, which enforces type safety, validation, and authentication:
Auto-Save Pattern: Form changes are debounced (1000ms) through useAutoSave, preventing excessive API calls while ensuring data persistence. Implementation: src/hooks/use-auto-save.ts
Validation Pattern: Zod schemas validate data at two levels:
applicationSaveSchema) for auto-save operationsapplicationSubmitSchema) for final submissionTransaction Pattern: Critical operations (scanning, redemption) use database transactions to ensure atomicity:
Point Management: The scavenger hunt maintains two point fields on the users table:
scavengerHuntEarned: Total points earned (never decreases)scavengerHuntBalance: Available points for redemption (decreases on redemption)Sources: src/server/api/routers/application.ts205-259 src/server/api/routers/scavenger-hunt.ts208-242 src/hooks/use-auto-save.ts Diagram 3 from high-level analysis
Key npm scripts defined in package.json7-19:
| Script | Purpose |
|---|---|
dev | Start dev server with Turbopack |
db:start | Start local PostgreSQL via start-database.sh |
db:generate / db:migrate | Drizzle schema migration workflow |
db:seed | Seed database with test data |
db:studio | Launch Drizzle Studio |
test | Run Vitest test suite |
Environment variables are type-validated at startup using @t3-oss/env-nextjs with Zod. Required groups include database URLs, NextAuth secrets, OAuth provider credentials, and external service keys (Resend, AWS/R2, Google APIs).
See page 1.3 for step-by-step setup instructions, page 11.2 for environment variable reference, and page 11.4 for testing strategy.
Sources: package.json7-19
The Hack Western platform is a modern, type-safe hackathon management system built on Next.js 15, tRPC, and PostgreSQL. It orchestrates three distinct temporal phases (application, review, live event) through a modular architecture with clear separation between public, authenticated, and organizer-only functionality. The scavenger hunt system serves as the centerpiece of the live event experience, while the application and review systems handle the pre-event logistics. All subsystems are documented in detail in subsequent sections of this wiki.
Sources: All files and diagrams referenced throughout this document
Refresh this wiki