How chandrakantamandal/hackathon-project-hub works
Purpose and Entry Points
Hackathon Project Hub is a full-stack platform for participant collaboration, project tracking, public showcasing, and judge scoring. The React SPA starts at client/src/main.jsx and composes routes/UI from client/src/App.jsx. The Express REST API starts at server/index.js, serving endpoints under /api.
Client Application and State
The Vite/React client separates public, participant, and judge experiences. Participant workspace pages include dashboard, team, project, and profile views; public discovery is the showcase; judges use a distinct login/dashboard flow. Shared client state is persisted through Zustand, while Axios provides the API boundary.
• client/src/App.jsx
• client/src/store/useAppStore.js
• client/src/utils/api.js
Participant Identity and Account Lifecycle
Participant authentication supports registration, email OTP verification, login/logout, auth checks, and password recovery. The backend uses JWTs in HTTP-only cookies; temporary registrations and verification processing are managed by the auth controller, with Mailtrap used for outbound verification/reset mail.
• server/routes/auth.js
• server/controller/auth.js
• server/mailtrap/emails.js
Collaboration Domain: Teams, Projects, and Tasks
MongoDB/Mongoose stores users, teams, projects, and tasks. Authenticated participants create or join teams, manage projects, and track tasks. Task status drives project-progress behavior, forming the core collaboration flow from team membership to deliverable completion.
• server/models/Team.js
• server/models/Project.js
• server/controller/tasks.js
Submission, Public Showcase, and Leaderboard
A participant turns a project into a judging submission with repository/demo metadata. Public showcase endpoints expose projects, views, likes, and comments; submissions support ranking by final score for the leaderboard. Client pages render project detail and public discovery independently from protected dashboard workflows.
• server/controller/submissions.js
• server/controller/showcase.js
• client/src/pages/ShowcasePage.jsx
Judge Portal and Evaluation Boundary
Judges are a separate principal type with registration-code-gated registration and localStorage JWT handling. Judge-only middleware protects submission browsing, search, weighted multi-criterion scoring, and badge assignment/removal. The judge dashboard is intentionally distinct from participant project management.
• server/routes/judge.js
• server/controller/judge.js
• server/middleware/judgeAuth.js
API, Persistence, and Operational Boundaries
Express routers delegate to controllers, which enforce authorization/validation and persist through Mongoose models to MongoDB. The server applies CORS, Helmet, compression, cookie parsing, and rate limiting; configuration comes from environment files. External boundaries are MongoDB, Mailtrap, and client-to-server REST calls configured with VITE_API_URL.
• server/index.js
• server/middleware/auth.js
• server/models/Submission.js
Main entry points: index.js API entry & middleware · App.jsx App routes & UI · Submission.js Submission model · tasks.js Teams, projects & tasks
Components 19
React client
- SPA entry
client/src/main.jsx - App routes & UI · Separates public, participant, and judge experiences.
client/src/App.jsx - App state · Persists shared client state.
client/src/store/useAppStore.js - REST client · Uses VITE_API_URL for API calls.
client/src/utils/api.js - Public showcase
client/src/pages/ShowcasePage.jsx
Express API
- API entry & middleware · Applies security, cookies, CORS, compression, and rate limits under /api.
server/index.js - Participant auth · Registration, OTP verification, login, recovery, and cookie JWT lifecycle.
server/controller/auth.js - Auth routes
server/routes/auth.js - Participant auth guard · Protects participant workflows.
server/middleware/auth.js - Teams, projects & tasks · Task status drives project progress.
server/controller/tasks.js - Submission & ranking · Turns projects into judgeable submissions and ranks final scores.
server/controller/submissions.js - Showcase interactions · Exposes public projects, views, likes, and comments.
server/controller/showcase.js - Judge portal routes · Separate registration-code-gated judge API.
server/routes/judge.js - Judge evaluation · Searches submissions, applies weighted scores, and manages badges.
server/controller/judge.js - Judge auth guard · Uses judge localStorage JWTs.
server/middleware/judgeAuth.js
Persistence & external
- Teams & projects · Membership and project records.
server/models/Team.js - Submission model
server/models/Submission.js - MongoDB · Stores users, teams, projects, tasks, and submissions.
- Mailtrap · Delivers verification and reset messages.
server/mailtrap/emails.js
Connections 22
- SPA entry → App routes & UI: mounts
- App routes & UI → App state: reads/writes state
- App routes & UI → REST client: calls API
- App routes & UI → Public showcase: renders public route
- REST client → API entry & middleware: REST /api
- API entry & middleware → Auth routes: routes auth
- Auth routes → Participant auth: delegates
- Participant auth → Mailtrap: sends OTP/reset email
- API entry & middleware → Participant auth guard: protects participant APIs
- Participant auth guard → Teams, projects & tasks: authorizes
- Teams, projects & tasks → Teams & projects: manages
- Teams & projects → MongoDB: persists to
- Teams, projects & tasks → Submission & ranking: projects submitted as
- API entry & middleware → Showcase interactions: routes public endpoints
- Showcase interactions → Submission model: reads interactions
- Public showcase → Showcase interactions: discovery requests
- Submission & ranking → Submission model: creates/ranks
- Submission model → MongoDB: persists to
- API entry & middleware → Judge portal routes: routes judge API
- Judge portal routes → Judge auth guard: protects
- Judge auth guard → Judge evaluation: authorizes
- Judge evaluation → Submission model: scores and badges