# krishagarwal-44/project-desk architecture

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

- Interactive diagram: https://gitdiagram.com/krishagarwal-44/project-desk
- Repository: https://github.com/krishagarwal-44/project-desk

## Overview

1. **Overall shape**
   - This is a two-tier MERN application: an **Express/Node backend** and a **React/Vite frontend**.
   - The product domain is **college project allocation and management**, centered on three roles: **Head**, **Mentor**, and **Student**.

2. **Frontend boundary**
   - The frontend lives under `frontend/Allocation` and is organized by **role-specific pages** plus shared shell components.
   - Shared UI/layout pieces include `Navbar`, `SideMenu`, `AuthContext`, `useAuth`, and `PrivateRoute`, which together suggest centralized auth state and route protection.

3. **Role-based UI subsystems**
   - `pages/Head`, `pages/Mentor`, and `pages/Student` are separate feature areas with their own dashboards and workflows.
   - The Head area includes dashboard cards, document management, interview scheduling, project review, and messaging.
   - The Mentor area focuses on assigned projects, forms, documentation, and messages.
   - The Student area covers project idea submission, bank project selection, checklist completion, documentation, pipeline tracking, and messaging.

4. **Frontend data access layer**
   - The frontend does not appear to call the backend directly from components; instead it uses service modules in `src/services`.
   - There are dedicated service files for `auth`, `common`, `head`, `mentor`, and `student`, which mirrors the backend’s role-based API segmentation.
   - `src/utils/axios.js` is the shared HTTP client boundary for all API traffic.

5. **Backend API boundary**
   - The backend is a conventional Express API in `backend/server.js`, with route modules for `auth`, `common`, `head`, `mentor`, and `student`.
   - Controllers are similarly separated by concern, which indicates a clear API surface per role and shared utility endpoints.
   - `authMiddleware.js` is the main gatekeeper for protected routes and role-aware access control.

6. **Domain model and persistence**
   - MongoDB is the persistence layer, accessed through Mongoose models in `backend/models`.
   - The model set shows the core business objects: `Student`, `Mentor`, `Head`, `ProjectIdea`, `ProjectBank`, `AssignedProject`, `Interview`, `Checklist`, `StudentChecklist`, `Document`, `Message`, and the multi-stage form entities (`Form1`, `Form2`, `Form3`, `StudentForm3`).
   - This indicates the system persists both identity data and the full project lifecycle state.

7. **Project lifecycle flow**
   - The key business flow is: **student submits or selects a project**, **mentor/head reviews it**, **forms and checklist items are completed**, and **progress/interview/document records are updated over time**.
   - `AssignedProject`, `Interview`, and the form/checklist models suggest the app tracks state transitions rather than just storing static records.

8. **Document and file handling**
   - `backend/middleware/upload.js` and the `backend/uploads` directory show that file uploads are stored on the server’s filesystem.
   - The `Document` model likely links uploaded files to users or projects, making file storage a separate artifact from metadata stored in MongoDB.
   - This creates a two-part document boundary: **binary files on disk** and **references/ownership in the database**.

9. **Messaging and announcements**
   - `Message` and the Head message pages indicate an internal communication subsystem.
   - The Head role likely acts as the broadcast source, while mentors and students receive notices through their own dashboards.
   - This is a domain feature, not a general chat system; it appears oriented toward department announcements and operational updates.

10. **Common vs role-specific services**
   - `commonController.js` and `commonRoutes.js` imply shared backend operations used across roles, such as generic uploads, lookup data, or dashboard-wide utilities.
   - The role-specific controllers and routes keep workflows isolated while still allowing a shared foundation for cross-cutting actions.

11. **Operational infrastructure**
   - The backend depends on **Node.js, Express, Mongoose, Multer, JWT, and bcrypt**, which means authentication is token-based and passwords are hashed.
   - The frontend uses **React + Vite**, with TailwindCSS and additional UI libraries noted in the README.
   - There is no sign of a separate job queue, cache, or external storage service; persistence is primarily **MongoDB + local upload storage**.

