Frontend Test Coverage:

Backend Test Coverage:

Build:

boxtribute

This is the repository for version 2 of the humanitarian relief web app Boxtribute. We support the distribution of over 1 million items each year and are deployed in over 15 locations across Europe and the Middle East (check our website for the most current list of partners).

Built by aid workers for aid workers, it is designed with three top priorities in mind:

1. Quick deployment into crisis situations, including easy integration into a large range of relief operations, whether they're being newly set up or already up and running.
2. Effective even with minimal training - doesn't require any professional expertise to use well. Can be run smoothly with short-term volunteers of all backgrounds.
3. Dignity and choice-based distribution as a first priority for vulnerable individuals.

The web app consists of a React front-end, and a Python Flask back-end.

Please check out Contribution Guidelines before you get started!

Table of Contents

1. Contribution Guidelines
2. Installation
   1. Basic steps
   2. Front-end
   3. Back-end
3. About Docker
4. Development Database Seed
5. CircleCI
6. Architecture overview
7. Sponsors

Preparation for Installation

• Clone the repository.
• Install Docker and docker-compose (version 2)

How do I get set up?

:star2: Only TWO commands required to get the full-stack app up and running :star2:

At the end of this section, there are links to further instructions to set up additional tools for your front-end and back-end environment.

1. Environment variables are managed in a single file. Run cp example.env .env

2. To build and start the involved Docker services, execute

   docker compose up
   

3. Open your web browser on http://localhost:3000

4. Log in with one of the test users listed below

NB: In case you get out-of-memory related errors, make sure your max memory is at least 4GB in your Docker settings (via Docker Settings UI -> Resources -> Memory) and try again. In (Linux) Docker there is no UI to set the memory limits globally. In that case, please specify the following in docker-compose.yml:

version: "2.4"
services:
    [...]
    front:
        mem_limit: 4G

Further Steps

• for front-end including react-testing-library, eslint, prettier
• for back-end including pytest, venv, formatting and debugging

About Docker

We use Docker containers to make it easy for everyone to spin up an development environment which is the same everywhere. In the docker-compose configuration file three Docker containers are specified - one for the MySQL database called db, one for the Flask back-end called webapp and one for the react front-end called front.

Development Database Seed

Boxtribute is an application for organisations who run distribution/warehouses in multiple bases. Therefore the development database seed holds at least two organisations and four bases:

• Organisation BoxAid working on Lesvos and
• Organisation BoxCare working on Samos and in Thessaloniki and Athens.

Each organisation has at least 3 user groups with different access levels in the app:

• Head of Operations (Admin access)
• Coordinator
• Volunteer

In the development seed and Auth0 dev tenant we created the following login credentials with names telling their role and access to the various bases:

• [email protected] (God User)

BoxAid (all have access to only one base: Lesvos):

• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected]

BoxCare (there are 3 bases associated - Thessaloniki, Samos, Athens):

• [email protected]
• [email protected] (Coordinator at bases Thessaloniki and Samos)
• [email protected] (Volunteer at bases Thessaloniki and Samos)
• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected] (only for label creation)

The password of all of these users is Browser_tests.

A collection of various QR labels (associated/not associated with existing boxes) can be found in this directory.

QR labels associated with boxes

Box in base 1

Box in base 2

Box in base 3

Box in base 4

QR labels not associated with any boxes

More labels can be found here.

QR labels that don't exist in the database

More labels can be found here.

CircleCI

We use CircleCI for automated testing of PRs and deployment to Google Cloud. To develop the CircleCI scripts you can run a CircleCI client locally. Please check out the documentation.

The most important commands are

circleci config validate
circleci local execute --job JOB_NAME

CircleCI development tips/learnings

• You can only trigger a job locally if it is part of a CircleCI workflow.
• Each run-step in the config of CircleCI should be treated as its own terminal. If you have for example activated an virtual environment in a run-step, this environment is not activated in the next run-step.

Deployment

About the versioning scheme:

• major version is always 2
• minor version is incremented if any database migration is part of the release
• "bugfix" version is incremented otherwise

1. Please commit (at least the last commit) using the command git commit -S -m "..." to make your commits verifiable. See this ticket for more info
2. Create a new list in trello named "Boxtribute 2.0 || merged to production date (v2.X.Y)"
3. Move the cards from the list "Boxtribute 2.0 || merged to staging" to the new list
4. Checkout the production branch and update it to the latest version: git checkout production && git pull --tags origin production
5. Merge master into production WITHOUT creating a merge commit (we want production to have the same history as master): git pull origin master
6. Publish the changes to the remote repo: git push origin production
7. Create a verifiable tag with the version number (check out the production branch after the merge, run git tag -s v2.X.Y and push the tag with git push --tags

Architecture overview

All our architecture decisions are logged in ADRs which you can find here.

System landscape

The following diagram gives the system context for the boxtribute software acc. to the C4 model architecture visualization method.

Software stack

Here is a list of intro tutorials for each technologies / frameworks / languages.

Front-end

• Typescript
• Chakra UI
• React
• React Hooks
• React Context
• Apollo

Interface

• GraphQL

Back-end

• Ariadne
• Python 3.12
• Flask
• PeeWee
• MySQL Community Edition

Authentication

• Auth0

Testing

• React Testing Library / Jest Tutorial
• Moving from Enzyme to React Testing Library
• Mocking Apollo Client
• Pytest

License

See the LICENSE file for license rights and limitations (Apache 2.0).

Sponsors

This project was funded 3x by the German Federal Ministry of Education and Research (BMBF) via the Prototype Fund. Read more here (German only):

• API für Datenbankzugriff und optimerten Austausch von Hilfsgütern
• Erweiterung zur Unterstützung von Transient Refugees
• Boxtribute 2.0