Graduation Project Documentation

CampusHub – Real-Time University Chat & Group Communication System

Prepared by: Laith Adel

Department of Computer Engineering Technology

[Al-Mamoon University]

Academic Year: 2024 – 2025

Supervisor: Dr. [Wameed]

CampusHub - Graduation Project | By Laith Adel

CampusHub Chat System

Chapter 1: System Overview

1.1 Project Title

CampusHub - Real-Time Chat & Group Communication System

1.2 Description

CampusHub is a full-stack, secure, and scalable real-time chat and group messaging platform
tailored for university environments. It provides one-on-one messaging, group chats, message
reactions, notifications, and file attachments. Designed to integrate seamlessly with student
portals or learning management systems, CampusHub ensures communication remains smooth,
fast, and private.

1.3 Technologies Used

• Backend: ASP.NET Core (.NET 8)

• Frontend: Next.js (React-based) with Tailwind CSS
• Database: PostgreSQL
• Authentication: JWT with refresh token and reCAPTCHA validation
• Server: Ubuntu with Nginx, SSL (HTTPS)
• Real-time Messaging: SignalR (WebSockets)

1.4 Key Features

• Secure user authentication with token-based flow

• One-on-one and group messaging with delivery & seen status
• Real-time notifications using SignalR
• reCAPTCHA protection for login/signup
• Message reactions, edits, pins, and attachments
• Group management (admins, members, leave, delete)
• Notification and unread message tracking

P a g e 2 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

1.5 System Architecture Overview

+--------------------+ HTTPS +---------------------+
| Frontend | <--------------> | Backend (API) |
| Next.js + Tailwind| | ASP.NET Core 8 |
+--------------------+ +---------------------+
| |
| WebSocket (SignalR) |
v v
Real-Time Notifications PostgreSQL (Data Layer)

1.6 User Roles

• User (Student/Staff): Can chat, create groups, send files, etc.

• Admin (Internal Logic Only): Used in group roles for permissions

Chapter 2: Backend – Authentication System

2.1 Overview

The authentication system provides secure login, registration, verification, token management,
and reCAPTCHA integration to prevent abuse. Users are authenticated using JWT tokens, which
are stored in HTTP-only cookies.

2.2 Registration Endpoint

Endpoint: POST /Account/Register/register

Fields Required:

• First Name
• Last Name
• Email
• Password
• Captcha Token

Flow:

1. reCAPTCHA token is verified.

2. New user is stored in the database.
3. A verification code is sent to the user's email.
4. User is redirected to the verification page.

P a g e 3 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

2.3 Verification Code Endpoint

Endpoint: POST /Account/VerifyCode/verifyCode

Input:

• Email
• Code

Behavior:

• Verifies the code and marks the email as verified.

• Allows login after verification is complete.

2.4 Login Endpoint

Endpoint: POST /Account/Login/login

Fields Required:

• Email
• Password
• Captcha Token

Flow:

1. reCAPTCHA token is validated.

2. Credentials are validated.
3. If valid, JWT access token is returned in the response.
4. Refresh token is stored securely.

2.5 JWT Token Structure

Claims inside JWT:

• NameIdentifier (User ID)

• GivenName / Surname
• Role
• Email

Token Validity: 10 minutes (access), refresh token longer with rotation.

P a g e 4 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

2.6 Refresh Token Generation

• 64-byte secure string using RandomNumberGenerator

• Rotated on every refresh request
• Stored in database (implementation suggested for extension)

2.7 JWT Token Generator Code (Simplified):

new Claim(ClaimTypes.NameIdentifier, userId.ToString()),
new Claim(ClaimTypes.GivenName, firstName),
new Claim(ClaimTypes.Surname, lastName),
new Claim(ClaimTypes.Email, email),
new Claim(ClaimTypes.Role, role.ToString())

2.8 Captcha Integration

• Google reCAPTCHA v2 Invisible

• Frontend triggers it on submit, backend validates via API.
• Secret stored in configuration securely

2.9 Error Handling

• Invalid JWT = 401 Unauthorized

• Invalid Captcha = 400 Bad Request
• Missing Fields = 400
• Expired Token = Manual refresh required (frontend handles it)

2.10 Security Practices

• HTTP-only cookies for token storage

