goodmap 2.0.0a1

Map engine to serve all the people :)

Good Map

Map engine to serve all the people ;)

Project Structure

This repository is a monorepo containing three parts:

• goodmap/ (repo root) — the Python backend, built on the platzky framework, published to PyPI as goodmap.
• frontend/ — the React frontend, built and bundled into the PyPI package (see make build-frontend). Not published as a separate npm package.
• e2e-tests/ — Playwright-based end-to-end tests exercising the backend and frontend together.

Each has its own dependency manager (poetry for the backend and e2e-tests, npm for the frontend) and is set up independently — see each directory's README for details. The root Makefile has convenience targets (make dev, make lint-check-all) that run across all three.

Setup

0. Clone the repo

git clone --recursive

Remember, everytime you want to pull the newest changes, run:

git pull
git submodule update

because goodmap contains a submodule.

#TODO remove all submodule connected instructions after removing platzky submodule (see #157)

1. Use python 3.10

If you have a different version of Python on your system, install python 3.10 alongside. For that, you can use pyenv. Follow the documentation. Useful commands: pyenv help <command>, pyenv install, pyenv shell, pyenv versions.

2. Install poetry in Python 3.10

poetry can create virtual environments associated with a project.
Make sure you are in the Python 3.10 environment and install:

pip install poetry

Useful commands: poetry -h <command>, poetry env list, poetry env info.

3. Install dependencies

poetry install

4. You're ready

When you enter the project directory, you can invoke any commands in your project like this:

poetry run <command>

Running App locally

TL;DR

If you don't want to go through all the configuration, e.g. you just simply want to test if everything works, you can simply run app with test dataset provided in examples directory:

poetry run flask --app 'goodmap.goodmap:create_app(config_path="./examples/e2e_test_config.yml")' run

Configuration

If you want to serve app with your configuration rename config-template.yml to config.yml and change its contents according to your needs.

Afterwards run it with:

poetry run flask --app 'goodmap.goodmap:create_app(config_path="/PATH/TO/YOUR/CONFIG")' --debug run

Option	Description
USE_LAZY_LOADING	Loads point data only after the user clicks a point. If set to false, point data is loaded together with the initial map.
FAKE_LOGIN	If set to true, allows access to the admin panel by simply selecting the role instead of logging in. DO NOT USE IN PRODUCTION!
SHOW_ACCESSIBILITY_TABLE	If set as true it shows special view to help with accessing application.

Database

The database is stored in JSON, in the map section. For an example database see examples/e2e_test_data.json. The first subsection data consists of the actual datapoints, representing points on a map.

Datapoints have fields. The next subsections define special types of fields:

• obligatory_fields - here are explicitely stated all the fields that the application assumes are presnt in all datapoints. E.g.

"position",
"name",
"accessible_by"

TODO: obligatory_fields is a new subsection, start using it in the actual application

• categories - fields that can somehow be used in the app, for example by which datapoints can be filtered. Every category has a specified list of allowed values. E.g.

"accessible_by": ["bikes", "cars", "pedestrians"]

• visible_data - when a datapoint will be rendered as a pin on a map, these fields will be shown in the box when clicking on a pin. E.g.

"name",
"type_of_place"

• meta-data - some special data like

"uuid"

You can define the fields in all these subsections. Besides these types of fields, there is no restriction on the number of fields a datapoint can have.

Running E2E Tests

E2E tests use Playwright and require both servers to be running before invoking make e2e-tests:

make run-e2e-backend   # generates the e2e config/data, then serves the backend on :5000
make run-frontend      # webpack dev server on :8080
make e2e-tests         # checks both are up, then runs the tests

make run-e2e-backend regenerates the templated config and a fresh copy of the test data before starting, so no separate setup step is needed. make e2e-tests performs a single-shot check and exits with a helpful message if either server is missing.

Examples

You can find examples of working configuration and database in examples/ directory:

• e2e_test_config.yml - Basic configuration example
• e2e_test_data.json - Example database with sample location data
• mongo_e2e_test_config.yml - MongoDB configuration example

final test