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
Web app serving JSON API. |
|
Procedures and classes for managing an area. |
|
Configuration constants. |
|
Manage pool of async connections to the PostGIS database. |
|
Procedures related to lists of whatever. |
|
Add new commit to the database. |
|
Get square's border from the database. |
|
Procedures related to managing users in the database. |