CollegeGuide

Version: 1.6

Authors:

Adrian Szydlo
Jake Farrell

Created: 13/02/2025

Last Modified: 21/02/2025

Table of contents
1. Introduction
2. System Features
- 2.1 Overview
- 2.2 Functional Requirements
3. System Architecture
4. High-Level Design
5. Problems and Resolution
6. Testing and Validation
7. Installation Guide

1. Introduction

1.1 Overview

This technical specification outlines the functionalities, requirements and design for CollegeGuide: a web-based student companion platform aimed to connect, simplify and interconnect student lives across Ireland. This platform provides a set of useful academic tools with the focus of a “by students, for students” approach by combining on-demand chatbot assistance and deeper, community-driven interaction features on dedicated module-based community boards. It is intended to work alongside existing online learning platforms, such as DCU’s Loop, extending a student’s options in digital solutions.

1.2 Purpose and Scope

This specification outlines the technical design of CollegeGuide, in particular:

System architecture and components
High-level design
Problems encountered and respective solutions
Testing and validation
Manual and Docker installation guide

The document will emphasise how the details of the Functional Specification were implemented, and what changes occurred in the process. This aims to provide a comprehensive understanding of the platform and to guide future development and deployment for developers, engineers and stakeholders.

1.3 Glossary

Below are some explanations of terms used in CollegeGuide that may not be immediately obvious:

Community Board - A space for interaction and features relevant to a module, accessible to all users, moderated by programme administrators or class representatives.

Community Board Moderator - Generally referred to as just “Moderator” throughout the document. It represents any user within a community board with special administrative privileges for said community board, assigned by the main system administrators.

Discussion Thread - Refers to a live discussion thread in a community board, made by a Moderator, which centres around a topic that can be collectively discussed by only the members of the community Board.

Advice Query - Refers to a live discussion thread in a community board, made by any user, whether a member or not, seeking information from members within the community board.

Chatbot - A simple artificial intelligence agent that responds to user’s prompt, providing an appropriate response given current information about the querying user and relevant knowledge base.

Experience Points - Abbreviated to “XP” throughout the document. This is a reward system to rank the engagement of users across the platform. Utilising certain features of the platform may award said XP.

Badge - A digital award associated with a user’s profile that can be displayed on their profile page, generally given for achieving a certain experience point amount or a statistic.

2. System Features

2.1 Overview

Figure 1 below shows a brief visual of how the system works on the frontend, as seen by a typical user. Note that not all features nor relationships can be fully represented due to the complexity of the application and the focus on a more simplified visual.

Figure 1. System Overview Diagram displaying a typical student user’s interaction with the system and how these features correlate. A group of symbolic student users represents the system-wide features applying to all users.

The primary features of CollegeGuide are found in the community boards associated with each module. A student can be a member of said board if they are part of that module. These include:

Discussion Threads: module-relevant discussions made by class representatives that any module member can respond to. These can be archived once the discussion is no longer relevant.
Advice Queries: module-relevant queries posted by any student and answered by module members.
Module Notes: module-relevant markdown notes posted by module members.
Partner Matcher: contains queues for the module created by class representatives based on current projects or events. Module members can join said queues and be matched algorithmically based on their profiles.

Any student can view any community board, however they can only post advice queries on the ones they are not a member of.

All student users have access to system-wide features that exist beyond the community-board-centred components. A user must only be authorised and verified to use said features. These include:

Chatbot: provides quick, relevant answers to student queries by receiving the information of a student from the system.
Timetable: contains a lecture/lab timetable relevant to the student scraped from a college’s official API.
Campus map: utilises OpenStreetMap API to provide the map of a student’s campus.
Leaderboard: displays the ranking of student’s based on their current level and experience.

Finally, an experience system aims to promote engagement on the platform. Achievements such as leveling up to certain levels provides users with badges that are displayed on their profile. This is complimented with the previously mentioned leaderboard to enforce a sense of recognition and friendly competition between students.

CollegeGuide is currently publicly accessible under the following URL: https://collegeguide.jakefarrell.ie/

2.2 Functional Requirements

