damn_server

Access PostGIS database via JSON API.

The damn_server package is FastAPI application that receives collaborative mapping requests and updates the PostGIS database accordingly.

There are three tables in the database: current_areas, current_squares, and current_commits. (The database also contains users table with basic information about users, like display_name.) The basic idea of the database is that users (mappers) can only add areas or commits. Users can not delete or change anything in the database. (Some updates, like area statistics, as well as some deletions, like finished areas, are done by the damn_upkeep package.)

Typical mapping workflow is map-review-done: A mapper sends map some square of the area request. The server locks a square and responds with the area identifier, the square identifier, and the square border. When finished, the mapper sends ready for review request. The server unlocks the square of the area and sets the square to be ready for the review. The same works for a reviewer.

Following mappers can only add areas principle, when creation of the new area is requested, the server saves the area to the current_areas table, creates new squares of the area in the current_squares table, and creates corresponding commits in the current_commits table.

Following mappers can only add commits principle, when the server is requested to map some square of the area, the server: 1) inspects the last commit of each square of the area, 2) finds the commits with to map type, effectively filtering the squares that should be mapped, 3) choose one of those squares and creates new locked type commit for that square in the current_commits table, and 4) finally responds with the area identifier, the square identifier, and the square border. All of the steps above is the single SQL query. Commits are only added so the whole history is available.

Main functionality is implemented in procedures. Classes are used solely as the structures to store the data. Configuration persists in conf module and can be loaded from the environment variables.

There are two “border” modules. db handles pool to PostGIS database (but does not contain queries) and api serves (HTTP) endpoints that use classes (from the other modules) as the structures for the communication.

The rest of the modules contain classes (the structures to store data), and procedures that manipulate the database (based on the data).

area module contains classes and procedures with SQL queries to manage saving, loading, and updating of the areas.

list_of module contains classes and procedures with SQL queries to handle getting lists of data from the database.

new module is about commits, effectively handling input from the mappers, like changing the state of the squares (to map, mapped, to review, done, …)

square module only contains the database requests to retrieve square’s border and recomputes the border to GeoJSON or GPX.

user module contains class and procedures with SQL queries to manage saving, loading, and updating of the user’s information.

I found out that it is sometimes hard to write docstrings. When the docstring is missing, please, see the source code.

Modules

damn_server.api	Web app serving JSON API.
damn_server.area	Procedures and classes for managing an area.
damn_server.conf	Configuration constants.
damn_server.db	Manage pool of async connections to the PostGIS database.
damn_server.list_of	Procedures related to lists of whatever.
damn_server.new	Add new commit to the database.
damn_server.square	Get square's border from the database.
damn_server.user	Procedures related to managing users in the database.