# chandrakantamandal/hackathon-project-hub architecture

> Architecture diagram of the GitHub repository chandrakantamandal/hackathon-project-hub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chandrakantamandal/hackathon-project-hub
- Repository: https://github.com/chandrakantamandal/hackathon-project-hub

## Overview

#### 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: [`server/index.js`](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/index.js) (API entry & middleware), [`client/src/App.jsx`](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/client/src/App.jsx) (App routes & UI), [`server/models/Submission.js`](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/models/Submission.js) (Submission model), [`server/controller/tasks.js`](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/controller/tasks.js) (Teams, projects & tasks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_spa_entry["SPA entry<br/>Vite React<br/>[main.jsx]"]
  node_app_routes["App routes &amp; UI<br/>React app<br/>[App.jsx]"]
  node_client_store["App state<br/>Zustand store<br/>[useAppStore.js]"]
  node_api_client["REST client<br/>Axios<br/>[api.js]"]
  node_showcase_page["Public showcase<br/>React page<br/>[ShowcasePage.jsx]"]
end

subgraph group_server["Express API"]
  node_api_server["API entry &amp; middleware<br/>Express<br/>[index.js]"]
  node_participant_auth["Participant auth<br/>routes/controller<br/>[auth.js]"]
  node_auth_routes["Auth routes<br/>Express router<br/>[auth.js]"]
  node_participant_auth_guard["Participant auth guard<br/>middleware<br/>[auth.js]"]
  node_collaboration["Teams, projects &amp; tasks<br/>domain controllers<br/>[tasks.js]"]
  node_submissions["Submission &amp; ranking<br/>controller<br/>[submissions.js]"]
  node_showcase["Showcase interactions<br/>controller<br/>[showcase.js]"]
  node_judge_routes["Judge portal routes<br/>Express router<br/>[judge.js]"]
  node_judge_evaluation["Judge evaluation<br/>controller<br/>[judge.js]"]
  node_judge_auth_guard["Judge auth guard<br/>middleware<br/>[judgeAuth.js]"]
end

subgraph group_data["Persistence &amp; external"]
  node_domain_models[("Teams &amp; projects<br/>Mongoose models<br/>[Team.js]")]
  node_submission_model[("Submission model<br/>Mongoose model<br/>[Submission.js]")]
  node_mongodb[("MongoDB<br/>database")]
  node_mailtrap["Mailtrap<br/>email service<br/>[emails.js]"]
end

node_spa_entry -->|"mounts"| node_app_routes
node_app_routes -->|"reads/writes state"| node_client_store
node_app_routes -->|"calls API"| node_api_client
node_app_routes -->|"renders public route"| node_showcase_page
node_api_client -->|"REST /api"| node_api_server
node_api_server -->|"routes auth"| node_auth_routes
node_auth_routes -->|"delegates"| node_participant_auth
node_participant_auth -->|"sends OTP/reset email"| node_mailtrap
node_api_server -->|"protects participant APIs"| node_participant_auth_guard
node_participant_auth_guard -->|"authorizes"| node_collaboration
node_collaboration -->|"manages"| node_domain_models
node_domain_models -->|"persists to"| node_mongodb
node_collaboration -->|"projects submitted as"| node_submissions
node_api_server -->|"routes public endpoints"| node_showcase
node_showcase -->|"reads interactions"| node_submission_model
node_showcase_page -->|"discovery requests"| node_showcase
node_submissions -->|"creates/ranks"| node_submission_model
node_submission_model -->|"persists to"| node_mongodb
node_api_server -->|"routes judge API"| node_judge_routes
node_judge_routes -->|"protects"| node_judge_auth_guard
node_judge_auth_guard -->|"authorizes"| node_judge_evaluation
node_judge_evaluation -->|"scores and badges"| node_submission_model

click node_spa_entry "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/client/src/main.jsx"
click node_app_routes "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/client/src/App.jsx"
click node_client_store "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/client/src/store/useAppStore.js"
click node_api_client "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/client/src/utils/api.js"
click node_showcase_page "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/client/src/pages/ShowcasePage.jsx"
click node_api_server "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/index.js"
click node_participant_auth "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/controller/auth.js"
click node_auth_routes "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/routes/auth.js"
click node_participant_auth_guard "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/middleware/auth.js"
click node_collaboration "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/controller/tasks.js"
click node_submissions "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/controller/submissions.js"
click node_showcase "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/controller/showcase.js"
click node_judge_routes "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/routes/judge.js"
click node_judge_evaluation "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/controller/judge.js"
click node_judge_auth_guard "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/middleware/judgeAuth.js"
click node_domain_models "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/models/Team.js"
click node_submission_model "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/models/Submission.js"
click node_mailtrap "https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/mailtrap/emails.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spa_entry,node_app_routes,node_client_store,node_api_client,node_showcase_page toneBlue
class node_api_server,node_participant_auth,node_auth_routes,node_participant_auth_guard,node_collaboration,node_submissions,node_showcase,node_judge_routes,node_judge_evaluation,node_judge_auth_guard toneAmber
class node_domain_models,node_submission_model,node_mongodb,node_mailtrap toneMint
```

## Components

### React client

- [SPA entry](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/client/src/main.jsx): Vite React · `client/src/main.jsx`
- [App routes & UI](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/client/src/App.jsx): React app · Separates public, participant, and judge experiences. · `client/src/App.jsx`
- [App state](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/client/src/store/useAppStore.js): Zustand store · Persists shared client state. · `client/src/store/useAppStore.js`
- [REST client](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/client/src/utils/api.js): Axios · Uses VITE_API_URL for API calls. · `client/src/utils/api.js`
- [Public showcase](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/client/src/pages/ShowcasePage.jsx): React page · `client/src/pages/ShowcasePage.jsx`

### Express API

- [API entry & middleware](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/index.js): Express · Applies security, cookies, CORS, compression, and rate limits under /api. · `server/index.js`
- [Participant auth](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/controller/auth.js): routes/controller · Registration, OTP verification, login, recovery, and cookie JWT lifecycle. · `server/controller/auth.js`
- [Auth routes](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/routes/auth.js): Express router · `server/routes/auth.js`
- [Participant auth guard](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/middleware/auth.js): middleware · Protects participant workflows. · `server/middleware/auth.js`
- [Teams, projects & tasks](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/controller/tasks.js): domain controllers · Task status drives project progress. · `server/controller/tasks.js`
- [Submission & ranking](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/controller/submissions.js): controller · Turns projects into judgeable submissions and ranks final scores. · `server/controller/submissions.js`
- [Showcase interactions](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/controller/showcase.js): controller · Exposes public projects, views, likes, and comments. · `server/controller/showcase.js`
- [Judge portal routes](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/routes/judge.js): Express router · Separate registration-code-gated judge API. · `server/routes/judge.js`
- [Judge evaluation](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/controller/judge.js): controller · Searches submissions, applies weighted scores, and manages badges. · `server/controller/judge.js`
- [Judge auth guard](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/middleware/judgeAuth.js): middleware · Uses judge localStorage JWTs. · `server/middleware/judgeAuth.js`

### Persistence & external

- [Teams & projects](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/models/Team.js): Mongoose models · Membership and project records. · `server/models/Team.js`
- [Submission model](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/models/Submission.js): Mongoose model · `server/models/Submission.js`
- **MongoDB**: database · Stores users, teams, projects, tasks, and submissions.
- [Mailtrap](https://github.com/chandrakantamandal/hackathon-project-hub/blob/main/server/mailtrap/emails.js): email service · Delivers verification and reset messages. · `server/mailtrap/emails.js`

## Connections

- 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