masks-personality-quiz/README.md

# Which *Masks* Playbook Are You? — a Personality Quiz

## About the Project

I started work on the first version of this personality quiz over a year ago, when I decided to teach myself programming.
The original version ran on JavaScript and was rendered and evaluated entirely by the browser.
This version runs entirely on the server, and the quiz results are evaluated by the server rather than the client.

The back-end runs on Python 3.10, using the Flask framework.
The web pages are templated using Jinja.
The web site is rendered using html and the Bootstrap CSS framework.
There have been some elements of the interface enhanced using rudimentary JavaScript, including the jQuery library.
Of all of these programming languages, Python has proved to be a far more intuitive language to learn, and generally programming this has been a lot more enjoyable and a lot less frustrating than the earlier iteration that used JavaScript.

The quiz runs by rendering a form with all of the questions and options on the browser.
The browser then submits the responses via a POST request to the server.
The server evaluates the responses and renders the results accordingly.
There is no information stored on the client.

All data transacted between the client and the server is stored as a Flask session for the duration that the user is on the web site.
If the user closes the site, the session data is deleted and all answers submitted are lost.

There are, of course, some considerable inefficiencies in the way I have set up the templating.
I have written the text for all the various web pages in the templates of the respective pages.
Ideally, I would have preferred having a single template for all of the web pages or views, and then have the content served on those pages render dynamically based on the URL query.
But that was a level of programming that was gratuitous at this point, as really most of the pages were serving static content anyway so it did not matter just now.

Moreover, the algorithm with which the quiz calculates Labels is highly inaccurate.
It is difficult to find an algorithm that simulates Label shifts like during play because of how many variables and conditions there are to what constitutes a valid Label shift, and the fact that which Labels are being shifted might be complicated by the existence of custom Labels like ‘Soldier’.
So the Labels that the quiz returns are highly inaccurate, often not adding up to the right numbers.

In addition, this is the first time I am storing the code of the quiz on my git repo, and having a much more streamlined version control process.
I have also Dockerised the app so it can be deployed seamlessly.

## Set Up

To run an instance of this app, you will need Docker and Docker Compose installed.

To set up an instance, you will need to clone the repository,

You will also need to create a module called `secret.py` and enter a secret key for Flask to use to encrypt session data.
The easiest way to do this is to make a copy of `secret.py.example`, remove `.example` from the filename, and then add a random string as a value for the variable defined therein.

After you have created `secret.py`, run `sudo docker-compose up -d` from the root folder.
The current set-up in the `docker-compose.yml` does not expose the container to the internet, but exposes it on an internal Docker network.
This can be changed by amending the `docker-compose.yml` entry on `line 8` to:

```yml
      - 5000:5000
```

## Version History

### Current Version: 3.0.1 (3 November 2021)

### Changelog

- Serving the web app using Gunicorn so it can handle multiple requests.
- Added OpenGraph and other social media meta tags to allow for sharing on social media.

### Past Versions

#### Version 3.0.0

- Re-built the quiz to run on the server side rather than on the client.
- Built using Python, Flask, Jinja, and html primarily.
- Changed the layout to a cleaner, more accessible and modern style using the Bootstrap CSS framework,
- Expanded to 30 questions.
- Refined the algorithm by which the Joined duplicates another playbook based on the second-highest scoring match rather than selecting a playbook entirely at random.
- Dockerised the quiz and hosting it on my web server, serving it via the front-end reverse proxy.

Because I only started using Git relatively recently, I have not uploaded the code from the older versions onto the repo.
The repo starts with version 3.

#### Version 2 (2 May 2020)

- First added the functionality to determine character Labels.
- Re-wrote many of the questions, expanded the quiz to 25 questions.
- Added extensible databases to allow for more questions to be added dynamically.
- Added the functionality to filter Playbooks based on source books.
- Added a glossary to explain game terms.

#### Version 1 (20 April 2020)

- First made the quiz to run entirely in the browser using JavaScript.
- Rudimentary quiz that returned the playbook most suited.