This section aims to compare the differences in functional requirements from CollegeGuide’s Functional Specification and provide a more concrete explanation of their implementation. These functional specifications are paraphrased and re-arranged from the Functional Specification for clarity purposes and to reflect the focus points of the project.

2.2.1 Managing Community Boards

Community boards are manageable by class representatives and system administrators through appropriate administrative tools. Introduced are privilege levels for users to determine moderation power and selectively display elements on the frontend, such as a “Create Discussion Thread” button; profanity filters that simplify moderation tasks through automated swear word obfuscation; and a frontend administration dashboard for modifying modules, years and programmes. As of writing this documentation, non-members of a community board have been replaced with visitor roles applied to students not part of a year. A senior role has not been implemented.

2.2.2 Interacting with Advice Queries

Advice queries can be viewed and created by any student and answered by only the module members in which an advice query was posted. An advice query cannot be made anonymous nor does it notify the poster via email if an answer was submitted. These features became stretch goals beyond the scope of the core vision of CollegeGuide to be achieved given the time constraints. Posting an advice query will provide the poster with an experience reward to encourage inter-module engagement. Comments posted on advice queries can be liked or loved by any student.

2.2.3 Interacting with Discussion Threads

Discussion threads can be viewed by any student, created only by module moderators and answered only by module members. The commenting facilities do not have robust spam filtering capabilities. Comments posted on discussion threads can be liked or loved by any student.

2.2.4 Interacting with Module Notes

A student may create public or private Markdown notes relevant to a module that may be viewable by any student if public. Students can like or love said notes. The student is not able to upload files as notes nor are they informed of any supported formats. A student is provided with experience points when submitting notes to encourage module contribution.

2.2.5 Using the Partner Matcher

The matcher consists of queues for a module which can be created by moderators, joined or left by any member of said module, and have matching capabilities for queue members that are invoked manually or automatically when queue deadline is reached. Once the deadline is reached, no more students can join, leave or manually match in a queue. All students are emailed their top matches when the queue deadline is reached. Matches are determined using an algorithmic comparison of student profile information. The algorithm does not account for proximity to the deadline. Students cannot provide feedback on their matches through the partner matcher, only by direct contact with administrators.

2.2.6 Querying the Chatbot

Chatbot promptly responds to user queries with information relevant to their student profile. The Chatbot can determine different categories of queries by keyword analysis and respond with appropriate information. Students receive experience points for querying the Chatbot to encourage its use. Quick prompt buttons allow for a single-click responses from the Chatbot for relevant academic questions.

2.2.7 Engaging with a User Profile:

A student profile displays relevant information to them and their current academic status. These profiles can be set as publicly viewable by other students or as private. The user profile is accessible from the navbar at the top of all web pages or from a dedicated section in any community board. Experience, levels, badges, posts, joined queues and notes can all be viewed in a student profile.

2.2.8 Engaging with the Reward System

Students are able to receive experience points, levels and badges. Students can like or love comments, notes and posts of other students. Any student may view their experience or the experience of others (given they set their profile as public) through the profile of that student user. The system does not support marking comments as “helpful”. Milestone badges are awarded to students that reach a certain level.

2.2.9 Other Functional Requirements

Additional functional requirements which have been met but not covered in the Functional Specification include:

Shall be able to register and login with a student email that must be unique (and to verify said email).
Shall be able to view leaderboards of all users that must be ranked by level and experience.
Shall be able to view a campus map relevant to the student.
Shall be able to use the web platform on mobile through responsive design support.

3. System Architecture

3.1 Overview

The CollegeGuide web platform architecture follows a traditional full-stack approach. It contains a user interface accessible via web portal and mobile devices running on a React frontend, and a Django-powered backend concerned with user handling, data processing, API requests/responses and data management using an SQLite database.

Figure 2. System architecture diagram which represents the interaction between frontend and backend components. Dotted lines represent direct interactions between frontend and backend.

The system architecture diagram, seen in Figure 2, above shows the component layout and communication within the current CollegeGuide architectural as opposed to the Functional Specification’s version of the same diagram. Most components interact on the frontend with the backend’s Axios API handler to display appropriate data from the database and third-party APIs.