• Strong password validation logic (8+ characters minimum)
• reCAPTCHA validation
• Role-based claims with Authorize attribute in controller
• Rate limiting (can be extended via middleware)

Chapter 3: Backend – Chat and Message Flow

3.1 Overview

P a g e 5 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

The core messaging functionality supports:

• One-on-one chat between users (trusted and untrusted)

• Message delivery, read/seen status
• Reactions, edits, replies, and pinning
• Secure message flow via SignalR in real-time

3.2 Sending a Direct Message

Endpoint: POST /api/Chat/SendMessage

Request Body:

• ReceiverId (GUID)
• Message (string)

Flow:

1. JWT is extracted to get SenderId

2. Verifies that sender ≠ receiver
3. Checks if sender and receiver are friends (Trusted)
4. Saves message to database with Trusted/Untrusted status
5. Sends notification via SignalR to the receiver

Response:

json
CopyEdit
{
"Status": "Message Sent",
"MessageId": "uuid",
"TrustStatus": "Trusted"
}

3.3 Real-time Message Delivery

Tech Used: SignalR (WebSockets)

Client Receives:

P a g e 6 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

• ReceiveMessageNotification
• ReceiveMessage
• Sent with:
o Sender ID
o Message Text
o Timestamp
o Trust Status

3.4 Message Status Updates

• IsRead and ReadAt are set when a message is opened.

• PATCH /api/Chat/markMessageAsSeen/{messageId}
• Sender is notified via SignalR using MessageSeen event

3.5 Message History

Endpoint: GET /api/Chat/getMessagesByUser/{userId}

Pagination: pageNumber, pageSize
Returns a paginated list of all messages exchanged between two users.

3.6 Edit and Delete Messages

• Edit: PATCH /api/Chat/editMessage/{messageId}

o Only the sender can edit
o Tracks EditedAt
• Delete: DELETE /api/Chat/deleteMessage/{messageId}
o Only the sender can delete their own messages

3.7 Message Reactions

Endpoint: POST /api/Chat/reactToMessage/{messageId}

Request: Emoji value in the body
Reactions are broadcasted via MessageReacted event in SignalR.

3.8 Forward & Reply to Messages

• Forward: Copies content and sends to another user with "[Forwarded]" prefix
• Reply: References message content with "[Reply to:]" label

3.9 Pinned Messages

• Pin: POST /api/Chat/pinMessage/{messageId}

P a g e 7 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

• Unpin: DELETE /api/Chat/unpinMessage/{messageId}

• Retrieve: GET /api/Chat/getPinnedMessages

3.10 Unread Message Count

Endpoint: GET /api/Chat/getUnreadMessagesCount

Returns the number of messages where ReceiverId = currentUser and IsRead = false

3.11 Chat Notifications

• Combined endpoint: GET /api/Chat/getNotifications

o Includes unread messages
o Includes pending friend requests
• Mark all as read: PATCH /api/Chat/markNotificationsAsRead

3.12 Chat Search

• Endpoint: GET /api/Chat/searchMessages?keyword=...

• Filters messages by content containing the keyword for current user

3.13 Exit & Delete Chat

• Exit (soft delete): Removes all user-related chat records: POST /api/Chat/exitChat
• Delete chat with user: Deletes all messages between two users: DELETE
/api/Chat/deleteChatWithUser/{userId}

Chapter 4: Group Chat System

4.1 Overview

The group chat system enables multiple users to communicate within a shared space. It supports:

• Group creation
• Admin controls (promote/demote/remove)
• Sending and receiving group messages
• Mentioning members
• Group notifications and unread message tracking

4.2 Create Group

P a g e 8 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

Endpoint: POST /api/Chat/createGroup

Request Body:

• Name: Group name

• MemberIds: List of user GUIDs

Flow:

1. Current user is marked as the group creator

2. Creator is assigned IsAdmin = true
3. Other members are added with IsAdmin = false

4.3 Send Group Message

Endpoint: POST /api/Chat/sendGroupMessage

Flow:

1. Verifies sender is a group member

2. Saves message to GroupMessages table
3. Broadcasts message via SignalR to other group members

4.4 Group Message Mentions

Endpoint: POST /api/Chat/sendGroupMessageWithMentions

Flow:

1. Detects mentions using @email

