# pranav1632/alumhub architecture

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

- Interactive diagram: https://gitdiagram.com/pranav1632/alumhub
- Repository: https://github.com/pranav1632/alumhub

## Overview

1. **Overall shape**
   AlumHub is a two-tier application: a React/Vite frontend in `alumni-frontend` and an Express/Mongoose backend in `alumni-backend`. The frontend is a routed single-page app; the backend is a REST API with a Socket.IO realtime layer.

2. **Frontend boundary**
   The frontend is organized around route pages in `src/pages`, shared UI in `src/components`, and application-wide auth state in `src/context/AuthContext.jsx`. `ProtectedRoute` and the dashboard pages enforce role-based navigation for `student`, `alumni`, and `admin` users.

3. **API access pattern**
   Client-server communication goes through `src/utils/axiosInstance.js`, which centralizes API calls and likely attaches auth tokens. This keeps page components thin and makes the backend appear as a set of domain APIs rather than direct model access.

4. **Backend request pipeline**
   Incoming HTTP traffic enters `server.js`, passes through security and auth middleware, and is dispatched by route modules to controllers. The key boundaries are `routes/ -> controllers/ -> models/`, with middleware handling authentication, authorization, and error normalization.

5. **Domain data model**
   MongoDB/Mongoose is the system of record. The main collections are centered on users and role-specific profiles (`User`, `StudentProfile`, `AlumniProfile`), plus interaction objects such as `MentorshipRequest`, `ChatRequest`, `Message`, `Discussion`, `Event`, `Notification`, and `Feedback`.

6. **Identity, signup, and verification flow**
   Authentication is handled by `authController` and `authRoutes`, with JWT-backed sessions and a verification/approval process before users fully participate. The readme and utility files indicate email-based OTP or verification code flows, plus document uploads for signup verification through Cloudinary unsigned uploads on the frontend.

7. **Role-based access and college isolation**
   Authorization is enforced with `middleware/authMiddleware.js` and related verification flags. The architecture is intentionally multi-tenant at the college level: `collegeId` scopes access so directories, chats, events, and admin actions remain isolated to a specific institution.

8. **Realtime chat subsystem**
   Private messaging is split between REST endpoints (`chatRoutes`, `chatController`) and a Socket.IO service in `socket/chatSocket.js`. The backend also has chat request permissions and read/delivery-state support, so the realtime channel is not just transport—it is part of the authorization and message state model.

9. **Community, mentorship, events, and notifications**
   Core engagement features are separated into their own modules: discussions/replies/likes, mentorship request lifecycle, event CRUD, and notifications. These modules are connected by shared user identity and notification creation, so actions in one domain often emit records into another.

10. **Admin and dashboard layer**
   Admin functionality is isolated in `adminController` and `adminRoutes`, covering verification, moderation, and feedback handling. Dashboard endpoints aggregate metrics for student, alumni, and college views, which the frontend consumes via dedicated dashboard pages.

11. **Supporting services**
   External services matter here: Nodemailer/SMTP supports account verification and email delivery, while Cloudinary is used for document and profile image uploads. `CORS` allowlisting and rate limiting are part of the API perimeter, reflecting an internet-facing app with multiple deployed origins.

12. **Deployment/runtime split**
   The frontend is built with Vite and configured for browser deployment, including Vercel support. The backend is a Node.js runtime service deployed separately, with environment-driven configuration for MongoDB, JWT, mail, and allowed client origins.

13. **Non-core artifacts**
   The repo also includes Postman testing docs and project/report documents, which support validation and documentation but are not runtime parts of the architecture. A local `btm.db` file appears present, but the primary database architecture described by the codebase is MongoDB.