Some frontend components, such as the Partner Matcher and Chatbot, interact with the backend directly. However, these also require the Axios API handler to find the appropriate backend functions. The Celery Beat Scheduler maintains some regular tasks such as checking if a Matcher Queue reached its deadline or a user is unverified for too long.

The frontend Navbar component provides a user with access to system-wide features or profile page. By default, a user is navigated to a view of all of their community boards, each of which may be accessed to reach that board’s respective features.

3.2 Frontend Architecture

The client-side aspects of the platform are built using React and JavaScript for a dynamic, responsive user interface (UI). Additionally, this is accelerated using Vite for fast hot-reloading and build performance. Tailwind CSS is used for simplifying CSS and handling the mobile responsive design, allowing for the platform to be used on smaller displays, such as mobile phones.

3.3 Backend Architecture

The server-side foundations are handled using Django with the REST framework. This includes platform logic, user authentication and API integration. Axios is used to handle API requests and responses between the backend and frontend. JWT tokens are used for handling session and access token states for user authentication. These are also passed into the frontend for user detail retrieval. The Celery Beat scheduler provides an ability to run periodic backend calls for system state and model checking. An SQlite database offers a light and fast data management solution and acts as the interface between all data-handling components of the application.

3.4 External Services

In order to provide some component functionality, we relied on existing solutions.

REST API: used with Django to provide an easier backend handling solution for powerful Web API management.
OpenStreetMap: provides a detailed campus map view, currently supported for the DCU Glasnevin Campus.
SBERT Machine Learning Model: used to evaluate profile bio comparisons for the Partner Matcher Algorithm.
Groq Cloud: large language model framework for the Chatbot.
Celery: provides periodic task scheduling in the backend.

4. High-Level Design

4.1 Class Diagram

The CollegeGuide platform follows a structured data model that connects students, modules, community boards, and engagement features. The below class diagram visually represents the key entires in the system and their relationships.

Figure 3. Class Diagram representing the object-oriented design of each major backend component. Pale green elements comprise user and profile elements, light blue entail community board features, orange represents the core academic elements and gray are system-wide features.

Figure 3 shows a class diagram which describes the object-oriented approach to CollegeGuide’s design. Each object is part of a respective class which shows its scope of attributes, operations and relationships with other object classes. This is a modification from the Functional Specification’s version with up-to-date classes and relations.

4.2 Use Case Diagram

Figure 4. Use Case Diagram for a student, moderator and administrator users interacting with the CollegeGuide system.

The above Use Case Diagram describes the typical flow of use cases and capabilities per user type. The colour code vaguely represents the Class Diagram for correlations where useful.

A student user has the lowest privilege level and can participate in the system once they are email-verified. Typical use cases are distributed between the three core use cases which are: interacting with the community boards, viewing user profiles and using the chatbot. For a deeper understanding of their interactions, one can look back at the previous diagrams in Section 4.1 and 3.1.

A moderator inherits all the capabilities of a typical student user, with the additional function of creating discussion threads and matcher queues in the Community Boards they moderate. An administrator can do what any student or moderator can do, with the additional ability to modify college details for students, be it college, programme, year or module information.

4.3 User Interface and User Experience (UI/UX)

Significant focus has been dedicated on ensuring adequate UI/UX principle incorporation. The main idea was to provide an engaging and visually appealing platform, while also offering simplicity and clarity of navigation. Figure 5.1 and Figure 5.2 below show two wireframe examples as initial website design mock-ups.

Old Layout 1 Figure 5.1. First wireframe iteration of a community board page.

Old Layout 2 Figure 5.2. Second wireframe iteration of a community board page.

Initial focus was placed on making sure each component within the community board was distinct and clearly separated. A navigation bar on top aimed to provide quick access to system-wide features and the student profile. This design has evolved to the final product as seen in Figure 6.1, which still maintains a vague similarity to the original idea.

Figure 6.1. Current design of the community board.

Similar focus was placed into all areas of CollegeGuide’s user interface, such as the modules view (Figure 6.2) or partner matcher (Figure 6.3). We aimed to maintain a similar feel and colour scheme throughout the app with a light and cheerful palette.

