# tamalnath963/facultyhub architecture

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

- Interactive diagram: https://gitdiagram.com/tamalnath963/facultyhub
- Repository: https://github.com/tamalnath963/facultyhub

## Overview

1. **Overall shape**
   - FacultyHub is a two-tier MERN application: a React frontend in `frontend/` and an Express/MongoDB API in `backend/`.
   - The core runtime boundary is browser UI → Axios HTTP calls → Express routes → Mongoose models → MongoDB, with file uploads handled separately on the backend filesystem.

2. **Backend entry and API surface**
   - `backend/server.js` is the API bootstrap point; it wires middleware, database connection, and route modules.
   - The API is split by domain into `authRoutes`, `facultyRoutes`, `reviewRoutes`, `reportRoutes`, and `adminRoutes`, which makes the backend naturally diagrammable as a set of feature-specific services rather than one monolith.

3. **Data model boundary**
   - MongoDB stores four main collections: `User`, `Faculty`, `Review`, and `Report`.
   - `User` supports all roles (student, faculty, admin) and drives access control.
   - `Faculty` represents profile and status data.
   - `Review` stores submitted ratings, moderation state, and review metadata.
   - `Report` holds generated/aggregated performance output for display and export.

4. **Auth and authorization flow**
   - Authentication is JWT-based: login/register endpoints issue tokens, and `backend/middleware/auth.js` protects privileged routes.
   - Role checks are enforced on the server, not just in the UI, so the architecture has both presentation-layer gating and API-layer enforcement.
   - The frontend keeps auth state in `frontend/src/context/AuthContext.js`, while `ProtectedRoute.js` blocks unauthenticated navigation.

5. **File upload subsystem**
   - Profile photo upload is a separate concern handled by `backend/middleware/upload.js` using Multer.
   - Uploaded images are stored in the backend `uploads/` directory, which is a persistence boundary distinct from MongoDB.
   - The frontend has a dedicated `PhotoUpload` page and photo-aware profile pages for student, faculty, and admin.

6. **Faculty management subsystem**
   - Faculty CRUD and status management live in `facultyRoutes.js` and are surfaced in `FacultyDirectory`, `FacultyForm`, `FacultyMyProfile`, and `SearchFaculty`.
   - This subsystem supports both admin-created records and faculty self-management, so ownership is role-dependent.
   - The directory UI supports browsing, search, and profile inspection, while the form UI serves create/edit flows.

7. **Review lifecycle and moderation**
   - Reviews follow a state machine: pending → approved/rejected, with only approved reviews becoming publicly visible.
   - `reviewRoutes.js` is the moderation boundary: students can submit reviews, admins can approve/reject/delete, and faculty/students can view approved feedback.
   - The frontend divides this into `SubmitReview`, `ReviewsPage`, and `AdminReviews`, which map cleanly to submission, display, and moderation concerns.

8. **Performance reporting subsystem**
   - `reportRoutes.js` provides the reporting layer, which derives performance metrics from approved reviews rather than manual entry.
   - The README indicates MongoDB aggregation is used for averages, category scores, semester comparisons, and leaderboard ranking.
   - `ReportsPage` is the main presentation layer for charts, report cards, and export-oriented views, while the `Report` model represents persisted report output when needed.

9. **Role-specific UI structure**
   - The frontend routes in `App.js` are organized by role and task: student, faculty, and admin each get distinct pages and dashboards.
   - `Sidebar.js` is role-aware navigation, and `Dashboard.js` acts as a landing page that changes based on the current user’s role.
   - Admin-focused pages (`AdminDashboard`, `AdminReviews`, `Adminprofile`) form a separate control plane from the general user experience.

10. **Frontend composition pattern**
   - Reusable UI is concentrated in `components/` such as `FacultyCard`, `StarRating`, `Sidebar`, and `ProtectedRoute`.
   - Page-level components in `pages/` orchestrate data fetching, filtering, forms, and role-specific rendering.
   - Shared API access is centralized in `frontend/src/utils/api.js`, so all network calls are funneled through one client boundary.

