Hackathon submission platform built with Next.js & Firebase (IO 2026 live collections + IWD 2026 archive). Optional Buddies networking (
/hackathon/buddies) is separate from the main event name. Originally based on DevfestCompetitionForm.
See docs/IO2026_HACKATHON_SPEC.md for collection names (io2026Hackathon_* / iwd2026Hackathon_*), migration, Firestore rules, and route checklist.
Engineering layout & Cursor: docs/ARCHITECTURE.md · project rules in .cursor/rules/ · skill .cursor/skills/hackathon-clean-architecture/ · AGENTS.md.
Set NEXT_PUBLIC_HACKATHON_DATASET=io2026 in .env.local to use live IO 2026 collections (omit for legacy hackaton*). Match Cloud Functions env vars when you flip the app.
- 🔐 Authentication - Firebase Auth with Email/Password & Google
- 📝 Draft System - Save and resume submissions
- 📸 Multi-Upload - Up to 5 screenshots per project
- 🏆 Winner Selection - Admin panel for selecting top 3
- 🎯 Social Integration - Profile tags and social links
- 💬 Buddies (signed-in) — attendee directory, buddy requests, extended profile chips (
/hackathon/buddies; see spec) - 📷 Event gallery — photos & videos at
/hackathon/photos; multi-upload, rename, moderation, carousel (docs/USER_FLOW.md) - 👥 User Roles - Admin, Moderator, and User roles
- 📱 Responsive - Works on all devices
npm installCreate .env.local:
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
# Optional: io2026 | unset for legacy hackaton* collections
# NEXT_PUBLIC_HACKATHON_DATASET=io2026- Create a Firebase project at Firebase Console
- Enable Authentication (Email/Password + Google)
- Create Firestore database
- Enable Storage
- Update Firestore and Storage rules (see docs/FIRESTORE_RULES.md)
npm run dev- docs/START_HERE.md - Complete beginner's guide
- docs/FEATURES_SIMPLE.md - What the app does
- docs/DEPLOYMENT.md - Complete deployment guide (5 minutes)
- docs/FIREBASE_SETUP.md - Firebase configuration
- docs/CHECKLIST.md - Pre-deployment checklist
- docs/USER_FLOW.md — Customer journeys with diagrams (auth, projects, check-in, vote, event gallery)
- docs/DATA_MODEL.md — Firestore schema (active + archive; event gallery collection)
- docs/FIREBASE_AUTH.md - Authentication implementation
- docs/FIRESTORE_RULES.md - Security rules
- docs/FEATURES.md - Complete feature list
- docs/TROUBLESHOOTING.md - Common issues and fixes
- docs/README.md - Complete documentation index
npm install -g vercel
vercel --prodComplete guide: docs/DEPLOYMENT.md
✅ No custom domain required - Works on .vercel.app
✅ Just 6 environment variables - Simple setup
✅ Firebase Auth - Email & Google sign-in
✅ 5-minute deployment - Get live quickly
DevfestCompetitionForm/
├── app/ # Next.js App Router
│ ├── page.tsx # Home page
│ ├── submit/ # Redirect → hackathon profile (project submission)
│ ├── gallery/ # Public gallery
│ ├── hackathon/ # Hackathon pages (overview, gallery, etc.)
│ └── admin/ # Admin panel
├── .cursor/ # Cursor rules (.mdc) & skills (agent workflows)
├── components/ # React components
│ ├── ui/ # shadcn UI components
│ ├── AuthModal.tsx # Sign-in modal
│ ├── UserButton.tsx # User menu
│ ├── ProtectedRoute.tsx # Route protection
│ └── TagSelector.tsx # Tag selection
├── lib/ # Utilities
│ ├── firebase.ts # Firebase config
│ ├── auth.ts # Auth helpers
│ ├── AuthContext.tsx # Auth context
│ └── validators.ts # Input validation
├── hooks/ # Custom hooks
│ └── useAuth.ts # Auth state hook
├── docs/ # Documentation
└── public/ # Static assets
| Route | Access | Description |
|---|---|---|
/ |
Public | Landing page |
/submit |
Public → redirect | Redirects to /hackathon/my-projects?project=1 (legacy ?edit= preserved) |
/hackathon/my-projects |
Protected | Your project card + draft / final submission form |
/gallery |
Public | View all submissions |
/admin |
Admin | Manage submissions & winners |
/admin/users |
Admin | User role management |
/hackathon |
Public | Hackathon overview |
/hackathon/gallery |
Public | Project gallery |
/hackathon/photos |
Public (+ upload when signed in) | Event gallery — photos & videos carousel |
/admin/photos |
Admin / moderator | Moderate uploads, reorder, rename |
- Framework: Next.js 14.2 (App Router)
- Language: TypeScript 5.6
- Authentication: Firebase Auth
- Database: Firebase Firestore
- Storage: Firebase Storage
- UI: shadcn/ui + Tailwind CSS
- Font: Poppins
- Deployment: Vercel
✅ Firebase Authentication with Email/Password & Google
✅ Role-based access control (Admin, Moderator, User)
✅ Firestore security rules
✅ Storage security rules
✅ Environment variables in .env.local (gitignored)
✅ Protected routes with authentication checks
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open a Pull Request
MIT License - see LICENSE file
- 📖 Check docs/ for complete guides
- 🐛 Open a GitHub issue
- 💬 Join discussions
- Event: DevFest 2025 London
- Date: November 22nd, 2025
- Location: LSE Centre Building (CBG), WC2A 2AE
- Theme: AI Innovation Lab Competition
Built with ❤️ for DevFest 2025 London