README.adoc

Mpesa Location Back-End

Table of Contents

• Apps
• Linting
• Front-end

The back-end consists of a Docker container with Python 3.10 and Django 4.2.2.

All Python package requirements are listed in Pipfile and their dependencies and associated hashes in Pipfile.lock which supports more secure verification and enables deterministic builds. Refer to Pipenv docs for more details. The initial requirements include:

• Django as the base framework

• markdown for rendering markdown in HTML

• djangorestframework for creating the API for the front-end to consume

• djangorestframework-gis for adding geographic add-ons for Django Rest Framework

• pytest for writing tests

• black for linting and automatically formatting the code

• django-debug-toolbar to help with debugging

• psycopg Modern implementation of a PostgreSQL adapter for Python using Psycopg3

• psycopg-binary to help with development using psycopg3 using pre-compiled libraries

• django-leaflet to enable using leaflet assets and object in Django project

• django-environ to enable configuration of Django application with environment variables

• dj-database-url to provide support for database URL environment variable

• django-filter to allow filtering of querysets dynamically

• djangorestframework-simplejwt to allow implementation of JSON Web Token (JWT) authentication

If you’d like to install additional dependencies, use pipenv shell to create a virtual environment, then run pipenv install <your package> which automatically adds them to the Pipfile file and rebuild the Docker containers with make build-dev for development and make build in production.

The application uses the PostGIS database back-end by default.

Apps

There are two Django apps in this application:

• users app - Facilitates authentication concerns like logging the user in through the login form.

• mpesa_loc app - The core business logic of the application – is serving as a GIS backend. Exposes a REST API that can be consumed by the front-end. Everything related to the API is in the backend folder. This includes very standard Django REST Framework viewsets in mpesa_api/viewsets.py, serializers in mpesa_api/serializers.py, and users/serializers.py, registering the routes from those viewsets in mpesa_api/routers.py and users/routers.py.

There are also some tests in the mpesa_api/test.py and users/test.py files.

Linting

Black is used to automatically format and lint files. The make lint-django command checks that the project is correctly formatted.

You can set up your editor to automatically format Python files using Black following the instructions on Black’s GitHub page.

You can also use the make lint-django-fix command to automatically format all Python files in the project.

Front-end

The front-end is a React app that’s rendered through Django.

Read more about how the front-end works in the frontend README.adoc.