Figure 6.2. Current design of the modules view, each module being an access point to its respective community board.

Figure 6.3. Current design of partner matcher interface.

Additionally, the application has been tested with responsive design principles in mind thanks to Tailwind’s grid features. This means that CollegeGuide can be used on both desktop and mobile as seen in Figure 6.4.

Mobile View

Figure 6.4. Example modules view on a mobile device.

5. Problems and Resolution

5.1 SQLite Database Limitations

Problem: Django comes natively with an SQLite database. This is a perfect, light-weight solution for small applications with not a lot of data to handle. However, the system experienced long load times and inefficiencies when we began to simulate larger volumes of posts, users and interactions after generating samples to test the system as if it was it was published and in operation.
Solution: We have evaluated different database solutions, such as MySQL and PostgreSQL. The former offering reliability and speed ideal for a large volume of simple queries, as is the case with our web application. The latter offers more data integrity, features and extensibility. However, the change of database was not in scope for the project, and is more of a future design decision. We are also exploring further optimisations through load balancing across several database instances. However, as of now, SQLite is still our database of choice with capabilities sufficient for the project scope and demonstration.

5.2 JWT Authentication and Session Management Challenges

Problem: Managing JWT tokens and ensuring seamless authentication may cause problems when tokens expire. We experienced frequent “401 Unauthorized” errors during initial implementation phases. These predominantly occurred due to token expiration not being handled properly.
Solution: Integrated a current time versus token expiration time check into our custom useUser hook which handles logged in user token verification and state handling. This solution, alongside further testing and monitoring, reduced “401 Unauthorized” errors across the website.

5.3 API Rate Limiting

Problem: After performing user testing described in Section 6.3, we discovered users being able to make unrestricted amounts of POST requests to the backend which poses a backend overload risk as the userbase scales. Additionally, this means that the system is vulnerable to Distributed Denial of Service (DDoS) attacks.
Solution: A POST request limiting middleware was implemented on the backend to limit the per-user POST request instances per minute to 10. Requests exceeding this threshold are automatically rejected with a “429 Too Many Requests” response. This ensures that system resources are available for all users.

5.4 Data Migration Issues

Problem: When performing data migrations using Django’s manage.py functionality, we ran into invalid entry collisions and databases not migrating properly. Adding fields to existing models did not necessarily add corresponding columns in the database.
Solution: We have come up with several troubleshooting steps shared between us. One of these was to enter the backend/migrations/ folder and remove all existing migrations except for the initial one. Another way was to remove the field that was causing errors in the latest migration file and re-migrate so the database treated the field as not yet applied and re-applied it. Lastly, if none of the above worked, we entered the database manually using sqlite3 db.sqlite3 on a WSL instance and edited the database entries manually. This procedure was something we learned through trial and error as these problems arose. Previously, we would wipe the database, but given the amount of information needed to populate it, it would be too inefficient to restart it with every small error.

5.5 Gathering Module Data via Web Scraping

Problem: We initially gathered the module and programme data from the DCU ModSpec page using web scraping. Unfortunately over the course of the development of CollegeGuide, the ModSpec page was updated and the view where you could see all years and modules in a particular programme was removed.
Solution: Luckily we had a backup of the saved json data we received from the ModSpec page before it was updated. We used this data for any updates to the modules, years and programmes in CollegeGuide. The file can be found in our backend directory, alternatively we could have pulled the data from the Wayback Machine.

5.6 Usage Limits of the Groq Cloud Free Tier

Problem: For the Groq Model we are using, llama-3.3-70b-versatile, the limit on Tokens Per Minute (TPM) is 6000. This can result in queries not being responded to due to the limit being reached.
Solution: We limited the max tokens to 1000, with most chatbot queries not exceeding this. We also implemented a system that allows users to clear their chat history in case they reach the max token limit with their previous responses. If we were to launch this commercially, would switch to a paid tier to remove these limitations.

6. Testing and Validation

6.1 Unit Testing

Unit testing has been used throughout the CollegeGuide development process to ensure that when any changes were made to the code, the system would still function as expected. Tests were both carried out manually in our local development environments, as well as automatically using Gitlab CI/CD pipelines.