2. Notifies mentioned users via MentionNotification event

4.5 Retrieve Group Messages

Endpoint: GET /api/Chat/getGroupMessages/{groupId}

Returns all messages for the specified group, sorted by timestamp.

4.6 Retrieve Group Members

P a g e 9 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

Endpoint: GET /api/Chat/getGroupMembers/{groupId}

Returns a list of all members including:

• Full name
• Email
• Admin status

4.7 Manage Group Members

Endpoint: POST /api/Chat/manageGroupMembers

Only accessible by the group creator

Request Body:

• GroupId
• AddMembers: List of new member GUIDs
• RemoveMembers: List of member GUIDs to remove

4.8 Promote to Admin

Endpoint: POST /api/Chat/makeUserAdmin

Allows group creator to assign IsAdmin = true to a user.

4.9 Remove User from Group

Endpoint: POST /api/Chat/removeUserFromGroup

Allows group admins or creator to remove a member.

4.10 Delete Group

Endpoint: DELETE /api/Chat/deleteGroup/{groupId}

Only the creator can delete the group. This also deletes:

• Group messages
• Member records

4.11 Leave Group

Endpoint: POST /api/Chat/leaveGroup/{groupId}

P a g e 10 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

Removes the user from the group.

4.12 Filter/Search Groups

Endpoint: GET /api/Chat/filterGroups?groupName=...

Returns groups matching a name substring where the user is a member.

4.13 Unread Group Messages

Endpoint: GET /api/Chat/unreadGroupMessages

Returns unread message count per group for the current user.

Chapter 5: Notifications & SignalR

5.1 Overview

The notification system ensures users receive real-time updates for important actions like new
messages, group mentions, friend requests, and reactions. SignalR is used to push these events
over WebSockets.

5.2 SignalR Hub Configuration

Class: ChatHub

• Configured in Startup.cs or Program.cs

• Handles methods such as:
o ReceiveMessage
o ReceiveGroupMessage
o MentionNotification
o MessageSeen

5.3 Real-Time Message Delivery

When a message is sent:

P a g e 11 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

• SignalR sends it to the recipient using their user ID.

• If it’s a group message, SignalR broadcasts it to all members except the sender.

5.4 Message Seen Event

SignalR Event: MessageSeen

• Triggered when a user reads a message.

• Sends back the message ID and timestamp to the original sender.

5.5 Mention Notifications

SignalR Event: MentionNotification

• Triggered when a user is mentioned in a group message (using @email).

• Only mentioned users receive this notification.

5.6 Push Reactions

SignalR Event: MessageReacted

• Triggered when a message receives a reaction (emoji, etc).

• Notifies the original sender.

5.7 Unread Messages Notification

Endpoint: GET /api/Chat/getNotifications Returns:

• List of unread direct messages

• List of pending friend requests

5.8 Mark All as Read

Endpoint: PATCH /api/Chat/markNotificationsAsRead

• Marks all messages and notifications as read.

5.9 Group Unread Messages Count

Endpoint: GET /api/Chat/unreadGroupMessages

• Returns count of unread messages per group for the current user.

5.10 Global Notification Fetch

P a g e 12 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

Endpoint: GET /api/Chat/getAllNotifications

• Fetches all unread system notifications from a centralized table.

5.11 Mark Single Notification as Read

Endpoint: PATCH /api/Chat/markNotificationAsRead/{notificationId}

• Marks one notification as read.

Chapter 6: File Upload & Attachments

6.1 Overview

CampusHub supports file attachments within messages. This includes document sharing, image
sending, and download access, all integrated into the real-time chat flow.

6.2 Supported File Upload Flow

• Files are uploaded via a multipart/form-data request.

• Uploaded files are saved to the server under the /wwwroot/uploads/ folder.
• File metadata is stored in the ChatMessages table under the AttachmentUrl column.

6.3 Send Message with Attachment

Endpoint: POST /api/Chat/sendMessageWithAttachment Payload Type: Form Data

(message + file) Fields:

• ReceiverId: string (GUID)

• Message: string
• File: IFormFile (optional)

Server Flow:

1. Validate sender and receiver.

2. Save the uploaded file to disk.
3. Generate AttachmentUrl.
4. Save message + file path to database.
5. Trigger SignalR to notify receiver.

