Merge pull request #6215 from robsavoye/develop

Add doc to explain diagrams

docs/about.md

@@ -4,28 +4,35 @@
 [![TM Backend on Quay](https://quay.io/repository/hotosm/tasking-manager/status "Tasking Manager Backend Build")](https://quay.io/repository/hotosm/tasking-manager)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=hotosm_tasking-manager&metric=alert_status)](https://sonarcloud.io/dashboard?id=hotosm_tasking-manager)
 
-[<img src="images/screenshot.jpg" />](../images/screenshot.jpg)
-
-The most popular tool for teams to coordinate mapping on OpenStreetMap. With this web application, an area of interest can be defined and divided up into smaller tasks that can be completed rapidly. It shows which areas need to be mapped and which areas need a review for quality assurance. You can see the tool in action: log into the widely used [HOT Tasking Manager](https://tasks.hotosm.org/) and start mapping.
-
-This is Free and Open Source Software. You are welcome to use the code and set up your own instance. The Tasking Manager has been initially designed and built by and for the [Humanitarian OpenStreetMap Team](https://www.hotosm.org/), and is nowadays used by many communities and organizations.
+![<img src="images/screenshot.jpg" />](images/screenshot.jpg)
+
+The most popular tool for teams to coordinate mapping on
+OpenStreetMap. With this web application, an area of interest can be
+defined and divided up into smaller tasks that can be completed
+rapidly. It shows which areas need to be mapped and which areas need a
+review for quality assurance. You can see the tool in action: log into
+the widely used [HOT Tasking Manager](https://tasks.hotosm.org/) and
+start mapping.
+
+This is Free and Open Source Software. You are welcome to use the code
+and set up your own instance. The Tasking Manager has been initially
+designed and built by and for the [Humanitarian OpenStreetMap
+Team](https://www.hotosm.org/), and is nowadays used by many
+communities and organizations.
 
 ## Get involved!
 
-* Start by reading our [Code of conduct](docs/code_of_conduct.md)
-* Get familiar with our [contributor guidelines](docs/contributing.md) explaining the different ways in which you can support this project! We need your help!
-* Join the Tasking Manager Collective Meet up - an opportunity to meet other Tasking Manager contributors. The meet ups take place on the second Wednesday of the month at 9:00 or 15:00UTC! Register to receive a calendar invite: https://bit.ly/3s6ntmV or join directly via this link: https://meet.jit.si/TaskingManagerCollectiveMeetUp
+* Join a Tasking Manager [working group](working-groups.md)
+* Start by reading our [Code of conduct](developers/code_of_conduct.md)
+* Get familiar with our [contributor guidelines](developers/contributing.md)
+  explaining the different ways in which you can support this project!
+  We need your help!
 * Read the monthly update blogs on [OSM Discourse](https://community.openstreetmap.org/c/general/38/all).
 
 ## Product Roadmap
-We have included below a [high level roadmap/plan](https://github.com/orgs/hotosm/projects/28/) [subject to change] that can be used as an overview.
-
-
-## Developers
-
-* [Setup the TM for development](developers/development-setup.md)
-* [Learn about versions and releases](developers/versions-and-releases.md)
-* Help us and submit [pull requests](https://github.com/hotosm/tasking-manager/pulls)
+We have included below a [high level
+roadmap/plan](https://github.com/orgs/hotosm/projects/28/) [subject to
+change] that can be used as an overview.
 
 ## Instances
 * [HOT Tasking Manager (production)](https://tasks.hotosm.org)

docs/dataflow.md

@@ -0,0 +1,64 @@
+# Tasking Manager Dataflow
+
+## Activity
+
+The Tasking Manager has several user data flows, as there are
+differences between a project manager, a mapper, and a validator as
+seen in this diagram.
+
+<a href="images/activity.png">
+![Activity](images/activity.png){ width=30%,height:30px }</a>
+
+Initially most Tasking Manager projects start with a disaster
+notification. The activation team discusses the notification, and if a
+response is needed creates a project. The project is an Area Of
+Interest (AOI) as a polygon, and a description and instructions. Then
+the AOI is split into tasks.
+
+Then when the project is announced, mappers select a task, and map the
+desired features for the project. Once the complete a task, it's
+marked as mapped, and then the mapper can select another task, and so
+on.
+
+Then the validator reviews all the tasks marked as mapped. There is
+more information on the [Validation process](validation.md) at this
+link.
+
+# Solution User
+
+<a href="https://raw.githubusercontent.com/hotosm/tasking-manager/develop/docs/images/solution-user.png">
+![Solution User](images/solution-user.png){ width=30%,height:30px }</a>
+
+## Component
+
+The Tasking Manager has multiple components. WHat the user sees is the
+REACT based frontend in their browser.
+<a href="https://raw.githubusercontent.com/hotosm/tasking-manager/develop/docs/images/component.png">
+![Component](images/component.png){ width=40%,height:30px }</a>
+
+The backend for the Tasking Mamnager is written using Flask, which is
+in python. This supplies the REST API, which the frontend uses. This
+API is also open to other projects.
+
+The data of course is OpenStreetMap, which is stored in a postgres
+database.
+
+## Conceptual
+
+The Tasking Manager uses other projects for some of it's data needs of
+the backend. This includes Oshome for mapping statistics, the HOT raw
+data API for data extracts, and OpenStreetMap of course.
+
+<a href="https://raw.githubusercontent.com/hotosm/tasking-manager/develop/docs/images/conceptual.png">
+![Conceptual](images/conceptual.png){ width=30%,height:30px }</a>
+
+# Information Flow
+
+This diagram shows the other projects that the Tasking Manager
+exchanges informstion with. OpenStreetNap(OSM) of course supplies
+data, and data from Tasking Manager projects goes into
+OSM. OpenAerialMap may be used as a source of imagery. Also projects
+may be transfered thh the Field Mapping Tasking Manager(FMTM).
+
+<a href="https://raw.githubusercontent.com/hotosm/tasking-manager/develop/docs/images/information_flow.png">
+![Information Flow](images/information_flow.png){ width=30%,height:30px }</a>

docs/contributing.md → docs/developers/contributing.md

@@ -59,7 +59,7 @@ testing, please comment on the PR directly.
 
 Create pull requests (PRs) for changes that you think are needed. We
 would really appreciate your help! We ask that you follow our [coding
-contribution guidelines](developers/contributing-guidelines.md)
+contribution guidelines](contributing-guidelines.md)
 
 Skills with the following would be beneficial:
 
@@ -76,7 +76,7 @@ Our latest task board can be found
 ## Translating
 
 Review or submit [language
-translations](developers/translations.md). Translations are important
+translations](translations.md). Translations are important
 as it makes Tasking Manager more efficient when it supports local
 languages.
 

docs/developers/development-setup.md

@@ -57,7 +57,9 @@ To learn React, check out the [React documentation](https://reactjs.org/).
 
 ### Backend
 
-The backend is made up of a postgres database and an associated API that calls various end points to create tasks, manage task state, and produce analytics.
+The backend is made up of a postgres database and an associated API
+that calls various end points to create tasks, manage task state, and
+produce analytics.
 
 #### Dependencies
 
@@ -67,15 +69,22 @@ The backend is made up of a postgres database and an associated API that calls v
 * [pip](https://pip.pypa.io/en/stable/installing/)
 * [libgeos-dev](https://trac.osgeo.org/geos/)
 
-You can check the [Dockerfile](../scripts/docker/tasking-manager/Dockerfile) to have a reference of how to install it in a Debian/Ubuntu system.
+You can check the
+[Dockerfile](https://github.com/hotosm/tasking-manager/blob/develop/Dockerfile)
+to have a reference of how to install it in a Debian/Ubuntu system.
 
 #### Configuration
 
-There are two ways to configure Tasking Manager. You can set some environment variables on your shell or you can define the configuration in the `tasking-manager.env` file on the repository root directory. To use that last option, follow the below instructions:
+There are two ways to configure Tasking Manager. You can set some
+environment variables on your shell or you can define the
+configuration in the `tasking-manager.env` file on the repository root
+directory. To use that last option, follow the below instructions:
 
-* Copy the example configuration file to start your own configuration: `cp example.env tasking-manager.env`.
+* Copy the example configuration file to start your own configuration:
+  `cp example.env tasking-manager.env`.
 * Adjust the `tasking-manager.env` configuration file to fit your configuration.
-* Make sure that the following variables are set correctly in the `tasking-manager.env` configuration file:
+* Make sure that the following variables are set correctly in the
+  `tasking-manager.env` configuration file:
   - `TM_APP_BASE_URL`=web-server-endpoint
   - `POSTGRES_DB`=tasking-manager-database-name
   - `POSTGRES_USER`=database-user-name
@@ -113,7 +122,8 @@ In order to send email correctly, set these variables as well:
 
 #### Tests
 
-The project includes a suite of Unit and Integration tests that you should run after any changes
+The project includes a suite of Unit and Integration tests that you
+should run after any changes.
 
 ```
 python3 -m unittest discover tests/backend
@@ -134,7 +144,13 @@ cd frontend && yarn build-locales
 
 #### Create a fresh database
 
-We use [Flask-Migrate](https://flask-migrate.readthedocs.io/en/latest/) to create the database from the migrations directory. Check the instructions on how to setup a PostGIS database with [docker](#creating-a-local-postgis-database-with-docker) or on your [local system](#non-docker). Then you can execute the following command to apply the migrations:
+We use
+[Flask-Migrate](https://flask-migrate.readthedocs.io/en/latest/) to
+create the database from the migrations directory. Check the
+instructions on how to setup a PostGIS database with
+[docker](#creating-a-local-postgis-database-with-docker) or on your
+[local system](#non-docker). Then you can execute the following
+command to apply the migrations:
 
 ```
 flask db upgrade
@@ -146,23 +162,35 @@ pdm run upgrade
 
 #### Set permissions to create projects
 
-To be able to create projects and have full permissions as an admin user inside TM, login to the TM with your OSM account to populate your user information in the database, then execute the following command on your terminal (with the OS user that is the owner of the database):
+To be able to create projects and have full permissions as an admin
+user inside TM, login to the TM with your OSM account to populate your
+user information in the database, then execute the following command
+on your terminal (with the OS user that is the owner of the database):
 
 `psql -d <your_database> -c "UPDATE users set role = 1 where username = '<your_osm_username>'"`
 
 ### API
 
-If you plan to only work on the API you only have to build the backend architecture. Install the backend dependencies, and run the server:
+If you plan to only work on the API you only have to build the backend
+architecture. Install the backend dependencies, and run the server:
 
 `flask run --debug --reload` or  `pdm run start`
 
-You can access the API documentation on [http://localhost:5000/api-docs](http://localhost:5000/api-docs), it also allows you to execute requests on your local TM instance. The API docs is also available on our [production](https://tasks.hotosm.org/api-docs) and [staging](https://tasks-stage.hotosm.org/api-docs/) instances.
+You can access the API documentation on
+[http://localhost:5000/api-docs](http://localhost:5000/api-docs), it
+also allows you to execute requests on your local TM instance. The API
+docs is also available on our
+[production](https://tasks.hotosm.org/api-docs) and
+[staging](https://tasks-stage.hotosm.org/api-docs/) instances.
 
 #### API Authentication
 
 In order to authenticate on the API, you need to have an Authorization Token.
 
-1. Run the command line `manage.py` via `flask` with the `gen_token` option and `-u <OSM_User_ID_number>`. The command line can be run in any shell session as long as you are in the tasking-manager directory.
+1. Run the command line `manage.py` via `flask` with the `gen_token`
+   option and `-u <OSM_User_ID_number>`. The command line can be run
+   in any shell session as long as you are in the tasking-manager
+   directory.
 
 ```
 flask gen_token -u 99999999
@@ -174,27 +202,38 @@ This will generate a line that looks like this:
 2. In the Swagger UI, where it says
 > Token sessionTokenHere==
 
-replace `sessionTokenHere==` with the string of characters between the apostrophes (' ') above so you end up with something that looks like this in that field:
+replace `sessionTokenHere==` with the string of characters between the
+apostrophes (' ') above so you end up with something that looks like
+this in that field:
 
 > Token SWpFaS5EaEoxRlEubHRVC1DSTVJZ2hfalMc0xlalu3KRk5BUGk0
 
-Your user must have logged in to the local testing instance once of course and have the needed permissions for the API call.
+Your user must have logged in to the local testing instance once of
+course and have the needed permissions for the API call.
 
-You can get your OSM user id number either by finding it in your local testing/dev database `select * from users` or from OSM by viewing the edit history of your user, selecting a changeset from the list, and then at the bottom link `Changeset XML` and it will be in the `uid` field of the XML returned.
+You can get your OSM user id number either by finding it in your local
+testing/dev database `select * from users` or from OSM by viewing the
+edit history of your user, selecting a changeset from the list, and
+then at the bottom link `Changeset XML` and it will be in the `uid`
+field of the XML returned.
 
 #### API Authentication on remote instance
 
-To get your token on the production or staging Tasking Manager instances, sign in in the browser and then either:
-
-- go to the user profile page, enable _Expert mode_ in the settings, and copy the token from the _API Key_ section.
-- inspect a network request and search for the `Authorization` field in the request headers section.
+To get your token on the production or staging Tasking Manager
+instances, sign in in the browser and then either:
 
+- go to the user profile page, enable _Expert mode_ in the settings,
+  and copy the token from the _API Key_ section.
+- inspect a network request and search for the `Authorization` field
+  in the request headers section.
 
 # Docker
 
 ## Creating a local PostGIS database with Docker
 
-If you're not able to connect to an existing tasking-manager DB, we have a [Dockerfile]() that will allow you to run PostGIS locally as follows.
+If you're not able to connect to an existing tasking-manager DB, we
+have a [Dockerfile]() that will allow you to run PostGIS locally as
+follows.
 
 ### Dependencies
 
@@ -210,13 +249,15 @@ Following must be available locally:
 docker build -t tasking-manager-db ./scripts/docker/postgis
 `
 
-2. The image should be downloaded and build locally.  Once complete you should see it listed, with
+2. The image should be downloaded and build locally.  Once complete
+   you should see it listed, with
 
 `
 docker images
 `
 
-3. You can now run the image (this will run PostGIS in a docker container, with port 5432 mapped to localhost):
+3. You can now run the image (this will run PostGIS in a docker
+   container, with port 5432 mapped to localhost):
 
 `
 docker run -d -p 5432:5432 tasking-manager-db
@@ -228,23 +269,29 @@ docker run -d -p 5432:5432 tasking-manager-db
 docker ps
 `
 
-5. Finally you can set your env variable to point at your containerised DB:
+5. Finally you can set your env variable to point at your
+   containerised DB:
 
 `
 export TM_DB=postgresql://hottm:hottm@localhost/tasking-manager
 `
 
-6.  Refer to the rest of the instructions in the README to setup the DB and run the app
+6.  Refer to the rest of the instructions in the README to setup the
+    DB and run the app.
 
 # Non-Docker
 
 ## Creating the PostGIS database
 
-It may be the case you would like to set up the database without using Docker for one reason or another. This provides you with a set of commands to create the database and export the database address to allow you to dive into backend development.
+It may be the case you would like to set up the database without using
+Docker for one reason or another. This provides you with a set of
+commands to create the database and export the database address to
+allow you to dive into backend development.
 
 ### Dependencies
 
-First, ensure that Postgresql and PostGIS are installed and running on your computer.
+First, ensure that Postgresql and PostGIS are installed and running on
+your computer.
 
 ### Create the database user and database
 
@@ -265,9 +312,12 @@ export TM_DB=postgresql://hottm:hottm@localhost/tasking-manager
 `
 
 
-It is possible to install and run the Tasking Manager using [Docker](https://docker.com) and [Docker Compose](https://docs.docker.com/compose/).
+It is possible to install and run the Tasking Manager using
+[Docker](https://docker.com) and [Docker
+Compose](https://docs.docker.com/compose/).
 
-Clone the Tasking Manager repository and use `docker-compose up` to get a working version of the API running.
+Clone the Tasking Manager repository and use `docker-compose up` to
+get a working version of the API running.
 
 ## Sysadmins guide