{"id":46634882,"url":"https://github.com/boxwise/boxtribute","last_synced_at":"2026-03-08T01:02:36.978Z","repository":{"id":36972870,"uuid":"290077536","full_name":"boxwise/boxtribute","owner":"boxwise","description":"The code base for Boxtribute 2.0, a humanitarian aid web application making it easy to source, store and distribute goods to people in need in a fair and dignified way","archived":false,"fork":false,"pushed_at":"2026-03-02T01:47:45.000Z","size":31098,"stargazers_count":44,"open_issues_count":23,"forks_count":13,"subscribers_count":8,"default_branch":"master","last_synced_at":"2026-03-02T03:41:18.854Z","etag":null,"topics":["circleci","distributions","docker","flask","graphql","humanitarian","humanitarian-aid","mysql-database","peewee-orm","python","react","reactjs","techforgood","warehouse-management"],"latest_commit_sha":null,"homepage":"https://www.boxtribute.org/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boxwise.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-08-25T01:09:13.000Z","updated_at":"2026-02-24T11:23:26.000Z","dependencies_parsed_at":"2023-10-16T18:24:41.700Z","dependency_job_id":"eded309b-260e-41d3-a4f4-fac6e5e72e9e","html_url":"https://github.com/boxwise/boxtribute","commit_stats":null,"previous_names":[],"tags_count":62,"template":false,"template_full_name":null,"purl":"pkg:github/boxwise/boxtribute","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boxwise%2Fboxtribute","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boxwise%2Fboxtribute/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boxwise%2Fboxtribute/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boxwise%2Fboxtribute/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boxwise","download_url":"https://codeload.github.com/boxwise/boxtribute/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boxwise%2Fboxtribute/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30240268,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T00:58:18.660Z","status":"ssl_error","status_checked_at":"2026-03-08T00:55:48.608Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["circleci","distributions","docker","flask","graphql","humanitarian","humanitarian-aid","mysql-database","peewee-orm","python","react","reactjs","techforgood","warehouse-management"],"created_at":"2026-03-08T01:01:02.458Z","updated_at":"2026-03-08T01:02:36.880Z","avatar_url":"https://github.com/boxwise.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![DPG Badge](https://img.shields.io/badge/Verified-DPG%20(Since%20%202022)-3333AB?logo=data:image/svg%2bxml;base64,PHN2ZyB3aWR0aD0iMzEiIGhlaWdodD0iMzMiIHZpZXdCb3g9IjAgMCAzMSAzMyIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTE0LjIwMDggMjEuMzY3OEwxMC4xNzM2IDE4LjAxMjRMMTEuNTIxOSAxNi40MDAzTDEzLjk5MjggMTguNDU5TDE5LjYyNjkgMTIuMjExMUwyMS4xOTA5IDEzLjYxNkwxNC4yMDA4IDIxLjM2NzhaTTI0LjYyNDEgOS4zNTEyN0wyNC44MDcxIDMuMDcyOTdMMTguODgxIDUuMTg2NjJMMTUuMzMxNCAtMi4zMzA4MmUtMDVMMTEuNzgyMSA1LjE4NjYyTDUuODU2MDEgMy4wNzI5N0w2LjAzOTA2IDkuMzUxMjdMMCAxMS4xMTc3TDMuODQ1MjEgMTYuMDg5NUwwIDIxLjA2MTJMNi4wMzkwNiAyMi44Mjc3TDUuODU2MDEgMjkuMTA2TDExLjc4MjEgMjYuOTkyM0wxNS4zMzE0IDMyLjE3OUwxOC44ODEgMjYuOTkyM0wyNC44MDcxIDI5LjEwNkwyNC42MjQxIDIyLjgyNzdMMzAuNjYzMSAyMS4wNjEyTDI2LjgxNzYgMTYuMDg5NUwzMC42NjMxIDExLjExNzdMMjQuNjI0MSA5LjM1MTI3WiIgZmlsbD0id2hpdGUiLz4KPC9zdmc+Cg==)](https://www.digitalpublicgoods.net/r/boxtribute)\n\n\n\u003ca width=\"105\" height=\"35\" href=\"https://auth0.com/?utm_source=oss\u0026utm_medium=gp\u0026utm_campaign=oss\" target=\"_blank\" alt=\"Single Sign On \u0026 Token Based Authentication - Auth0\"\u003e\n\u003cimg width=\"105\" height=\"35\" alt=\"JWT Auth for open source projects\" src=\"https://cdn.auth0.com/oss/badges/a0-badge-dark.png\"\u003e\u003c/a\u003e\n\nFrontend Test Coverage: [![codecov](https://codecov.io/gh/boxwise/boxtribute/branch/master/graph/badge.svg?token=646MWM6V9H\u0026flag=frontend)](https://codecov.io/gh/boxwise/boxtribute)\n\nBackend Test Coverage: [![codecov](https://codecov.io/gh/boxwise/boxtribute/branch/master/graph/badge.svg?token=646MWM6V9H\u0026flag=backend)](https://codecov.io/gh/boxwise/boxtribute)\n\nBuild: [![CircleCI](https://circleci.com/gh/boxwise/boxtribute.svg?style=svg)](https://circleci.com/gh/boxwise/boxtribute)\n\n# boxtribute\n\nThis is the repository for version 2 of the humanitarian relief web app [Boxtribute](https://www.boxtribute.org). 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](https://boxtribute.org) for the most current list of partners).\n\nBuilt by aid workers for aid workers, it is designed with three top priorities in mind:\n\n1. 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.\n2. 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.\n3. Dignity and choice-based distribution as a first priority for vulnerable individuals.\n\nThe web app consists of a [React front-end](/front), and a [Python Flask back-end](/back).\n\nPlease check out [**Contribution Guidelines**](CONTRIBUTING.md) before you get started!\n\n## Table of Contents\n\n1. [Contribution Guidelines](CONTRIBUTING.md)\n1. [Installation](#preparation-for-installation)\n   1. [Basic steps](#preparation-for-installation)\n   2. [Front-end](/react/README.md)\n   3. [Back-end](/back/README.md)\n1. [About Docker](#about-docker)\n1. [Development Database Seed](#development-database-seed)\n1. [CircleCI](#circleci)\n1. [Architecture overview](#architecture-overview)\n1. [Sponsors](#sponsors)\n\n## Preparation for Installation\n\n- Clone the repository.\n- Install [Docker](https://www.docker.com/products/docker-desktop) and `docker-compose` (version 2)\n\n## How do I get set up?\n\n:star2: _Only TWO commands required to get the full-stack app up and running_ :star2:\n\nAt the end of this section, there are links to further instructions to set up additional tools for your front-end and back-end environment.\n\n1.  Environment variables are managed in a single file. Run `cp example.env .env`\n\n1.  To build and start the involved Docker services, execute\n\n        docker compose up\n\n1.  Open your web browser on `http://localhost:3000`\n\n1.  Log in with one of the test users [listed below](#development-database-seed)\n\n**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 -\u003e Resources -\u003e Memory_) and try again.**\nIn (Linux) Docker there is no UI to set the memory limits globally. In that case, please specify the following in `docker-compose.yml`:\n\n```\nversion: \"2.4\"\nservices:\n    [...]\n    front:\n        mem_limit: 4G\n```\n\n### Further Steps\n\n- [for front-end including react-testing-library, eslint, prettier](/front/README.md)\n- [for back-end including pytest, venv, formatting and debugging](/back/README.md)\n\n## About Docker\n\nWe 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](./docker-compose.yml) 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`.\n\n## Development Database Seed\n\nBoxtribute is an application for organisations who run distribution/warehouses in multiple bases.\nTherefore the development database seed holds at least two organisations and four bases:\n\n- Organisation `BoxAid` working on `Lesvos` and\n- Organisation `BoxCare` working on `Samos` and in `Thessaloniki` and `Athens`.\n\nEach organisation has at least 3 user groups with different access levels in the app:\n\n- `Head of Operations` (Admin access)\n- `Coordinator`\n- `Volunteer`\n\nIn the development seed and Auth0 dev tenant we created the following login credentials with names telling their role and access to the various bases:\n\n- some.admin@boxtribute.org (God User)\n\nBoxAid (all have access to only one base: Lesvos):\n\n- dev_headofops@boxaid.org\n- dev_coordinator@boxaid.org\n- dev_volunteer@boxaid.org\n- warehouse.volunteer@lesvos.org\n- freeshop.volunteer@lesvos.org\n- library.volunteer@lesvos.org\n\nBoxCare (there are 3 bases associated - Thessaloniki, Samos, Athens):\n\n- dev_headofops@boxcare.org\n- dev_coordinator@boxcare.org (Coordinator at bases Thessaloniki and Samos)\n- dev_volunteer@boxcare.org (Volunteer at bases Thessaloniki and Samos)\n- coordinator@thessaloniki.org\n- coordinator@samos.org\n- coordinator@athens.org\n- volunteer@thessaloniki.org\n- volunteer@samos.org\n- volunteer@athens.org\n- warehouse.volunteer@athens.org\n- freeshop.volunteer@athens.org\n- label@athens.org (only for label creation)\n\nThe password of all of these users is `Browser_tests`.\n\nA collection of various QR labels (associated/not associated with existing boxes) can be found in [this directory](./docs/qr).\n\n### QR labels associated with boxes\n\nBox in base 1\n\n![box in base 1](./docs/qr/code-with-box-base-1-a3f22cbf5e52ea40557d8c8117ece5d3.png)\n\nBox in base 2\n\n![box in base 2](./docs/qr/code-with-box-base-2-c7c9691e8490695871eff25a7184a68d.png)\n\nBox in base 3\n\n![box in base 3](./docs/qr/code-with-box-base-3-04508398e21891508288f9d64c250f1e.png)\n\nBox in base 4\n\n![box in base 4](./docs/qr/code-with-box-base-4-d871e6c7f0a6e74fea024427a6ee3381.png)\n\n### QR labels not associated with any boxes\n\n![x0](./docs/qr/without-box/0159bdee5ace105482989775c591f1af.png)\n\n![x1](./docs/qr/without-box/02aab8f4b84d9c917c9ed5ff148c7776.png)\n\n![x2](./docs/qr/without-box/083c297c3de6396dad509f8018ac403d.png)\n\nMore boxes can be found [here](./docs/qr/without-box).\n\n### QR labels that don't exist in the database\n\n![x0](./docs/qr/not-in-database/168842e6389b520d4b1836562aa1f05.png)\n\n![x1](./docs/qr/not-in-database/12ca607ce60c484bdbb703def950c5b.png)\n\n![x2](./docs/qr/not-in-database/13f12820c8010f2f7349962930e6bf4.png)\n\nMore boxes can be found [here](./docs/qr/not-in-database).\n\n## CircleCI\n\nWe are 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](https://circleci.com/docs/2.0/local-cli/).\n\nThe most important commands are\n\n```\ncircleci config validate\ncircleci local execute --job JOB_NAME\n```\n\n### CircleCI development tips/learnings\n\n- You can only trigger a job locally if it is part of a CircleCI workflow.\n- 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.\n\n### Deployment\n\nAbout the versioning scheme:\n\n- major version is always 2\n- minor version is incremented if any database migration is part of the release\n- \"bugfix\" version is incremented otherwise\n\n1. Please commit (at least the last commit) using the command `git commit -S -m \"...\"` to make your commits verifiable. See [this ticket](https://trello.com/c/kgB1H7B0) for more info\n1. Create a new list in trello named \"Boxtribute 2.0 || merged to production date (v2.X.Y)\"\n1. Move the cards from the list \"Boxtribute 2.0 || merged to staging\" to the new list\n1. Checkout the production branch and update it to the latest version: `git checkout production \u0026\u0026 git pull --tags origin production`\n1. Merge master into production WITHOUT creating a merge commit (we want production to have the same history as master): `git pull origin master`\n1. Publish the changes to the remote repo: `git push origin production`\n1. 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`\n\n## Architecture overview\n\nAll our architecture decisions are logged in ADRs which you can find [here](docs/adr/adr_template.md).\n\n### System landscape\n\nThe follow diagram gives the system context for the boxtribute software acc. to the [C4 model](https://c4model.com/diagrams) architecture visualization method.\n\n![C4 system landscape](docs/c4-system-landscape.png)\n\n### Software stack\n\nHere is a list of intro tutorials for each technologies / frameworks / languages.\n\n#### Front-end\n\n- [Typescript](https://react-typescript-cheatsheet.netlify.app/)\n- [Chakra UI](https://chakra-ui.com/)\n- [React](https://reactjs.org/docs/getting-started.html)\n- [React Hooks](https://reactjs.org/docs/hooks-intro.html)\n- [React Context](https://reactjs.org/docs/context.html)\n- [Apollo](https://www.apollographql.com/docs/react/)\n\n#### Interface\n\n- [GraphQL](https://graphql.org/learn/)\n\n#### Back-end\n\n- [Ariadne](https://ariadnegraphql.org/docs/flask-integration.html)\n- [Python 3.12](https://devguide.python.org/)\n- [Flask](https://flask.palletsprojects.com/en/1.1.x/tutorial/layout/)\n- [PeeWee](http://docs.peewee-orm.com/en/latest/peewee/quickstart.html)\n- [MySQL Community Edition](https://www.mysql.com/products/community/)\n\n#### Authentication\n\n- [Auth0](https://auth0.com/docs/quickstart/spa/react)\n\n#### Testing\n\n- [React Testing Library / Jest Tutorial](https://www.freecodecamp.org/news/8-simple-steps-to-start-testing-react-apps-using-react-testing-library-and-jest/)\n- [Moving from Enzyme to React Testing Library](https://medium.com/@boyney123/my-experience-moving-from-enzyme-to-react-testing-library-5ac65d992ce)\n- [Mocking Apollo Client](https://www.apollographql.com/docs/react/development-testing/testing/)\n- [Pytest](https://docs.pytest.org/en/stable/fixture.html)\n\n## License\n\nSee the [LICENSE file](./LICENSE.md) for license rights and limitations (Apache 2.0).\n\n## Sponsors\n\nThis project was funded 3x by the German Federal Ministry of Education and Research (BMBF) via the [Prototype Fund](https://prototypefund.de/). Read more here (German only):\n\n- [API für Datenbankzugriff und optimerten Austausch von Hilfsgütern](https://prototypefund.de/project/boxtribute-api-fuer-datenbankzugriff-und-optimierten-austausch-von-hilfsguetern/)\n- [Erweiterung zur Unterstützung von Transient Refugees](https://prototypefund.de/project/erweiterung-von-boxtribute-zur-unterstuetzung-von-transient-refugees/)\n- [Boxtribute 2.0](https://prototypefund.de/project/boxtribute-2-0/)\n\n![BMBF logo](docs/bmbf.jpg)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboxwise%2Fboxtribute","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboxwise%2Fboxtribute","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboxwise%2Fboxtribute/lists"}