6.4 Receive Attachment in Chat

P a g e 13 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

When a message contains an attachment:

• AttachmentUrl is included in the SignalR event.

• Frontend displays the file preview or download link.

6.5 View All Attachments

Endpoint: GET /api/Chat/getMessageAttachments

• Returns all messages with non-null AttachmentUrl.

• Used to build an "Attachments Gallery" or "Files Tab" in chat.

6.6 Delete Attachment

Endpoint: DELETE /api/Chat/deleteAttachment/{messageId}

• Validates ownership by sender.

• Deletes physical file from disk.
• Removes AttachmentUrl from the message in the DB.

6.7 Security Considerations

• Files are stored in a non-public folder; access via generated download links.
• File names are randomized using GUID_filename.ext.
• Validation can be added for allowed file types (PDF, JPG, DOCX, etc).
• Limit upload size using server-side config.

6.8 Optional Enhancements

• Virus scanning via third-party API

• Image compression for uploaded photos
• File type icons and smart previews (PDF/image/video)

Chapter 7: Frontend – Pages and Flows

7.1 Overview

P a g e 14 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

The frontend is built using Next.js (App Router) with Tailwind CSS for styling. It provides a
responsive, modern, and accessible user interface for all features, including authentication, chat,
notifications, and group management.

7.2 Authentication Pages

7.2.1 Login Page

• Route: /login
• Components:
o Email input
o Password input
o reCAPTCHA (Invisible)
• Behavior:
o Sends credentials and captcha token to /Account/Login/login
o Stores access token in secure cookies
o Redirects to /dashboard on success

7.2.2 Signup Page

• Route: /signup
• Components:
o First Name
o Last Name
o Email
o Password (min 8 chars)
o reCAPTCHA (Invisible)
• Behavior:
o Validates all fields
o Sends data to /Account/Register/register
o Redirects to /verify-code

7.2.3 Email Verification Page

• Route: /verify-code
• Components:
o Email input (pre-filled)
o Code input
• Behavior:
o Sends data to /Account/VerifyCode/verifyCode
o Redirects to /login on success

P a g e 15 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

7.3 Dashboard Page

• Route: /dashboard
• Access: Protected via middleware
• Features:
o List of recent chats
o Unread message counter
o Navigation to chat or group sections

7.4 Chat Interface

• Componentized Layout:
o Sidebar: contacts and groups
o Main panel: conversation view
o Input: message text, emoji picker, upload button
• Supports:
o Real-time updates via SignalR
o Reactions, reply, pin, edit, delete
o File attachment preview

7.5 Group Management

• UI for:
o Creating groups
o Viewing members
o Adding/removing members
o Making members admin
o Leaving or deleting group

7.6 Notifications

• Dropdown UI accessible from header

• Shows:
o Unread messages
o Mentions
o Friend requests
• Clicking a notification opens the related chat/group

P a g e 16 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

7.7 UX Enhancements

• Loading spinners and error messages

• Dark theme styling (Tailwind dark mode)
• Form validations and toast alerts
• reCAPTCHA failure fallback handler

Chapter 8: Recommendations and Final Notes

8.1 Suggested Improvements

While CampusHub’s backend is fully developed and operational, the frontend is currently
limited to authentication (login and signup). The following recommendations can enhance the
system’s completeness, usability, and scalability in future iterations:

Security Enhancements • Rate Limiting Middleware: To prevent abuse and brute force
attacks.
• Account Lockout: Temporarily block login after multiple failed attempts.
• Audit Logs: Track user activity (logins, message edits, deletions).

Internationalization • Multi-language Support: Add Arabic, Kurdish, etc., using Next.js

i18n.
• RTL Support: Tailwind CSS can be extended for right-to-left layout.

AI/Smart Features • Auto-Moderation in Groups: Detect bad words or spam messages.

• Message Summarization: Automatically summarize long messages using OpenAI or Hugging
Face APIs.
• Recommendation Engine: Suggest users to connect with based on common groups or
interaction frequency.

System Extensibility • Plugin Support: Allow universities to add custom plugins for
surveys, polls, or academic integrations.
• API Rate Limits per Role: E.g., guests vs registered users.
• Modular Microservices: Split chat, auth, and notification into services for scaling.

P a g e 17 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

