# Match Up

Match Up! is a web application to create pairings of players from a pool and assign to a limited number of slots. It is [live](https://mu.karanj.com)!

Here it is in action:

![Game Page](https://gitlab.com/KaranJayachandra/match_up/-/raw/main/assets/docs.png?ref_type=heads)

Some features of this application are:

- Activate and deactivate named players, guests and courts
- Propose pairings to each court from a set of players
  - Considers player levels (optionally mingle players)
  - Prioritize players that haven't played as many games
- Timer to limit the time for each round

What this application ***IS***:

- Open: The source code is available for modifications and extension
- Private: All player data is stored in your browser via local storage

What this application ***IS NOT***:

- Secure: The data is available for anyone to observe via the browser console
- Performant: Works with a small number of named players (~3MB)

## Usage

- Select or deselect the courts available
- Check in and check out the regular players
- Optionally add guests to the game
  - Beginner: Level 1
  - Novice: Level 3
  - Intermediate: Level 6
- Choose how the pools should be created
  - All levels (Disregard levels)
  - 2 Levels (Players split into two categories)
  - 3 Levels (Players split into three categories)
  - Skill based (Consider all levels)
- Request a proposal and confirm to start a round
- Repeat as many times as needed
- Reset the session at the bottom of the page
- You can update the list of players by providing a CSV file. The format is show below:

|id|first_name|last_name|level|
|---|---|---|---|
|104|John|Doe|4|
|104|Jane|Doe|9|

Levels are defined between 1 to 10.

## Compilation

Please install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [node](https://nodejs.org/en) on your machine before proceeding further.

Once installed, open the terminal to a folder of your choosing and run the following commands to setup the application.

```bash
git clone https://gitlab.com/KaranJayachandra/match_up.git
cd match_up
npm install
```

To run a development server run `npm run dev` or run `npm run build` to create a optimized bundle of static content. I choose to serve this content via GitLab pages but you could choose to do so in any other server. This application is running via [IIS](https://www.iis.net/) locally on machine at my club as it doesn't have access to the internet.

## Architectural Design Record

Key Learnings: 

- The choice of language is tightly coupled to application complexity requirements:
  - [Flask](https://flask.palletsprojects.com/en/stable/) or [Dash](https://dash.plotly.com/tutorial) applications are easy to develop but hard to deploy.
  - JavaScript is a superb language for creating shareable tools for non-technical people.
- Front end work and back end work are equally important in the success of an application.
- Vanilla JavaScript is enough for most simple applications; complex applications might benefit from [state](https://refactoring.guru/design-patterns/state).

At [my badminton club](https://www.bctsf.nl/) we run a hustle system to create matches of four players from a pool of players currently at the club. This application aimed to solve this problem. I started off using Plotly Dash, then transitioned to a combination of Flask and HTMX. Running a web server with a connected postgres databased instance on Heroku seemed overkill for this after going live. Therefore, I finally ending up with the foundational triad for web development:

1. Hypertext Markup Language (HTML) for the content
2. Cascading Style Sheets (CSS) for the styling
3. JavaScript for (JS) user interaction

I believe that HTML is quite straight forward to learn. So I don't write much about it here but this [cheatsheet](https://www.simplehtmlguide.com/cheatsheet.php) was really handy. Complications come from the use of meta tags. These I used occasionally and I look them up when needed. I found CSS more difficult. There are several nitty gritty details and properties which can be used. I went with a simple style sheet already available. But I have made attempts at making my own. An example is my [website](https://karanj.com). Some good CSS frameworks I considered are:

- [Simple](https://simplecss.org)
- [Bulma](https://bulma.io)
- [Pico](https://picocss.com)

It took me quite some time to pick up JavaScript. For some reason, I always found it irritating to work with. Mainly because of its dependency to browsers. I found things were unwieldy at first but when I transitioned to `node`, everything became much easier. `node` embeds V8 inside a C++ program to run JS without a browser. It also acts as a package manager for JavaScript. I think JavaScript might now be one of the best languages for rapid development and deployment. Here I wanted to make small cheatsheet for myself for the future when I have to jump back into JS development.

JavaScript is a dynamically typed language whose runtime is embedded in most browsers. JavaScript engines in browsers: Firefox has SpiderMonkey and Chrome has V8. ECMAScript is the standard, JavaScript is an implementation of it. JavaScript uses [camel case](https://en.wikipedia.org/wiki/Camel_case) as a naming convention. Key learnings are:

- `let` to declare mutable variables, `const` for immutable ones
- Value types: `Number`, `String`, `Boolean`, `Symbol`, `undefined` and `null`
- `undefined` is the default value for variables, `null` is to clear the value
- Reference types: `Object`, `Function`, `Array`
- Functions are are used in JavaScript to:
	- Apply operations on parameters and return the output. 
	- Create an effect for the user to see
- Since functions are objects, this is how classes are implemented in JavaScript

A summary of what I learnt can be seen below:

```javascript
// Constructor function
function Human(name) {
	this.name = name;
	this.location = "USA";
	this.friends = ["John", "Mary"];
	this.position = 0;
	this.walk = function() {
		this.position += 1;
		console.log("User walked!");
	}
}

let user = new Human();
user.friends.append("Anthony")
user.walk();
```
### Packaging

JavaScript can be packaged for others to use via an `npm` package. This is very similar to how `pip` works for Python. There are some packages that are really useful that I note below:

- [Lodash](https://lodash.com/) is crucial for working with JavaScript objects
- [Vite](https://vite.dev/) makes building single page application a breeze

Some packages that are useful for debugging are: [debug](https://www.npmjs.com/package/debug) and [chalk](https://www.npmjs.com/package/chalk). I would like to try out the folloing packages in future projects:

- [Tensorflow.js](https://www.tensorflow.org/js): for numerical computing
- [vue.js](https://vuejs.org/): Package components into a single file
- [express.js](https://expressjs.com/): flask equivalent with routing and requests

## Resources

- Mosh Hamedani's [JS Basics](https://www.youtube.com/watch?v=W6NZfCO5SIk) and [Object-oriented JS](https://www.youtube.com/watch?v=PFmuCDHHpwk)
- [Primeagen - HTMX Sucks](https://www.youtube.com/watch?v=4gwOv2-A8Vo)
- [Tech with Tim - Use SQLAlchemy Database](https://www.youtube.com/watch?v=uZnp21fu8TQ)