damn_server

Access PostGIS database via JSON API.

The damn_server package is FastAPI application that translates requests of mappers to PostGIS database queries.

There are three tables in the database: current_areas, current_squares, and current_commits. (The database also contains the fourth users table with basic information about users, like display_name.) See 20_create_damn_db.sql file to inspect the structure of the tables.

The access to the database is handled by the db module. db keeps the pool of async database connections, but there are no queries.

Queries to manipulate the database are inside the procedures of area, list_of, new, square and user modules. These modules also contain classes – data structures used solely to describe the format of the data to work with.

These classes are used in the api module that serves HTTP endpoints. Finally, the configuration persists in the conf module and is loaded from the environment variables.

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 needs review request. The server unlocks the square of the area and sets the square to be ready for the review. Now it’s up to a reviewer to pick some square to review and decide if it needs more mapping or is done.

The basic idea of the database is that mappers only add commits. What does it mean for the typical mapping workflow? Let’s see. When the server receives a request 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 needs mapping, 3) chooses one of those squares and adds new commit with locked type and the square’s identifier to the current_commits, and finally 4) responds with the area identifier, the square identifier, and the square border. Steps (1-3) are the single SQL query. (4) is another, read-only query to retrieve the square’s border.

Processing the needs review request is a bit simpler. In such a case the server: 1) checks that the last commit of the squre that needs review has type locked and that the mapper is the author of the commit and 2) adds new commit with to review type and the square’s identifier to the current_commits.

So the mappers only add commits to the database. Nothing is updated or deleted. The consequence is that the whole history of all the area’s squares is available.

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.