# student-jss/campusresolve architecture

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

- Interactive diagram: https://gitdiagram.com/student-jss/campusresolve
- Repository: https://github.com/student-jss/campusresolve

## Overview

This is a college complaint-management application: students submit and track complaints, staff handle assigned work, and administrators manage users, categories, assignments, and analytics. The client routes role-specific workflows to an Express API; server controllers enforce domain operations and persist records in MongoDB. Notifications can be delivered in real time, while image storage and password-reset email are integrations. The graph follows documented capabilities and indexed imports; several page-to-service and route-to-controller links are documented only at the API level, so those links are marked unverified.

Main entry points: [`server/routes`](https://github.com/student-jss/campusresolve/tree/main/server/routes) (Express API routes), [`server/controllers/adminController.js`](https://github.com/student-jss/campusresolve/blob/main/server/controllers/adminController.js) (Admin and analytics), [`client/src/services/api.js`](https://github.com/student-jss/campusresolve/blob/main/client/src/services/api.js) (HTTP API client), [`server/models/User.js`](https://github.com/student-jss/campusresolve/blob/main/server/models/User.js) (User records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_app["Role-based routes<br/>[App.jsx]"]
  node_complaint_ui["Complaint workflows"]
  node_admin_ui["Admin console"]
  node_auth_state["Authentication state<br/>[AuthContext.jsx]"]
  node_api_client["HTTP API client<br/>[api.js]"]
  node_complaint_service["Complaint API service"]
  node_notification_ui["Notification client"]
end

subgraph group_api["API and workflows"]
  node_routes["Express API routes"]
  node_auth_controller["Account and recovery<br/>[authController.js]"]
  node_complaint_controller["Complaint lifecycle"]
  node_admin_controller["Admin and analytics<br/>[adminController.js]"]
  node_upload_controller["Image upload handling"]
  node_auth_middleware["JWT and role checks<br/>[auth.js]"]
end

subgraph group_data["Domain data"]
  node_user_model[("User records<br/>[User.js]")]
  node_complaint_model[("Complaint records<br/>[Complaint.js]")]
  node_category_model[("Complaint categories<br/>[Category.js]")]
  node_comment_model[("Complaint comments<br/>[Comment.js]")]
  node_notification_model[("Notification records<br/>[Notification.js]")]
end

subgraph group_integrations["Live and external services"]
  node_socket_service["Authenticated socket rooms<br/>[socket.js]"]
  node_notification_service["Notification dispatch"]
  node_cloudinary["Cloudinary image storage"]
  node_email["SMTP email service<br/>[emailService.js]"]
end

node_users(("Students, staff, admins"))
node_mongodb[("MongoDB")]

node_users -->|"use role routes"| node_app
node_app -->|"routes to"| node_complaint_ui
node_app -->|"routes to"| node_admin_ui
node_complaint_ui -.->|"requests complaints"| node_complaint_service
node_admin_ui -.->|"requests admin data"| node_api_client
node_auth_state -->|"uses auth service"| node_api_client
node_complaint_service -->|"sends HTTP calls"| node_api_client
node_notification_ui -->|"fetches notifications"| node_api_client
node_notification_ui -.->|"receives live events"| node_socket_service
node_api_client -.->|"calls API"| node_routes
node_routes -->|"protects endpoints"| node_auth_middleware
node_routes -->|"dispatches auth"| node_auth_controller
node_routes -->|"dispatches complaints"| node_complaint_controller
node_routes -->|"dispatches uploads"| node_upload_controller
node_routes -.->|"dispatches admin"| node_admin_controller
node_auth_middleware -->|"loads account"| node_user_model
node_auth_controller -->|"reads and writes"| node_user_model
node_auth_controller -->|"sends reset email"| node_email
node_complaint_controller -->|"reads and updates"| node_complaint_model
node_complaint_controller -->|"creates comments"| node_comment_model
node_complaint_controller -->|"creates notifications"| node_notification_service
node_admin_controller -->|"manages users"| node_user_model
node_admin_controller -->|"assigns and aggregates"| node_complaint_model
node_admin_controller -->|"joins category data"| node_category_model
node_admin_controller -->|"notifies assignment"| node_notification_service
node_upload_controller -->|"updates complaint images"| node_complaint_model
node_upload_controller -->|"updates profile image"| node_user_model
node_upload_controller -->|"uploads images"| node_cloudinary
node_notification_service -->|"persists notification"| node_notification_model
node_notification_service -->|"emits event"| node_socket_service
node_user_model -.->|"persists records"| node_mongodb
node_complaint_model -.->|"persists records"| node_mongodb
node_category_model -.->|"persists records"| node_mongodb
node_comment_model -.->|"persists records"| node_mongodb
node_notification_model -.->|"persists records"| node_mongodb

click node_app "https://github.com/student-jss/campusresolve/blob/main/client/src/App.jsx"
click node_complaint_ui "https://github.com/student-jss/campusresolve/tree/main/client/src/pages"
click node_admin_ui "https://github.com/student-jss/campusresolve/tree/main/client/src/pages/admin"
click node_auth_state "https://github.com/student-jss/campusresolve/blob/main/client/src/context/AuthContext.jsx"
click node_api_client "https://github.com/student-jss/campusresolve/blob/main/client/src/services/api.js"
click node_complaint_service "https://github.com/student-jss/campusresolve/blob/main/client/src/services/complaintService.js"
click node_notification_ui "https://github.com/student-jss/campusresolve/blob/main/client/src/hooks/useNotifications.js"
click node_routes "https://github.com/student-jss/campusresolve/tree/main/server/routes"
click node_auth_controller "https://github.com/student-jss/campusresolve/blob/main/server/controllers/authController.js"
click node_complaint_controller "https://github.com/student-jss/campusresolve/blob/main/server/controllers/complaintController.js"
click node_admin_controller "https://github.com/student-jss/campusresolve/blob/main/server/controllers/adminController.js"
click node_upload_controller "https://github.com/student-jss/campusresolve/blob/main/server/controllers/uploadController.js"
click node_auth_middleware "https://github.com/student-jss/campusresolve/blob/main/server/middlewares/auth.js"
click node_user_model "https://github.com/student-jss/campusresolve/blob/main/server/models/User.js"
click node_complaint_model "https://github.com/student-jss/campusresolve/blob/main/server/models/Complaint.js"
click node_category_model "https://github.com/student-jss/campusresolve/blob/main/server/models/Category.js"
click node_comment_model "https://github.com/student-jss/campusresolve/blob/main/server/models/Comment.js"
click node_notification_model "https://github.com/student-jss/campusresolve/blob/main/server/models/Notification.js"
click node_socket_service "https://github.com/student-jss/campusresolve/blob/main/server/sockets/socket.js"
click node_notification_service "https://github.com/student-jss/campusresolve/blob/main/server/services/notificationService.js"
click node_cloudinary "https://github.com/student-jss/campusresolve/blob/main/server/utils/uploadToCloudinary.js"
click node_email "https://github.com/student-jss/campusresolve/blob/main/server/services/emailService.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_app,node_complaint_ui,node_admin_ui,node_auth_state,node_api_client,node_complaint_service,node_notification_ui toneBlue
class node_routes,node_auth_controller,node_complaint_controller,node_admin_controller,node_upload_controller,node_auth_middleware,node_mongodb toneAmber
class node_user_model,node_complaint_model,node_category_model,node_comment_model,node_notification_model toneMint
class node_socket_service,node_notification_service,node_cloudinary,node_email toneRose
class node_users toneIndigo
```

## Components

### Web application

- [Role-based routes](https://github.com/student-jss/campusresolve/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Complaint workflows](https://github.com/student-jss/campusresolve/tree/main/client/src/pages): `client/src/pages`
- [Admin console](https://github.com/student-jss/campusresolve/tree/main/client/src/pages/admin): `client/src/pages/admin`
- [Authentication state](https://github.com/student-jss/campusresolve/blob/main/client/src/context/AuthContext.jsx): `client/src/context/AuthContext.jsx`
- [HTTP API client](https://github.com/student-jss/campusresolve/blob/main/client/src/services/api.js): `client/src/services/api.js`
- [Complaint API service](https://github.com/student-jss/campusresolve/blob/main/client/src/services/complaintService.js): `client/src/services/complaintService.js`
- [Notification client](https://github.com/student-jss/campusresolve/blob/main/client/src/hooks/useNotifications.js): `client/src/hooks/useNotifications.js`

### API and workflows

- [Express API routes](https://github.com/student-jss/campusresolve/tree/main/server/routes): `server/routes`
- [Account and recovery](https://github.com/student-jss/campusresolve/blob/main/server/controllers/authController.js): `server/controllers/authController.js`
- [Complaint lifecycle](https://github.com/student-jss/campusresolve/blob/main/server/controllers/complaintController.js): `server/controllers/complaintController.js`
- [Admin and analytics](https://github.com/student-jss/campusresolve/blob/main/server/controllers/adminController.js): `server/controllers/adminController.js`
- [Image upload handling](https://github.com/student-jss/campusresolve/blob/main/server/controllers/uploadController.js): `server/controllers/uploadController.js`
- [JWT and role checks](https://github.com/student-jss/campusresolve/blob/main/server/middlewares/auth.js): `server/middlewares/auth.js`

### Domain data

- [User records](https://github.com/student-jss/campusresolve/blob/main/server/models/User.js): `server/models/User.js`
- [Complaint records](https://github.com/student-jss/campusresolve/blob/main/server/models/Complaint.js): `server/models/Complaint.js`
- [Complaint categories](https://github.com/student-jss/campusresolve/blob/main/server/models/Category.js): `server/models/Category.js`
- [Complaint comments](https://github.com/student-jss/campusresolve/blob/main/server/models/Comment.js): `server/models/Comment.js`
- [Notification records](https://github.com/student-jss/campusresolve/blob/main/server/models/Notification.js): `server/models/Notification.js`

### Live and external services

- [Authenticated socket rooms](https://github.com/student-jss/campusresolve/blob/main/server/sockets/socket.js): `server/sockets/socket.js`
- [Notification dispatch](https://github.com/student-jss/campusresolve/blob/main/server/services/notificationService.js): `server/services/notificationService.js`
- [Cloudinary image storage](https://github.com/student-jss/campusresolve/blob/main/server/utils/uploadToCloudinary.js): `server/utils/uploadToCloudinary.js`
- [SMTP email service](https://github.com/student-jss/campusresolve/blob/main/server/services/emailService.js): `server/services/emailService.js`

### Other components

- **Students, staff, admins**
- **MongoDB**

## Connections

- Students, staff, admins → Role-based routes: use role routes (evidence: `client/src/App.jsx`)
- Role-based routes → Complaint workflows: routes to (evidence: `client/src/App.jsx`)
- Role-based routes → Admin console: routes to (evidence: `client/src/App.jsx`)
- Complaint workflows → Complaint API service: requests complaints
- Admin console → HTTP API client: requests admin data
- Authentication state → HTTP API client: uses auth service (evidence: `client/src/context/AuthContext.jsx`)
- Complaint API service → HTTP API client: sends HTTP calls (evidence: `client/src/services/complaintService.js`)
- Notification client → HTTP API client: fetches notifications
- Notification client → Authenticated socket rooms: receives live events
- HTTP API client → Express API routes: calls API
- Express API routes → JWT and role checks: protects endpoints (evidence: `server/routes/auth.js`)
- Express API routes → Account and recovery: dispatches auth (evidence: `server/routes/auth.js`)
- Express API routes → Complaint lifecycle: dispatches complaints (evidence: `server/routes/complaints.js`)
- Express API routes → Image upload handling: dispatches uploads (evidence: `server/routes/complaints.js`)
- Express API routes → Admin and analytics: dispatches admin
- JWT and role checks → User records: loads account (evidence: `server/middlewares/auth.js`)
- Account and recovery → User records: reads and writes (evidence: `server/controllers/authController.js`)
- Account and recovery → SMTP email service: sends reset email (evidence: `server/controllers/authController.js`)
- Complaint lifecycle → Complaint records: reads and updates (evidence: `server/controllers/complaintController.js`)
- Complaint lifecycle → Complaint comments: creates comments (evidence: `server/controllers/complaintController.js`)
- Complaint lifecycle → Notification dispatch: creates notifications (evidence: `server/controllers/complaintController.js`)
- Admin and analytics → User records: manages users (evidence: `server/controllers/adminController.js`)
- Admin and analytics → Complaint records: assigns and aggregates (evidence: `server/controllers/adminController.js`)
- Admin and analytics → Complaint categories: joins category data (evidence: `server/controllers/adminController.js`)
- Admin and analytics → Notification dispatch: notifies assignment (evidence: `server/controllers/adminController.js`)
- Image upload handling → Complaint records: updates complaint images (evidence: `server/controllers/uploadController.js`)
- Image upload handling → User records: updates profile image (evidence: `server/controllers/uploadController.js`)
- Image upload handling → Cloudinary image storage: uploads images (evidence: `server/controllers/uploadController.js`)
- Notification dispatch → Notification records: persists notification (evidence: `server/services/notificationService.js`)
- Notification dispatch → Authenticated socket rooms: emits event (evidence: `server/services/notificationService.js`)
- User records → MongoDB: persists records
- Complaint records → MongoDB: persists records
- Complaint categories → MongoDB: persists records
- Complaint comments → MongoDB: persists records
- Notification records → MongoDB: persists records