We kept a clean git repository where all of our development work was done on a separate development branch, with any merge requests into main being required to have passed all tests. This ensured that the main branch was always in a working state, and that any changes made to the codebase would not break any existing functionality once deployed for production.

6.1.1 Backend Testing

We used Django’s built-in testing framework, along with API specific features provided by Django Rest Framework to carry out our backend testing. In total we have 33 tests running on each commit to both our production and development branches. Tested features include:

Creation of various database models for users, modules, programmes, years, colleges
Testing of API endpoints for user registration, login, refreshing authentication tokens, verification of emails, profile creation
Testing of API endpoints for note creation, discussion thread and advice query creation along with replying
Testing of external APIs such as Groq Cloud for the ChatBot and TimetableSync for retrieving DCU timetable data

Our Gitlab CI/CD pipeline for testing the backend:

backend-test:
  image: python:3.12
  stage: test
  script:
    - cd code/backend
    - python3 -m pip install --upgrade pip
    - pip install -r requirements.txt
    - python3 manage.py test

Screenshot of Backend Tests

Figure 7.1. Screenshot of CollegeGuide backend tests.

6.1.2 Frontend Testing

To test the frontend of our application, we used Vitest, a testing framework specifically designed for Vite applications like ours, with Jest support included. We have 10 tests running on each commit to both our production and development branches. Tested features include:

Main components vital to CollegeGuide’s functionality, such as the Registration and Login Process, and Navigation Bar
Other smaller components such as the leaderboard, Footer, and the Badge display

Our Gitlab CI/CD pipeline for testing the frontend:

frontend-test:
  image: node:22.12.0
  stage: test
  script:
    - cd code/frontend
    - npm install
    - npm run test

Screenshot of Frontend Tests

Figure 7.2. Screenshot of CollegeGuide frontend tests.

6.1.3 Pipeline Explanation and Testing Coverage

Both the frontend and backend test pipelines run on every commit to the Gitlab repository, ensuring that any changes made to the code do not break any existing functionality. If any of the tests fail to pass, the pipeline will fail and we will be notified via email alerts. The code first sets up the required environment variables from GitLab’s secret manager, then installs the required dependencies and runs the tests.

Unfortunately, due to the scale of our project we were unable to implement 100% of unit test case coverage, but to combat this we rigorously tested the project ourselves continuously throughout the project, and had help from our user testing participants to find issues and discover bugs.

With more time we would have liked to implement a more complete testing coverage, but we are happy with the current amount of testing done.

6.2 Integration Testing

Our integration testing took place in the form of building docker images of both the frontend and backend using GitLab CI/CD pipelines. Then pulling the latest build on Jake’s home server to test the application in a production environment.

Once the latest image was deployed, we could log into the site from any device, mobile or desktop, and test the features. We also set up a status page to monitor system uptime, and to alert us if the system went down for any reason.

Status page link: https://status.jakefarrell.ie/status/collegeguide

Status Page

Figure 7.3 Screenshot of the CollegeGuide status page.

Our Gitlab CI/CD pipeline for building and pushing the docker images:

build-backend:
  image: docker:20.10.11
  stage: build
  script:
    - cd code/backend
    - docker build -t ghcr.io/$GH_REGISTRY_USER/collegeguide-backend .
    - docker login -u $GH_REGISTRY_USER -p $GH_REGISTRY_PASSWORD ghcr.io
    - docker push ghcr.io/$GH_REGISTRY_USER/collegeguide-backend

build-frontend:
  image: docker:20.10.11
  stage: build
  script:
    - cd code/frontend
    - docker build -t ghcr.io/cheeselad/collegeguide-frontend -f Dockerfile --build-arg VITE_API_URL="https://collegeguide-api.jakefarrell.ie" .
    - docker login -u $GH_REGISTRY_USER -p $GH_REGISTRY_PASSWORD ghcr.io
    - docker push ghcr.io/$GH_REGISTRY_USER/collegeguide-frontend

These work similar to the unit testing pipelines, but instead they build production ready docker images of the frontend and backend, and push them to the GitLab container registry. These images are then pulled and run on Jake’s home server for testing and deployment.

