BaLance is a tool for teaching associates to split student cohorts into well Balanced teams that gel well together and work productively.
It makes use of student personality data to determine the optimal team formations and provides a variety of team formation strategies for teaching associates to select from.
The application offers three methods for forming teams:
-
Belbin Personality Method: This method categorizes students by Belbin team roles, where student are categorised as either people, thinking or action.
-
Effort-Based Method: This approach assesses the hours students are willing to commit to group work, pairing student together with same work ethics.
-
Project Preference Method: This strategy lets students indicate their project preferences with submission time serving a first come first serve basis.
These strategies allow teachers to select the most suitable approach based on their unique cohort dynamics, ultimately enhancing the learning experience for students.
- Software Requirements
- Setup Guide
- Deployment
- Git Quality Assurance
- Features
- Development guidelines
- Contributors
MERN architecture:
- MySQL Ver 8.1x(database)
- Express.js (backend)
- React Ver 18.x (frontend)
- Node.js (runtime)
- Docker (containerisation)
- Auth0 (Authentication)
- Railway (deployment)
- Google Service accoutn (API functionality with service account)
- Google forms API
- Nodemailer
-
MySQL: Download Youtube guide: https://www.youtube.com/watch?v=u96rVINbAUI&feature=youtu.be
NOTE: When setting up your root account and password, be sure to keep them somewhere as it will be important in setting up the app workbench connection. Forgetting may require you to reinstall MySQL or may completely bar you from being able to set up the application. -
Docker: [Windows] (https://docs.docker.com/desktop/install/windows-install/) [Mac] (https://docs.docker.com/desktop/install/mac-install/). If on mac or linux[debian] you could use terminal
brew install docker sudo apt install docker.io -
Node.js Download the Node.js installer from Node.js — Download Node.js® and run it.
-
Clone the repo:
git clone https://github.com/Monash-FIT3170/BaLance-Team-Forming-Dashboard.git; cd BaLance-Team-Forming-Dashboard/ -
MySQL
- Open up your MySQL workbench and create a new MySQL connection, using the default settings is fine.
- Create .env files in the frontend and backend folders in the below format. Change the DB_PASSWORD to your MySQL root account’s password. If you did not use root as your root account’s username, change DB_USER accordingly.
- Open the MySQL Terminal/ MySQL Shell and type in the following command:
source <absolute path>/schemaCreation.sql;NOTE: if copying the path from vscode, explorer, etc. all back slashes ‘\’ must be replaced with forward slashes ‘/’ - Connect to your database:
mysql -h host_address -u user_name -p pass_word < schemaCreation.sql;
-
npm depencencies:
cd backend npm i cd ../frontend npm i -
Google Service Account Creation:
- In the Google Cloud console, go to the Create service account page.
- Go to Create service account
- Select a Google Cloud project.
- Enter a service account name to display in the Google Cloud console.
- Done
To utilise the account you need to create a key:- Click on the account, shown in the previous step
- Go to the keys tab
- Add key Note: This will download a json file. Store this in the backend env file as a string
-
Auth0 Guide QuickStart : https://auth0.com/docs/quickstart/spa/react/interactive . Take note of the audience parameters
Run the frontend and backend from their respective directories
cd backend; npm run start
cd frontend; npm run start
Required environment variables:
In /backend/
MYSQLPORT=
MYSQLHOST=
MYSQLUSER=
MYSQLPASSWORD=
MYSQL_DATABASE="student_group_db"
AUTH="TEST"
GOOGLE_SERVICE_ACCOUNT_TOKEN =
AUTH_DOMAIN=""
In /frontend/
VITE_REACT_APP_AUTH="TEST"
VITE_REACT_APP_AUTH_CLIENT_ID=
VITE_REACT_AUTH_DOMAIN=
VITE_BACKEND_URL=""
Note: VITE BACKEND URL should be localhost:8080 if running on local or the backend public url if deployed
An existing docker-compose can be used however, it must be noted the database must be run from your local device as an existing image has not yet been implemented.
This application was deployed on railway on their free tier: https://railway.app/
Quick guide on learning railway can be found here: https://docs.railway.app/quick-start
Setting up BaLance:
- Deploy from Github Repo (If you have linked your github account, you can find the Balance repo )
- In the architecture view, click on the repo block
- Under the Source, click on Add Root Directory. Set it to "/frontend" Change the "Branch connected to production" from main to deploymentBranch (optional). Generate domain (this will be the public url). Click out of the block
- Top right, create -> Github Repo -> Balance
- Under source, click Add Root Directory. Set it to "/backend" Change the "Branch connected to production" from main to deploymentBranch (optional). Click out of the block
- Top right, create -> database -> mysql. This will create a mysql instance. (Note: if you would like specific version, you can click on the settings and change the source image to another docker image)
- Next steps are to connect the backend to the database via variable references. Click on MySQL instance-> variables -> copy database, host, password, port, user variables and add them to the backend service. This is also where env file variables are added.
- Add necessary env variables to both frontend and backend services
Note: The deployed backend and frontend do not run the schema creation script. If needed to be run, it is recommended to connect to the online database via terminal. Command to so can be found by clicking on the mysql instance -> data tab -> connect ->public network. Can also perform the necessary changes via the railway UI.
The trunk based development branching model will be used in this project. This ensures that the main branch is always in development and the integration of features is continuous. This continuous integration allows for frequent code testing and reviews, promoting the quality of the code. Furthermore, continuous integration and frequent testing will help catch bugs early and reduce the risk of deploying a faulty product. Commits
Developers are expected to regularly commit their progress. Commits should be small in size. Examples of acceptable commits are a complete function, or the framework for a class. In the case of large classes, every function within the class should be committed separately. When debugging code, developers should refrain from committing debugs in multiple sections of the code simultaneously. Each commit should only pertain to debugs of one function or a similarly small unit of code.
Commit descriptions should feature the following prefixes/tags: DEBUG, FEATURE, DOCS, REFACTOR, TEST, STYLE. The format of the commit should be ‘[prefix]: [description]’. Descriptions should be written in an imperative mood, using actionable verbs such as ‘add’, ‘update’, or ‘remove’. The description should be a single concise sentence. If your commit message needs to be longer, this indicates that it can be broken down into multiple commits.
The main branch currently in github will function as the trunk branch with ‘feature’ branches as short development branches. Feature branches are branches where teams will develop, implement small tasks and features or perform code spikes all requiring no more than a few days' effort. After features are completed, a pull request (PR) shall be requested by the agile team with final code review and execution of CI/CD pipelines before merging into the main branch. (Complete CI/CD pipelines may not be applicable to certain, if not any, stages of the project as it is a requirement to be implemented).
Branch names shall follow the following convention: Type of Branch/Related User Stories/description of branch
Types of branches include: Feature Code Spike Hotfix
Eg. Feature/User Story 1/Add Button
Semantic Versioning (SemVer): Semantic Versioning uses a three-part version number: MAJOR.MINOR.PATCH.
[MAJOR] Significant changes and versions are not backwards compatible
[MINOR] New features and versions are backward compatible
[PATCH] Bug fixes/ small changes. Remains backward compatible \
Contributions are welcome and can be submitted via pull requests.
All pull requests must include the following:
- A brief summary of the changes made.
- References to any relevant issue numbers (if applicable).
- Instructions for testing the changes.
- Any other relevant information (e.g., potential impacts on other parts of the codebase). A maintainer will be notified and review the changes made.
- Forms groups between students using one of multiple available formation strategies
- View group by group and cohort wide analytics on personality distribution
- Export group allocation data in CSV format for use with your learning management system
- Sending out a google forms to all students to collect results
- Auth0 login page preventing use of features without authentication
- Manual data entry, addition, editing or removal of data
- To use the team forming dashboard, create a new offering for the unit you are currently running
- Enter the unit and upload your csv list of students with their student details
- Upload student personality data in accordance with the strategy you would like to form teams against
- Select your group formation strategy and form groups
- Optionally export group information as a csv to upload to your learning management system
The following examples outline the expected structure and content of csv files. Note extra columns may be present but will be ignored and only what is shown will be used by the application.
| studentId | labCode | lastName | preferredName | wam | gender | |
|---|---|---|---|---|---|---|
| 12345678 | 01_DualMode | Jim | White | [email protected] | 93 | M |
| 28462818 | 02_OnCampus | Jemma | Black | [email protected] | 93 | F |
- studentId must be an 8-digit number
- labCode must be prefixed by the number and '_' minimally
- gender must be a single char
Belbin type must be one of people, thinking or action
| studentId | belbinType |
|---|---|
| 12345678 | people |
| 28462818 | thinking |
| 41161886 | action |
hourCommitment is the estimated number of hours that a student expects to commit in a week
| studentId | hourCommitment | avgAssignmentMark |
|---|---|---|
| 12345678 | 13 | 73 |
| 28462818 | 18 | 84 |
Preferences can be added to the end of the table as needed. Project Pref is a number from 1 to n, where n is the number of projects.
| timestamp | studentId | full name | Project Pref n | |
|---|---|---|---|---|
| 2/26/2024 20:00:39 | 12345678 | Jim White | [email protected] | 1 |
| 2/26/2024 20:00:39 | 28462818 | Jemma Black | [email protected] | 9 |
Refer to the feature extention writeup under docs/ for further details on how to add group formation strategies
For the purpose of testing, a script to generate mock input data can be found under docs/mockInputs.
Run the following commands under the docs/mockInputs directory to create a virtual environment and view details on usage:
python -m venv .venv
source .venv/bin/activate # .venv/Scripts/activate for Windows
pip install -r requirements.txt
python ./generator.py --help
Thanks goes to these wonderful people (emoji key):
 Abby 💻 🎨 🐛 👀 |
 ahes0001 💻 🎨 🐛 👀 |
 Alex 💻 🎨 🐛 |
 AbBaSamo 💻 🎨 🐛 👀 📖 |
 clau-0016 💻 🎨 🐛 |
 francisanthony17 💻 🎨 🐛 👀 |
 jhun0012 💻 🎨 🐛 👀 📖 |
 Jonathan Yip 💻 🎨 🐛 |
 lbon0008 💻 🎨 🐛 👀 |
 MariahMcCleery 💻 🎨 🐛 📖 |
 Mark-Mikhail 💻 🎨 🐛 👀 |
 mfin0008 💻 🎨 🐛 👀 |
 nath0002 💻 🎨 🐛 |
 Ian Kabil Felix 🧑🏫 |
 Riordan Alfredo 🧑🏫 🎨 🔣 🤔 |
 Rishi-Bidani 💻 🎨 🐛 |
 Domico Carlo 💻 🎨 🐛 |
 Thejas 💻 🎨 🐛 |
 ZCStephen 💻 🎨 🐛 |
 jeffreyyan4 💻 🎨 🐛 |
 Lachlan Williams 💻 🎨 🐛 |
 charles 💻 🎨 🐛 |
 dhon0010 💻 🎨 🐛 |
 kbay0009 💻 🎨 🐛 |
 Trevor Yao 💻 🎨 🐛 |
 oneil1625 💻 🎨 🐛 |
 echu0033 💻 🎨 🐛 |
 Aung33270333 💻 🎨 🐛 |
 me-za 💻 🎨 🐛 |
 dcor0010 💻 🎨 🐛 |
 alexismcharo 💻 🎨 🐛 |
This project follows the all-contributors specification. Contributions of any kind welcome!