11. **Cross-cutting UX and state**
   - `AuthContext.js` is the main shared client state for login status, current user, and role-driven rendering.
   - The app uses React Router for navigation and React-based component composition for all major screens.
   - Global styling is centralized in `index.css`, with the README indicating a dark-theme design system built using CSS variables.

12. **Key architecture boundaries to capture in a diagram**
   - Browser/UI boundary: React pages and components.
   - Client state boundary: Auth context and protected routing.
   - API boundary: Express route modules by domain.
   - Security boundary: JWT middleware and role checks.
   - Persistence boundary: MongoDB collections plus filesystem uploads.
   - Derived-data boundary: report aggregation from review data.

13. **External/runtime dependencies that materially matter**
   - Node.js/Express run the server side, React runs the client side, MongoDB is the primary datastore, and JWT/bcrypt/Multer support security and uploads.
   - The repo is designed to be run as two processes in development, with the root package coordinating frontend and backend startup.

Main entry points: [`backend/server.js`](https://github.com/tamalnath963/facultyhub/blob/main/backend/server.js) (Server), [`frontend/src/App.js`](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/App.js) (App), [`frontend/src/utils/api.js`](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/utils/api.js) (API Client), [`backend/routes/reviewRoutes.js`](https://github.com/tamalnath963/facultyhub/blob/main/backend/routes/reviewRoutes.js) (Review Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App<br/>router shell<br/>[App.js]"]
  node_frontend_auth(("Auth State<br/>context<br/>[AuthContext.js]"))
  node_frontend_protected{{"Protected Route<br/>guard<br/>[ProtectedRoute.js]"}}
  node_frontend_api["API Client<br/>http client<br/>[api.js]"]
  node_frontend_sidebar["Sidebar<br/>navigation<br/>[Sidebar.js]"]
  node_frontend_dashboard["Dashboard<br/>role landing<br/>[Dashboard.js]"]
  node_frontend_faculty_directory["Faculty Directory<br/>browse page"]
  node_frontend_faculty_form["Faculty Form<br/>editor page<br/>[FacultyForm.js]"]
  node_frontend_submit_review["Submit Review<br/>submission page<br/>[SubmitReview.js]"]
  node_frontend_reviews["Reviews Page<br/>display page<br/>[ReviewsPage.js]"]
  node_frontend_admin_reviews["Admin Reviews<br/>moderation page<br/>[AdminReviews.js]"]
  node_frontend_reports["Reports Page<br/>analytics page<br/>[ReportsPage.js]"]
  node_frontend_photo_upload["Photo Upload<br/>upload page<br/>[PhotoUpload.js]"]
end

subgraph group_backend["Backend"]
  node_backend_server["Server<br/>api bootstrap<br/>[server.js]"]
  node_backend_auth_routes["Auth Routes<br/>route module<br/>[authRoutes.js]"]
  node_backend_faculty_routes["Faculty Routes<br/>route module<br/>[facultyRoutes.js]"]
  node_backend_review_routes["Review Routes<br/>route module<br/>[reviewRoutes.js]"]
  node_backend_report_routes["Report Routes<br/>route module<br/>[reportRoutes.js]"]
  node_backend_admin_routes["Admin Routes<br/>route module<br/>[adminRoutes.js]"]
  node_backend_auth_mw{{"Auth Middleware<br/>security middleware<br/>[auth.js]"}}
  node_backend_upload_mw{{"Upload Middleware<br/>file middleware<br/>[upload.js]"}}
  node_backend_user_model[("User<br/>mongoose model<br/>[User.js]")]
  node_backend_faculty_model[("Faculty<br/>mongoose model<br/>[Faculty.js]")]
  node_backend_review_model[("Review<br/>mongoose model<br/>[Review.js]")]
  node_backend_report_model[("Report<br/>mongoose model<br/>[Report.js]")]
end

node_frontend_app -->|"uses"| node_frontend_auth
node_frontend_app -->|"wraps"| node_frontend_protected
node_frontend_app -->|"renders"| node_frontend_sidebar
node_frontend_app -->|"routes to"| node_frontend_dashboard
node_frontend_app -->|"routes to"| node_frontend_faculty_directory
node_frontend_app -->|"routes to"| node_frontend_submit_review
node_frontend_app -->|"routes to"| node_frontend_reviews
node_frontend_app -->|"routes to"| node_frontend_admin_reviews
node_frontend_app -->|"routes to"| node_frontend_reports
node_frontend_app -->|"routes to"| node_frontend_photo_upload
node_frontend_dashboard -->|"fetches via"| node_frontend_api
node_frontend_faculty_directory -->|"fetches via"| node_frontend_api
node_frontend_faculty_form -->|"writes via"| node_frontend_api
node_frontend_submit_review -->|"submits via"| node_frontend_api
node_frontend_reviews -->|"reads via"| node_frontend_api
node_frontend_admin_reviews -->|"moderates via"| node_frontend_api
node_frontend_reports -->|"queries via"| node_frontend_api
node_frontend_photo_upload -->|"uploads via"| node_frontend_api
node_backend_server -->|"mounts"| node_backend_auth_routes
node_backend_server -->|"mounts"| node_backend_faculty_routes
node_backend_server -->|"mounts"| node_backend_review_routes
node_backend_server -->|"mounts"| node_backend_report_routes
node_backend_server -->|"mounts"| node_backend_admin_routes
node_backend_server -->|"uses"| node_backend_auth_mw
node_backend_server -->|"uses"| node_backend_upload_mw
node_backend_server -.->|"connects to"| node_backend_user_model
node_backend_server -.->|"connects to"| node_backend_faculty_model
node_backend_server -.->|"connects to"| node_backend_review_model
node_backend_server -.->|"connects to"| node_backend_report_model
node_backend_auth_routes -->|"reads/writes"| node_backend_user_model
node_backend_faculty_routes -->|"reads/writes"| node_backend_faculty_model
node_backend_faculty_routes -->|"protects"| node_backend_auth_mw
node_backend_review_routes -->|"reads/writes"| node_backend_review_model
node_backend_review_routes -.->|"authorizes"| node_backend_user_model
node_backend_review_routes -->|"protects"| node_backend_auth_mw
node_backend_report_routes -->|"reads/writes"| node_backend_report_model
node_backend_report_routes -->|"derives from"| node_backend_review_model
node_backend_admin_routes -->|"protects"| node_backend_auth_mw
node_backend_admin_routes -.->|"manages"| node_backend_user_model

click node_frontend_app "https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/App.js"
click node_frontend_auth "https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/context/AuthContext.js"
click node_frontend_protected "https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/components/ProtectedRoute.js"
click node_frontend_api "https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/utils/api.js"
click node_frontend_sidebar "https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/components/Sidebar.js"
click node_frontend_dashboard "https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/Dashboard.js"
click node_frontend_faculty_directory "https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/FacultyDirectory.js"
click node_frontend_faculty_form "https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/FacultyForm.js"
click node_frontend_submit_review "https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/SubmitReview.js"
click node_frontend_reviews "https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/ReviewsPage.js"
click node_frontend_admin_reviews "https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/AdminReviews.js"
click node_frontend_reports "https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/ReportsPage.js"
click node_frontend_photo_upload "https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/PhotoUpload.js"
click node_backend_server "https://github.com/tamalnath963/facultyhub/blob/main/backend/server.js"
click node_backend_auth_routes "https://github.com/tamalnath963/facultyhub/blob/main/backend/routes/authRoutes.js"
click node_backend_faculty_routes "https://github.com/tamalnath963/facultyhub/blob/main/backend/routes/facultyRoutes.js"
click node_backend_review_routes "https://github.com/tamalnath963/facultyhub/blob/main/backend/routes/reviewRoutes.js"
click node_backend_report_routes "https://github.com/tamalnath963/facultyhub/blob/main/backend/routes/reportRoutes.js"
click node_backend_admin_routes "https://github.com/tamalnath963/facultyhub/blob/main/backend/routes/adminRoutes.js"
click node_backend_auth_mw "https://github.com/tamalnath963/facultyhub/blob/main/backend/middleware/auth.js"
click node_backend_upload_mw "https://github.com/tamalnath963/facultyhub/blob/main/backend/middleware/upload.js"
click node_backend_user_model "https://github.com/tamalnath963/facultyhub/blob/main/backend/models/User.js"
click node_backend_faculty_model "https://github.com/tamalnath963/facultyhub/blob/main/backend/models/Faculty.js"
click node_backend_review_model "https://github.com/tamalnath963/facultyhub/blob/main/backend/models/Review.js"
click node_backend_report_model "https://github.com/tamalnath963/facultyhub/blob/main/backend/models/Report.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_frontend_app,node_frontend_auth,node_frontend_protected,node_frontend_api,node_frontend_sidebar,node_frontend_dashboard,node_frontend_faculty_directory,node_frontend_faculty_form,node_frontend_submit_review,node_frontend_reviews,node_frontend_admin_reviews,node_frontend_reports,node_frontend_photo_upload toneBlue
class node_backend_server,node_backend_auth_routes,node_backend_faculty_routes,node_backend_review_routes,node_backend_report_routes,node_backend_admin_routes,node_backend_auth_mw,node_backend_upload_mw,node_backend_user_model,node_backend_faculty_model,node_backend_review_model,node_backend_report_model toneAmber
```

## Components

### Frontend

React UI, shared client state, and page-level flows

- [App](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/App.js): router shell · Top-level React routes and role-based page composition · `frontend/src/App.js`
- [Auth State](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/context/AuthContext.js): context · Shared login, user, and role state for the client · `frontend/src/context/AuthContext.js`
- [Protected Route](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/components/ProtectedRoute.js): guard · Blocks unauthenticated navigation on the client · `frontend/src/components/ProtectedRoute.js`
- [API Client](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/utils/api.js): http client · Central Axios boundary for browser-to-server calls · `frontend/src/utils/api.js`
- [Sidebar](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/components/Sidebar.js): navigation · Role-aware navigation for dashboard and feature pages · `frontend/src/components/Sidebar.js`
- [Dashboard](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/Dashboard.js): role landing · Role-sensitive landing page for students, faculty, and admins · `frontend/src/pages/Dashboard.js`
- [Faculty Directory](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/FacultyDirectory.js): browse page · Browse, search, and inspect faculty records · `frontend/src/pages/FacultyDirectory.js`
- [Faculty Form](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/FacultyForm.js): editor page · Create and edit faculty profiles and status data · `frontend/src/pages/FacultyForm.js`
- [Submit Review](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/SubmitReview.js): submission page · Student review entry flow with ratings and metadata · `frontend/src/pages/SubmitReview.js`
- [Reviews Page](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/ReviewsPage.js): display page · Public-facing approved review listings and feedback views · `frontend/src/pages/ReviewsPage.js`
- [Admin Reviews](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/AdminReviews.js): moderation page · Admin moderation UI for approving, rejecting, and deleting reviews · `frontend/src/pages/AdminReviews.js`
- [Reports Page](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/ReportsPage.js): analytics page · Charts, report cards, and export-oriented performance views · `frontend/src/pages/ReportsPage.js`
- [Photo Upload](https://github.com/tamalnath963/facultyhub/blob/main/frontend/src/pages/PhotoUpload.js): upload page · Client flow for uploading profile images · `frontend/src/pages/PhotoUpload.js`

### Backend

Express API, security middleware, and MongoDB models

- [Server](https://github.com/tamalnath963/facultyhub/blob/main/backend/server.js): api bootstrap · Express bootstrap that wires middleware, database, and routes · `backend/server.js`
- [Auth Routes](https://github.com/tamalnath963/facultyhub/blob/main/backend/routes/authRoutes.js): route module · Login, signup, and JWT issuance endpoints · `backend/routes/authRoutes.js`
- [Faculty Routes](https://github.com/tamalnath963/facultyhub/blob/main/backend/routes/facultyRoutes.js): route module · Faculty CRUD and status management endpoints · `backend/routes/facultyRoutes.js`
- [Review Routes](https://github.com/tamalnath963/facultyhub/blob/main/backend/routes/reviewRoutes.js): route module · Review submission and moderation endpoints · `backend/routes/reviewRoutes.js`
- [Report Routes](https://github.com/tamalnath963/facultyhub/blob/main/backend/routes/reportRoutes.js): route module · Derived reporting and aggregation endpoints · `backend/routes/reportRoutes.js`
- [Admin Routes](https://github.com/tamalnath963/facultyhub/blob/main/backend/routes/adminRoutes.js): route module · Admin-only control plane endpoints · `backend/routes/adminRoutes.js`
- [Auth Middleware](https://github.com/tamalnath963/facultyhub/blob/main/backend/middleware/auth.js): security middleware · JWT verification and server-side role checks · `backend/middleware/auth.js`
- [Upload Middleware](https://github.com/tamalnath963/facultyhub/blob/main/backend/middleware/upload.js): file middleware · Multer-based profile image handling · `backend/middleware/upload.js`
- [User](https://github.com/tamalnath963/facultyhub/blob/main/backend/models/User.js): mongoose model · Shared account and role records for students, faculty, and admins · `backend/models/User.js`
- [Faculty](https://github.com/tamalnath963/facultyhub/blob/main/backend/models/Faculty.js): mongoose model · Faculty profile and status records · `backend/models/Faculty.js`
- [Review](https://github.com/tamalnath963/facultyhub/blob/main/backend/models/Review.js): mongoose model · Submitted reviews, moderation state, and metadata · `backend/models/Review.js`
- [Report](https://github.com/tamalnath963/facultyhub/blob/main/backend/models/Report.js): mongoose model · Persisted report output and aggregated metrics · `backend/models/Report.js`

## Connections

- App → Auth State: uses · App reads current user and role state
- App → Protected Route: wraps · Routes are guarded at the UI boundary
- App → Sidebar: renders · Shared navigation is composed into the shell
- App → Dashboard: routes to · Role-aware landing page
- App → Faculty Directory: routes to · Faculty browsing surface
- App → Submit Review: routes to · Review submission surface
- App → Reviews Page: routes to · Review display surface
- App → Admin Reviews: routes to · Admin moderation surface
- App → Reports Page: routes to · Reporting surface
- App → Photo Upload: routes to · Profile image upload surface
- Dashboard → API Client: fetches via · Dashboard data loads through the shared client
- Faculty Directory → API Client: fetches via · Directory and search data use the shared client
- Faculty Form → API Client: writes via · Create and update requests use the shared client
- Submit Review → API Client: submits via · Review creation requests use the shared client
- Reviews Page → API Client: reads via · Approved review views load from the API
- Admin Reviews → API Client: moderates via · Admin actions call the API client
- Reports Page → API Client: queries via · Report and analytics requests use the shared client
- Photo Upload → API Client: uploads via · Photo upload requests use the shared client
- Server → Auth Routes: mounts · Authentication endpoints are registered on startup
- Server → Faculty Routes: mounts · Faculty endpoints are registered on startup
- Server → Review Routes: mounts · Review endpoints are registered on startup
- Server → Report Routes: mounts · Report endpoints are registered on startup
- Server → Admin Routes: mounts · Admin endpoints are registered on startup
- Server → Auth Middleware: uses · Protected routes rely on authentication middleware
- Server → Upload Middleware: uses · Uploads rely on file handling middleware
- Server → User: connects to · Server bootstraps database access through models
- Server → Faculty: connects to · Server bootstraps database access through models
- Server → Review: connects to · Server bootstraps database access through models
- Server → Report: connects to · Server bootstraps database access through models
- Auth Routes → User: reads/writes · Auth endpoints create and validate user accounts
- Faculty Routes → Faculty: reads/writes · Faculty endpoints manage faculty records
- Faculty Routes → Auth Middleware: protects · Role checks guard management operations
- Review Routes → Review: reads/writes · Review submission and moderation persistence
- Review Routes → User: authorizes · Review actions are tied to user roles
- Review Routes → Auth Middleware: protects · Privileged review actions require JWT auth
- Report Routes → Report: reads/writes · Persisted reporting output and summaries
- Report Routes → Review: derives from · Reports aggregate approved reviews
- Admin Routes → Auth Middleware: protects · Admin control plane is server-side gated
- Admin Routes → User: manages · Admin operations interact with user roles