4 tier share distribution system

Peter Lu

https://github.com/py1u

This guide will help you set up and run the app with the required dependencies. We will be using a virtual environment throughout the guide.

• Requires Python 3.8 or higher
• At least 150MB disk space since input datasets are included in the project

The reason a virtual environment is used is so that we can manage our python project depandencies without affecting our global python package versioning system. Python projects tend to use many different versions causing version mismatch problems so creating a virtual environment before installing project dependencies + running the application is always good practice.

I mainly use Linux commands for this project however I included most commands that will work

• MacOS/Linux commands are postfixed with 3 (ex: pip3, python3) and windowsOS is not.

1. Install the required version of Python (if not installed already).

2. Create a virtual environment:

   python3 -m venv .venv

3. Activate the virtual environment:

   source .venv/bin/activate

1. Install the required version of Python (if not installed already).

2. Create a virtual environment:

   python -m venv .venv

3. Activate the virtual environment:

   .venv\Scripts\activate

After activating the virtual environment, your command prompt should change to indicate that you are inside the virtual environment.

looks something like (.venv)

Once the virtual environment is activated, install the project dependencies listed in requirements.txt:

pip3 install -r requirements.txt

The requirements.txt includes the following dependencies:

Flask==3.1.0
Werkzeug==3.1.3
Jinja2==3.1.5
itsdangerous==2.2.0
click==8.1.8
pandas==2.2.3
numpy==2.2.3
pytest==8.3.4
python-dotenv==1.0.1

Most of these come with the standard Flask installation with added data science libraries and environment management packages I decided to utilize.

Once the dependencies are installed, you can run the Flask application.

1. Set up environment variables (optional since I did not add deployment secrets for this project):

   • Create a .env file in the root of your project

2. Start the Flask app at app.py in the root directory using this command

   python3 app.py

By default, the app will run on http://127.0.0.1:8000/. I set the port to 8000 for this project and debugging is already disabled.

3. View generated reports

• there are two options, viewing the UI or sending a api GET request
• homepage is found at http://127.0.0.1:8000
• reports are found at http://127.0.0.1:8000/reports/<commitment_id> where commitment_id is a dynamic route segment(ex: pick a value 1 - 10)
• APIs are found at http://127.0.0.1:8000/api/reports/<commitment_id>
• feel free to try out /api/hello or api/about/ to test the connection

After testing and stopping the application you must perform this step

To deactivate the virtual environment, run:

deactivate

This will return you to your system's global Python environment.

• If you encounter any issues during installation or running the app, ensure that all dependencies are correctly installed and the virtual environment is activated.

• To run tests, you can use pytest by simply running:

  pytest

• There should be 4 test cases that are performed on the 4 tiers.

If you have issues running the app, make sure the following are correct:

• Your Python version is 3.8 or higher.
• The virtual environment is activated before installing dependencies.
• You are running the app from within the virtual environment.
• pycache files are naturally generated in the application along with .pyc files but should already to handled in .gitgnore

I decided to approach the challenge with a more creative and curious learning oppurtuinity and a product-focused mindset. This is why I created the name of the project "MizuShare", where "mizu" means water as if the waterfall engine is designed so that profit shares are distributed smoothly like flowing water

1. looking to introduce a database integration for improving data management
2. integrate a vite + react frontend for more responsive UI
3. build a robust testing suite focusing on test driven development