6.3 User Testing

The first production-ready version of CollegeGuide was subject to user testing in order to evaluate the next steps for development and design. A small group of 6 DCU students has participated, with 10 minutes spent per student. We allowed students from DCU to access the web application’s public domain with a sample user account. The students were guided on the available features in order to gather first impressions. An anonymous questionnaire was then offered to those interested in providing feedback.

Additional explanations to each choice were required in order to better understand the background of each opinion. In general, the reception was positive among all student participating and some student filled out the questionnaire with some helpful insights.

Students liked the layout and clarity of all components on the website, one stating: “Whenever I looked for an element, I found it greeting me in the precise position that I had looked”. Another student complimented the profile: “Good integration of personalisation and could see this being useful for students”.

A core criticism was the functionality of the Chatbot, with one response stating: “Overall excellent, some minor issues with the AI chat features”. The loading times of the website were also mentioned due to still using SQLite at the time, as mentioned in Section 5.1.

This user testing has mainly reinforced our satisfaction with the UI/UX principles applied to the web pages as mentioned in Section 4.3 and guided us on next steps in deployment. The user testing also revealed the typical use case patterns and some overlooked vulnerabilities, as mentioned in Section 5.

7. Installation Guide

The below guide will detail the process of how to run CollegeGuide on a local machine.

7.1 Prerequisites

Software requirements:
- Python 3 (tested on version 3.13.1)
- git
- Node.js* (tested on version 22.12.0)
- npm*
- A Chromium-based or Firefox-based browser
It is recommended to use nvm (for Linux) or nvm-windows (for Windows)
Hardware requirements:
- Windows 10 or 11 Machine*
- 8GB of free disk space
- Internet connection

Also tested on Linux Debian version 12.

7.2 Manual Install Instructions

1. Open a new terminal and ensure your prerequisites are available and up-to-date by typing in the following:

$ node -v       # checks node version
$ npm -v        # checks npm version
$ git -v        # checks git version

Note: You may need to close and re-open your terminal if you just installed any of the above to run with the latest environmental variables.

2. Clone the CollegeGuide Gitlab repository into a folder of your choice:

$ cd C:\path\to\folder     # replace the path with your desired path
$ git clone https://gitlab.computing.dcu.ie/farrej88/2025-csc1049-jfarrell-collegeguide.git

Note: This is an Internal Gitlab repository, hence only users with a login to the DCU Gitlab can clone it. Contact [email protected] or [email protected] for further details.

3. Navigate to 2025-csc1049-jfarrell-collegeguide\code\backend (backend path) and run:

$ pip install -r requirements.txt

Note: You can move on to Step 4 while this is downloading.

4. In another terminal instance, navigate to 2025-csc1049-jfarrell-collegeguide\code\frontend (frontend path) and run:

$ npm install

5. Once both are installed, in \backend, create a new file called .env (if it does not exist already) and add the following into it:

export AI_API_KEY=<GROQ_API_KEY>
export SECRET_KEY=<DJANGO_SECRET_KEY>
export DEBUG=True
export EMAIL_HOST_PASSWORD=<EMAIL_ACCOUNT_PASSWORD>
export BASE_URL=http://localhost:8000

Make sure to replace the keys and password with your correct values. Save the file!

6. While in the same backend path, run:

$ python manage.py makemigrations
$ python manage.py migrate

7. Finally, in the same path, run:

$ python manage.py runserver

Navigate to the URL displayed in terminal, e.g. http://localhost:8000/.

8. Go to \frontend in your other terminal and create a new file called .env (if it does not exist already) and add the following into it:

VITE_API_URL="http://127.0.0.1:8000"

While in the frontend path, run:

$ npm run dev

Similarly, go to the URL displayed, e.g. http://localhost:5173/.

7.3 Docker One-Command Install Instructions

1. Clone the CollegeGuide Gitlab repository into a folder of your choice:

$ cd C:\path\to\folder     # replace the path with your desired path
$ git clone https://gitlab.computing.dcu.ie/farrej88/2025-csc1049-jfarrell-collegeguide.git