README.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# Match Up

Match Up! is a flask web application to create pairings of players from a pool and assign to a limited number of slots.

Here it is in action:

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

![Player Page](https://gitlab.com/KaranJayachandra/match_up/-/raw/feature/docs/docs/player_screen.png?ref_type=heads)

Some additional features of this application are:

- Propose pairings to create a round
- Timer to limit the time for each round
- Create pairings based on player level
- Prioritize players with fewer played games
- Blocking spaces that aren't available any more
- Blocking players that aren't available any more
- Regular and guest players

What this application ***IS***:

- Simple: Easy to modify, extend and use

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

- Secure: This was designed to be used locally on a machine
- Performant: It was designed for use by a single admin user

## How to run

Please install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [python](https://realpython.com/installing-python/) 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
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

Now create a file called .env with the environment variables needed by the application. An example is shown below.

```text
DATABASE = "database.csv"
COURTS = 10
APP_SETTINGS = "config.DevelopmentConfig"
```

The *DATABASE* variable contains the list of players which is just a simple CSV file with two columns, the first containing their name and the second containing their skill level from 1 to 10. The *COURTS* variable is the number of spaces or slots you have for creating pairings. *APP_SETTINGS* should be chosen between "config.DevelopmentConfig" or "config.ProductionConfig" based on the deployment.

The application can then be run using (ensure you are in the virtual environment if you closed the terminal after the previous steps):

```bash
flask run
```

The application should be running now and the terminal should display the ip and port number. Most modern terminals will allow you to navigate directly to the application by clicking on the displayed address.

## Technology used

This is a simple application build using [flask](https://flask.palletsprojects.com/en/3.0.x/), [htmx](https://htmx.org/) and [Bulma](https://bulma.io/). Flask acts as the backend that generates HTML responses using the wonderful [Jinja](https://jinja.palletsprojects.com/en/3.1.x/) templating language. Interactivity of the application is done using HTMX using simple GET and POST methods to the backend. The application is styled using the Bulma with its easy to used CSS classes.

## Startup Automation

Create a powershell script with the following content in the folder with the code.

```ps1
$env:DATABASE = "<data-base-file-name>.csv"
$env:APP_SETTINGS = "config.ProductionConfig"
.venv\Scripts\activate
pythonw -m flask run -p <port-number>
```

Create a task using Task Scheduler to run this script on start up.

## Background / Motivation

This part of the README focuses on the motivation of why this application was built and contains no technical value. Please read on in case you want to know more about the technological choices made.

> I am part of a badminton club where an old Microsoft Access application was being used to run the games played every week. The application started crashing after a good run of a few years and also lacked a few badly needed features. Instead of fixing the old application, I took it upon myself to create something using tools that are more suited for such an application. I wanted to prioritize delivery speed for performance and hence choose Python. More over, the sheer number of Python programmers allows for the application to be easily maintained by others. I myself have no idea how Microsoft Access works. Since it was quite a small application, I went with Flask as it was more than enough for the features that I needed instead of Django. I have a background in electrical engineering and having never made frontends before, went with the simplest option for the user interface after a bit of research. HTMX required no need of me writing JavaScript and was by far the most appealing option. The website needed some basic styling and after looking at a few CSS frameworks, I settled with Bulma. It game me everything I needed. The application is currently about to be deployed at the badminton club.