12. **How to diagram the system**
   - A good architecture diagram should show:
     - Three client-facing role UIs on the frontend.
     - A shared frontend API/service layer feeding a single backend.
     - Backend routing separated into auth/common/head/mentor/student modules.
     - Controllers calling Mongoose models.
     - MongoDB as the main data store.
     - Local upload storage as a separate file store linked to document records.
     - JWT auth middleware protecting role-specific API paths.

Main entry points: [`backend/routes/headRoutes.js`](https://github.com/krishagarwal-44/project-desk/blob/main/backend/routes/headRoutes.js) (Role routes), [`frontend/Allocation/src/services/headService.js`](https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/services/headService.js) (Role services), [`backend/models/Student.js`](https://github.com/krishagarwal-44/project-desk/blob/main/backend/models/Student.js) (Domain models), [`backend/server.js`](https://github.com/krishagarwal-44/project-desk/blob/main/backend/server.js) (API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>React app<br/>[App.jsx]"]
  node_frontend_auth(("Auth state<br/>context/hook<br/>[AuthContext.jsx]"))
  node_frontend_route_guard{{"Private route<br/>route guard<br/>[PrivateRoute.jsx]"}}
  node_frontend_shell_ui["Shell UI<br/>layout components<br/>[Navbar.jsx]"]
  node_frontend_api_client["API client<br/>HTTP client<br/>[axios.js]"]
  node_frontend_services["Role services<br/>service layer<br/>[headService.js]"]
  node_frontend_head_ui["Head UI<br/>role workspace<br/>[HeadDashboard.jsx]"]
  node_frontend_mentor_ui["Mentor UI<br/>role workspace"]
  node_frontend_student_ui["Student UI<br/>role workspace"]
end

subgraph group_backend["Backend"]
  node_backend_server["API server<br/>Express entrypoint<br/>[server.js]"]
  node_backend_auth_routes["Auth routes<br/>route module<br/>[authRoutes.js]"]
  node_backend_role_routes["Role routes<br/>route modules<br/>[headRoutes.js]"]
  node_backend_auth_mw{{"Auth middleware<br/>JWT gatekeeper<br/>[authMiddleware.js]"}}
  node_backend_auth_ctrl["Auth controller<br/>[authController.js]"]
  node_backend_common_ctrl["Common controller"]
  node_backend_role_ctrls["Role controllers<br/>[headController.js]"]
end

subgraph group_data["Data & files"]
  node_backend_models[("Domain models<br/>Mongoose models<br/>[Student.js]")]
  node_backend_uploads["Upload store<br/>filesystem"]
end

node_frontend_app -->|"renders"| node_frontend_shell_ui
node_frontend_app -->|"protects"| node_frontend_route_guard
node_frontend_auth -->|"provides auth"| node_frontend_app
node_frontend_route_guard -->|"reads session"| node_frontend_auth
node_frontend_head_ui -->|"calls"| node_frontend_services
node_frontend_mentor_ui -->|"calls"| node_frontend_services
node_frontend_student_ui -->|"calls"| node_frontend_services
node_frontend_services -->|"uses"| node_frontend_api_client
node_frontend_api_client -->|"HTTP API"| node_backend_server
node_backend_server -->|"mounts"| node_backend_auth_routes
node_backend_server -->|"mounts"| node_backend_role_routes
node_backend_auth_routes -->|"delegates"| node_backend_auth_ctrl
node_backend_role_routes -->|"delegates"| node_backend_common_ctrl
node_backend_role_routes -->|"delegates"| node_backend_role_ctrls
node_backend_role_routes -->|"protects"| node_backend_auth_mw
node_backend_auth_ctrl -->|"reads/writes"| node_backend_models
node_backend_common_ctrl -->|"reads/writes"| node_backend_models
node_backend_role_ctrls -->|"reads/writes"| node_backend_models
node_backend_role_ctrls -->|"stores files"| node_backend_uploads
node_backend_models -.->|"references"| node_backend_uploads

click node_frontend_app "https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/App.jsx"
click node_frontend_auth "https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/context/AuthContext.jsx"
click node_frontend_route_guard "https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/routes/PrivateRoute.jsx"
click node_frontend_shell_ui "https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/components/Navbar.jsx"
click node_frontend_api_client "https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/utils/axios.js"
click node_frontend_services "https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/services/headService.js"
click node_frontend_head_ui "https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/pages/Head/HeadDashboard.jsx"
click node_frontend_mentor_ui "https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/pages/Mentor/MentorDashboard.jsx"
click node_frontend_student_ui "https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/pages/Student/StudentDashboard.jsx"
click node_backend_server "https://github.com/krishagarwal-44/project-desk/blob/main/backend/server.js"
click node_backend_auth_routes "https://github.com/krishagarwal-44/project-desk/blob/main/backend/routes/authRoutes.js"
click node_backend_role_routes "https://github.com/krishagarwal-44/project-desk/blob/main/backend/routes/headRoutes.js"
click node_backend_auth_mw "https://github.com/krishagarwal-44/project-desk/blob/main/backend/middleware/authMiddleware.js"
click node_backend_auth_ctrl "https://github.com/krishagarwal-44/project-desk/blob/main/backend/controllers/authController.js"
click node_backend_common_ctrl "https://github.com/krishagarwal-44/project-desk/blob/main/backend/controllers/commonController.js"
click node_backend_role_ctrls "https://github.com/krishagarwal-44/project-desk/blob/main/backend/controllers/headController.js"
click node_backend_models "https://github.com/krishagarwal-44/project-desk/blob/main/backend/models/Student.js"
click node_backend_uploads "https://github.com/krishagarwal-44/project-desk/tree/main/backend/uploads"

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_frontend_app,node_frontend_auth,node_frontend_route_guard,node_frontend_shell_ui,node_frontend_api_client,node_frontend_services,node_frontend_head_ui,node_frontend_mentor_ui,node_frontend_student_ui toneBlue
class node_backend_server,node_backend_auth_routes,node_backend_role_routes,node_backend_auth_mw,node_backend_auth_ctrl,node_backend_common_ctrl,node_backend_role_ctrls toneAmber
class node_backend_models,node_backend_uploads toneMint
```

## Components

### Frontend

React/Vite client with role-based dashboards and shared auth/UI shell.

- [App shell](https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/App.jsx): React app · Main frontend composition and routing entry. · `frontend/Allocation/src/App.jsx`
- [Auth state](https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/context/AuthContext.jsx): context/hook · Central auth context and helper hook for session state. · `frontend/Allocation/src/context/AuthContext.jsx`
- [Private route](https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/routes/PrivateRoute.jsx): route guard · Protects authenticated or role-restricted views. · `frontend/Allocation/src/routes/PrivateRoute.jsx`
- [Shell UI](https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/components/Navbar.jsx): layout components · Shared navigation and menu chrome for the client. · `frontend/Allocation/src/components/Navbar.jsx`
- [API client](https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/utils/axios.js): HTTP client · Shared Axios boundary used by all service modules. · `frontend/Allocation/src/utils/axios.js`
- [Role services](https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/services/headService.js): service layer · Frontend service modules for auth, common, head, mentor, and student flows. · `frontend/Allocation/src/services/headService.js`
- [Head UI](https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/pages/Head/HeadDashboard.jsx): role workspace · Head dashboards, reviews, interviews, documents, and messaging screens. · `frontend/Allocation/src/pages/Head/HeadDashboard.jsx`
- [Mentor UI](https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/pages/Mentor/MentorDashboard.jsx): role workspace · Mentor pages for assigned projects, forms, documentation, and messages. · `frontend/Allocation/src/pages/Mentor/MentorDashboard.jsx`
- [Student UI](https://github.com/krishagarwal-44/project-desk/blob/main/frontend/Allocation/src/pages/Student/StudentDashboard.jsx): role workspace · Student pages for ideas, bank projects, checklist, pipeline, and messages. · `frontend/Allocation/src/pages/Student/StudentDashboard.jsx`

### Backend

Express API split by auth, shared, and role-specific routes/controllers.

- [API server](https://github.com/krishagarwal-44/project-desk/blob/main/backend/server.js): Express entrypoint · Bootstraps the Node/Express backend and mounts routes. · `backend/server.js`
- [Auth routes](https://github.com/krishagarwal-44/project-desk/blob/main/backend/routes/authRoutes.js): route module · Authentication and registration endpoints. · `backend/routes/authRoutes.js`
- [Role routes](https://github.com/krishagarwal-44/project-desk/blob/main/backend/routes/headRoutes.js): route modules · Shared and role-specific API surfaces for head, mentor, and student operations. · `backend/routes/headRoutes.js`
- [Auth middleware](https://github.com/krishagarwal-44/project-desk/blob/main/backend/middleware/authMiddleware.js): JWT gatekeeper · Protects APIs with token validation and role-aware access control. · `backend/middleware/authMiddleware.js`
- [Auth controller](https://github.com/krishagarwal-44/project-desk/blob/main/backend/controllers/authController.js): controller · Handles login and registration logic. · `backend/controllers/authController.js`
- [Common controller](https://github.com/krishagarwal-44/project-desk/blob/main/backend/controllers/commonController.js): controller · Shared backend operations used across roles. · `backend/controllers/commonController.js`
- [Role controllers](https://github.com/krishagarwal-44/project-desk/blob/main/backend/controllers/headController.js): controllers · Head, mentor, and student workflow handlers. · `backend/controllers/headController.js`

### Data & files

MongoDB models plus local upload storage for documents.

- [Domain models](https://github.com/krishagarwal-44/project-desk/blob/main/backend/models/Student.js): Mongoose models · Persistent business objects for users, projects, forms, checklists, interviews, messages, and documents. · `backend/models/Student.js`
- [Upload store](https://github.com/krishagarwal-44/project-desk/tree/main/backend/uploads): filesystem · Local server-side storage for uploaded files. · `backend/uploads`

## Connections

- App shell → Shell UI: renders · Composes shared UI chrome and application views.
- App shell → Private route: protects · Wraps sensitive routes with access checks.
- Auth state → App shell: provides auth · Supplies session and user state to the app.
- Private route → Auth state: reads session · Uses auth state to decide access.
- Head UI → Role services: calls · Uses service modules for role operations.
- Mentor UI → Role services: calls · Uses service modules for role operations.
- Student UI → Role services: calls · Uses service modules for role operations.
- Role services → API client: uses · All API requests flow through the shared Axios client.
- API client → API server: HTTP API · Client requests hit the Express backend.
- API server → Auth routes: mounts · Registers authentication endpoints.
- API server → Role routes: mounts · Registers shared and role-specific endpoints.
- Auth routes → Auth controller: delegates · Auth routes invoke controller logic.
- Role routes → Common controller: delegates · Shared routes invoke common backend logic.
- Role routes → Role controllers: delegates · Role routes invoke head/mentor/student handlers.
- Role routes → Auth middleware: protects · Secures private API paths with JWT/role checks.
- Auth controller → Domain models: reads/writes · Auth operations persist identity data.
- Common controller → Domain models: reads/writes · Shared operations access core domain records.
- Role controllers → Domain models: reads/writes · Workflow handlers update lifecycle state and documents.
- Role controllers → Upload store: stores files · Upload flows write binaries to local filesystem storage.
- Domain models → Upload store: references · Document records point to uploaded files.