Admin Dashboard • User Statistics: Active users, top senders, message volume.
• Message Analytics: Emoji usage, peak hours, group activity heatmap.
• Moderation Tools: View flagged messages, block users.

8.2 Deployment Best Practices

• Use Docker for consistent backend deployment.

• Enable HTTPS (already configured via Nginx + SSL).
• Automate backups of PostgreSQL.
• Monitor usage with Prometheus + Grafana or third-party tools.

8.3 Future Feature Ideas

• Complete UI development: implement chat interface, inbox view, group management pages.
• Voice & Video Chat Integration.
• Event Scheduling and Reminders in Groups.
• Status (Online/Offline/Busy).
• Advanced Search Filters (file type, date, sender).
• Custom Stickers or Emoji Packs.

Acknowledgments
I would like to express my sincere gratitude to all those who supported me throughout the development
of the CampusHub project.

Special thanks to:

• [Dr. Wameed] – for continuous guidance and constructive feedback.

• My teammates and friends – for their moral support, testing help, and brainstorming sessions.
• University staff and faculty – for providing the academic environment and resources necessary
to complete this work.
• My family – for their patience, encouragement, and endless motivation during this journey.

This project would not have been possible without your valuable support.

P a g e 18 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

Glossary
Term/Abbreviation Description
JSON Web Token – used for secure, stateless user
JWT
authentication
Application Programming Interface – communication
API
between frontend and backend
reCAPTCHA A Google service that protects sites from spam and abuse
ASP.NET library for real-time web functionality using
SignalR
WebSockets
A communication protocol for full-duplex real-time data
WebSockets
between client and server
A React-based framework for building server-side rendered
Next.js
web applications
Tailwind CSS A utility-first CSS framework for building modern UIs
PostgreSQL An open-source relational database management system
HTTPS Secure version of HTTP, encrypted via SSL
A long-lived token used to obtain a new access token
Refresh Token
without logging in again

Sources & References

1. ASP.NET Core Documentation
https://learn.microsoft.com/en-us/aspnet/core
2. SignalR – ASP.NET Core Real-time Communication
https://learn.microsoft.com/en-us/aspnet/core/signalr/introduction
3. Next.js Documentation
https://nextjs.org/docs
4. Tailwind CSS Documentation
https://tailwindcss.com/docs
5. PostgreSQL Documentation
https://www.postgresql.org/docs/
6. Google reCAPTCHA API Docs
https://developers.google.com/recaptcha/docs/v3
7. JWT.io – JSON Web Token Introduction
https://jwt.io/introduction
8. OpenAI Documentation (for future AI features)
https://platform.openai.com/docs

P a g e 19 | 20
Al-Mamoon University College – Department of Computer Engineering Technology
CampusHub - Graduation Project | By Laith Adel

9. Hugging Face – NLP Models and APIs

https://huggingface.co/docs
10. Docker Docs – Deployment & Containers
https://docs.docker.com/

Personal Reflection
Working on CampusHub has been an incredibly rewarding experience. This project allowed me
to apply my knowledge of full-stack development in a real-world scenario that touches on real-
time communication, user experience, and security.

I faced many technical challenges — from managing JWT token flows to implementing SignalR
for live updates. However, these hurdles helped me grow significantly as a developer. I also
gained a deeper understanding of authentication, state management, and secure backend
practices.

Beyond the technical skills, this project taught me the importance of planning, communication,
and perseverance. I am proud of what I have built and excited to continue learning and building
more complex systems in the future.

Index
• Chapter 1 – System Overview ........................................... Page 2

• Chapter 2 – Backend – Authentication System .................. Page 3

• Chapter 3 – Backend – Chat and Message Flow ................. Page 5

• Chapter 4 – Group Chat System ....................................... Page 8

• Chapter 5 – Notifications & SignalR .................................. Page 11

• Chapter 6 – File Upload & Attachments ............................. Page 12

• Chapter 7 – Frontend – Pages and Flows ........................... Page 14

• Chapter 8 – Recommendations and Final Notes ............... Page 16

• Acknowledgments ........................................................... Page 18

• Glossary .................................................................... Page 19

• Personal Reflection .......................................................... Page 20

P a g e 20 | 20
Al-Mamoon University College – Department of Computer Engineering Technology