This page will introduce you to Freerooms. It will cover what features we currently have, help you understand the codebase better and go through how to setup your environment to develop and run Freerooms locally.

What is Freerooms?

Freerooms is a tool to help UNSW students find free rooms on campus. In the currently deployed v1 frontend, we are able to choose from a gallery of buildings, see which rooms are available given a time slot and show the timetable for that particular room from Monday to Friday.

Open

Gallery

Open

List of rooms

 

Open

Timetable

Our new v2 frontend consolidates all the above information into a single page for a smoother user experience and introduces the ability to search for specific buildings, filter and sort by a variety of criteria and see each of the buildings laid out on the map.

Open

Room list condensed into a side panel

 

Open

Filter, search and sort

 

 

Open

Map

 

Architecture Guide

Currently the repo is divided into four main directories for the backend, and both the v1 and v2 frontends and the mobile app.

v1 Frontend

v1 is the one currently deployed at http://freerooms.csesoc.app, unless you’re working on porting one of the features over to v2 you probably don’t need to look at it much. The code for this is found in the frontend folder, which has been developed using Vue.js and is written in TypeScript. Within the frontend/src folder, we are able to see the following folders:

• views: Contains Views, the pages of the site, what the end-user sees online

• components: Contains small, reusable pieces of code which can be inserted to any View

• assets: Contains all images the site requires

• models: Contains definitions of classes and interfaces which are used to define objects and maintain type safety, as well as a list of all locations

• plugins: Defines the colour scheme for the website and the types of icons used (Material Design)

• routes: Defines the various valid URLs and the corresponding View to display

• services: Contains APIs to the backend

v2 Frontend

v2 is the one currently on staging at https://freerooms.staging.csesoc.unsw.edu.au/ and has been the focus of the 2022 team. The code for this is found in the v2/frontend folder and has been developed React with Next.js and is written in Typescript. Within the v2/frontend folder, we are able to see the following folders:

• components: Contains small, reusable React components

• config: Declares some important constants used throughout the frontend

• hooks: Contains custom React hooks

• pages: Contains each of our Next.js pages (currently there is only one)

• styles: Contains our CSS stylesheets

• views: Contains larger scale components e.g. list view, map view

Backend

Both the v1 and v2 frontend use the same backend. The code for this is found in the v2/backend folder. The backend has been developed using the Express framework and is written in TypeScript. Within the v2/backend/src folder we can see the following files:

• src: Contains all the code for the backend

  • index.ts: Declares the various routes and middleware (e.g. error handling) for the server

  • service.ts: Contains functions called to retrieve the data for each endpoint, and also some functions for parsing request parameters

  • helpers.ts: Contains general helper functions e.g. fetching data, date manipulation

  • scraper.ts: Contains the implementation for our scraper that extracts data about all the CATS rooms and buildings

  • config.ts: Declares some important constants used throughout the backend

  • types.ts: Contains the type definitions for all user-defined types

• database.json: Contains the building and room data we scrape

The backend also currently makes heavy use of the data from CSESoc’s timetable scraper, which we share with Notangles. Its implementation can be found at GitHub - devsoc-unsw/timetable-scraper: A scraper and public API for UNSW's timetable site and the API documentation can be found at https://devsoc.atlassian.net/wiki/pages/createpage.action?spaceKey=N&title=Timetable%20Scraper%20API.

Mobile App

INSERT STUFF HERE

Other files

There are various config files found in each of the directories, you probably won’t be working on them but it’s good to know what they do.

• package.json: The necessary packages required for the project and the aliases for the pnpm start, pnpm dev etc. commands

• pnpm-lock.yaml: Details the exact steps taken by pnpm to install all packages and their dependencies, important for deployment

• .gitignore: The files and folders not to be committed to Git, such as node_modules

• .prettierrc: The configuration for the Prettier extension which you can use to format your code

• tsconfig.json: The rules defining how to transpile the Typescript code into JavaScript during the build process

• Dockerfile: The instructions on how to create a Docker image from the code in the folder

• dockerignore: The files not to include in the Docker image

• renovate.json: The rules for our automatic package updater

Set-up & Installation

Tools

You will need to install some or all of the following tools to develop Freerooms.

• Git

  • duh

• Node.js

  • The JavaScript runtime used by our web app (and most other web apps)

  • You probably already have this installed but you can download it here: Node.js — Download Node.js®

• pnpm

  • The JavaScript package manager we use which is faster and simpler than npm

  • You can follow the instructions here to install: Installation | pnpm

  • Don’t use npm to install packages please, here’s a cheat sheet for common npm commands in pnpm

Running Freerooms Locally

For the backend, in the v2/backend folder

• To install all packages, use the pnpm icommand

• To run, use the pnpm start command

For the v1 frontend (doesn’t use pnpm), in the frontend folder:

• To install all packages, use the npm install command

• To run, first run the backend then use npm run serve command

For the v2 frontend, in the v2/frontend folder:

• To install all packages, use the pnpm i command

• To run, first run the backend then use the pnpm dev command

For the mobile app INSERT MOBILE STUFF HERE