Main entry points: [`alumni-frontend/src/pages`](https://github.com/pranav1632/alumhub/tree/main/alumni-frontend/src/pages) (Pages), [`alumni-backend/server.js`](https://github.com/pranav1632/alumhub/blob/main/alumni-backend/server.js) (Server), [`alumni-backend/controllers`](https://github.com/pranav1632/alumhub/tree/main/alumni-backend/controllers) (Controllers), [`alumni-frontend/src/utils/axiosInstance.js`](https://github.com/pranav1632/alumhub/blob/main/alumni-frontend/src/utils/axiosInstance.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_app["App shell<br/>React SPA<br/>[App.jsx]"]
  node_fe_routes["Pages<br/>route views"]
  node_fe_components["Shared UI<br/>components"]
  node_fe_auth(("Auth state<br/>context<br/>[AuthContext.jsx]"))
  node_fe_api["API client<br/>axios wrapper<br/>[axiosInstance.js]"]
  node_fe_dashboards["Dashboards<br/>role views"]
end

subgraph group_backend["Backend"]
  node_be_server["Server<br/>Express entry<br/>[server.js]"]
  node_be_authmw["Auth middleware<br/>security layer<br/>[authMiddleware.js]"]
  node_be_errmw["Error middleware<br/>error layer<br/>[errorMiddleware.js]"]
  node_be_routes["Routes<br/>route modules"]
  node_be_controllers["Controllers<br/>request handlers"]
  node_be_models[("Models")]
  node_be_socket["Chat socket<br/>socket service<br/>[chatSocket.js]"]
  node_be_utils["Domain utils<br/>helpers"]
end

subgraph group_services["External services"]
  node_svc_db[("MongoDB<br/>data store")]
  node_svc_mail["Email service<br/>SMTP/Nodemailer"]
  node_svc_cloud["Cloudinary<br/>media upload"]
  node_svc_runtime["Deploy targets<br/>runtime<br/>[vercel.json]"]
  node_docs["Docs<br/>[README.md]"]
end

node_fe_app -->|"renders"| node_fe_routes
node_fe_app -->|"uses"| node_fe_components
node_fe_routes -->|"reads auth"| node_fe_auth
node_fe_components -->|"guards UI"| node_fe_auth
node_fe_routes -->|"calls API"| node_fe_api
node_fe_dashboards -->|"loads metrics"| node_fe_api
node_fe_api -->|"HTTP"| node_be_server
node_be_server -->|"passes through"| node_be_authmw
node_be_server -->|"dispatches to"| node_be_routes
node_be_routes -->|"invokes"| node_be_controllers
node_be_controllers -->|"persists via"| node_be_models
node_be_controllers -->|"uses"| node_be_utils
node_be_controllers -->|"emits realtime"| node_be_socket
node_be_socket -->|"reads/writes"| node_be_models
node_be_utils -->|"sends email"| node_svc_mail
node_fe_routes -->|"uploads docs"| node_svc_cloud
node_be_models -->|"stores data"| node_svc_db
node_be_server -.->|"deploys on"| node_svc_runtime
node_docs -.->|"describes"| node_be_routes

click node_fe_app "https://github.com/pranav1632/alumhub/blob/main/alumni-frontend/src/App.jsx"
click node_fe_routes "https://github.com/pranav1632/alumhub/tree/main/alumni-frontend/src/pages"
click node_fe_components "https://github.com/pranav1632/alumhub/tree/main/alumni-frontend/src/components"
click node_fe_auth "https://github.com/pranav1632/alumhub/blob/main/alumni-frontend/src/context/AuthContext.jsx"
click node_fe_api "https://github.com/pranav1632/alumhub/blob/main/alumni-frontend/src/utils/axiosInstance.js"
click node_fe_dashboards "https://github.com/pranav1632/alumhub/tree/main/alumni-frontend/src/pages/dashboards"
click node_be_server "https://github.com/pranav1632/alumhub/blob/main/alumni-backend/server.js"
click node_be_authmw "https://github.com/pranav1632/alumhub/blob/main/alumni-backend/middleware/authMiddleware.js"
click node_be_errmw "https://github.com/pranav1632/alumhub/blob/main/alumni-backend/middleware/errorMiddleware.js"
click node_be_routes "https://github.com/pranav1632/alumhub/tree/main/alumni-backend/routes"
click node_be_controllers "https://github.com/pranav1632/alumhub/tree/main/alumni-backend/controllers"
click node_be_models "https://github.com/pranav1632/alumhub/tree/main/alumni-backend/models"
click node_be_socket "https://github.com/pranav1632/alumhub/blob/main/alumni-backend/socket/chatSocket.js"
click node_be_utils "https://github.com/pranav1632/alumhub/tree/main/alumni-backend/utils"
click node_svc_runtime "https://github.com/pranav1632/alumhub/blob/main/alumni-frontend/vercel.json"
click node_docs "https://github.com/pranav1632/alumhub/blob/main/README.md"

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_fe_app,node_fe_routes,node_fe_components,node_fe_auth,node_fe_api,node_fe_dashboards toneBlue
class node_be_server,node_be_authmw,node_be_errmw,node_be_routes,node_be_controllers,node_be_models,node_be_socket,node_be_utils toneAmber
class node_svc_db,node_svc_mail,node_svc_cloud,node_svc_runtime,node_docs toneMint
```

## Components

### Frontend

React/Vite single-page app with routed pages, shared UI, and auth state.

- [App shell](https://github.com/pranav1632/alumhub/blob/main/alumni-frontend/src/App.jsx): React SPA · Top-level client app wiring routing and layout. · `alumni-frontend/src/App.jsx`
- [Pages](https://github.com/pranav1632/alumhub/tree/main/alumni-frontend/src/pages): route views · Primary routed screens for login, profile, chat, directory, discussions, events, mentorship, and dashboards. · `alumni-frontend/src/pages`
- [Shared UI](https://github.com/pranav1632/alumhub/tree/main/alumni-frontend/src/components): components · Reusable interface components such as header, footer, chat widget, notifications, and protected routing. · `alumni-frontend/src/components`
- [Auth state](https://github.com/pranav1632/alumhub/blob/main/alumni-frontend/src/context/AuthContext.jsx): context · Application-wide authentication and user state. · `alumni-frontend/src/context/AuthContext.jsx`
- [API client](https://github.com/pranav1632/alumhub/blob/main/alumni-frontend/src/utils/axiosInstance.js): axios wrapper · Centralized HTTP client used by the frontend to call backend APIs. · `alumni-frontend/src/utils/axiosInstance.js`
- [Dashboards](https://github.com/pranav1632/alumhub/tree/main/alumni-frontend/src/pages/dashboards): role views · Student, alumni, and college dashboard pages built on role-aware navigation. · `alumni-frontend/src/pages/dashboards`

### Backend

Express/Mongoose API with controllers, middleware, models, and realtime chat.

- [Server](https://github.com/pranav1632/alumhub/blob/main/alumni-backend/server.js): Express entry · HTTP entrypoint that boots the API, middleware, routes, and Socket.IO. · `alumni-backend/server.js`
- [Auth middleware](https://github.com/pranav1632/alumhub/blob/main/alumni-backend/middleware/authMiddleware.js): security layer · JWT, role, and verification enforcement for protected routes. · `alumni-backend/middleware/authMiddleware.js`
- [Error middleware](https://github.com/pranav1632/alumhub/blob/main/alumni-backend/middleware/errorMiddleware.js): error layer · Central error normalization and response handling. · `alumni-backend/middleware/errorMiddleware.js`
- [Routes](https://github.com/pranav1632/alumhub/tree/main/alumni-backend/routes): route modules · REST endpoint grouping for auth, users, admin, chat, dashboards, discussions, events, feedback, mentorship, alumni, and notifications. · `alumni-backend/routes`
- [Controllers](https://github.com/pranav1632/alumhub/tree/main/alumni-backend/controllers): request handlers · Domain controllers that implement API behavior across identity, community, chat, events, and admin flows. · `alumni-backend/controllers`
- [Models](https://github.com/pranav1632/alumhub/tree/main/alumni-backend/models): mongoose models · MongoDB collections for users, profiles, messaging, engagement, and feedback. · `alumni-backend/models`
- [Chat socket](https://github.com/pranav1632/alumhub/blob/main/alumni-backend/socket/chatSocket.js): socket service · Socket.IO realtime channel for private messaging and delivery state. · `alumni-backend/socket/chatSocket.js`
- [Domain utils](https://github.com/pranav1632/alumhub/tree/main/alumni-backend/utils): helpers · Support functions for chat permissions, notifications, verification, profiles, and email sending. · `alumni-backend/utils`

### External services

Email, file storage, database, and deployment/runtime dependencies.

- **MongoDB**: data store · Primary system of record for users, profiles, chats, events, notifications, and community content.
- **Email service**: SMTP/Nodemailer · Outbound email delivery for verification and account communication.
- **Cloudinary**: media upload · External document and image upload storage used during signup and profile flows.
- [Deploy targets](https://github.com/pranav1632/alumhub/blob/main/alumni-frontend/vercel.json): runtime · Separate browser deployment for the frontend and Node.js deployment for the backend. · `alumni-frontend/vercel.json`
- [Docs](https://github.com/pranav1632/alumhub/blob/main/README.md): repo docs · Testing and project documentation supporting the application but not part of runtime architecture. · `README.md`

## Connections

- App shell → Pages: renders · The app shell mounts routed pages and views.
- App shell → Shared UI: uses · The app shell composes shared UI and layout components.
- Pages → Auth state: reads auth · Pages and dashboards rely on shared auth state for user identity and role.
- Shared UI → Auth state: guards UI · ProtectedRoute and related components enforce client-side access patterns.
- Pages → API client: calls API · Route pages fetch and mutate data through the centralized axios client.
- Dashboards → API client: loads metrics · Dashboard views request role-specific aggregate data from the backend.
- API client → Server: HTTP · Client-server communication enters the backend via REST endpoints.
- Server → Auth middleware: passes through · Incoming requests are filtered by authentication and authorization middleware.
- Server → Routes: dispatches to · The server forwards requests to route modules.
- Routes → Controllers: invokes · Routes delegate business logic to controllers.
- Controllers → Models: persists via · Controllers read and write MongoDB collections through Mongoose models.
- Controllers → Domain utils: uses · Controllers rely on helpers for verification, notifications, mail, and profile logic.
- Controllers → Chat socket: emits realtime · Chat operations coordinate with the Socket.IO messaging layer.
- Chat socket → Models: reads/writes · Realtime messaging state is backed by chat and message documents.
- Domain utils → Email service: sends email · Verification and account flows use outbound email delivery.
- Pages → Cloudinary: uploads docs · Signup and profile flows include cloud-hosted uploads.
- Models → MongoDB: stores data · The Mongoose models persist the application data model in MongoDB.
- Server → Deploy targets: deploys on · Frontend and backend are deployed as separate runtime targets.
- Docs → Routes: describes · Repository documentation and testing notes explain the API surface.
