.. SPDX-FileCopyrightText: 2024 Jiri Vlasak
..
.. SPDX-License-Identifier: CC-BY-SA-4.0

Unofficial design documents for HOT Tasking Manager
===================================================

... to support `HOT Tasking Manager (HOT TM)`_ development, inspired by
the `tech debt`_ discussion.

- repository: https://git.sr.ht/~qeef/dd-hot-tm
- documentation: https://dd-hot-tm.tojemoje.site/

.. _HOT Tasking manager (HOT TM): https://wiki.openstreetmap.org/wiki/Tasking_Manager
.. _tech debt: https://github.com/hotosm/tasking-manager/discussions/6264

HOT TM is a collaborative mapping tool that helps mappers with the
management of mapping of large areas. It is the oldest one and the most
widely used tool for such a purpose.

Alternatives are `SimpleTaskManager`_ that aims on simplicity and has a
different workflow and `Divide and map. Now.`_ that aims on simplicity
and openness. However, neither of those alternatives implement the whole
range of the functionality of the HOT TM.

.. _SimpleTaskManager: https://wiki.openstreetmap.org/wiki/SimpleTaskManager
.. _Divide and map. Now.: https://wiki.openstreetmap.org/wiki/Divide_and_map._Now.

A lot is happening in the HOT TM development in recent years and clearly
there is a desire for the improvement. It's just not enough. What HOT TM
is still lacking to fight the technical debt, is a solid design.

Our *Unofficial design documents for HOT Tasking Manager* contain
descriptions of specific part of HOT TM and recommendations for the
implementation.


A note on technical debt
------------------------

We can find an explanation of what is `technical debt`_ for example at
Wikipedia. In these unofficial design documents, we understand the *tech
debt* as the difficulty of extending the functionality or fixing bugs --
the *difficulty of maintaining the code*.

.. _technical debt: https://en.wikipedia.org/wiki/Technical_debt


A note on stratified design
---------------------------

Examples and the explanations of the `stratified design`_ are discussed
in blog posts and books. In these unofficial design documents we
understand the stratas as *separated concerns* bridged by clearly
defined *interfaces*. In :ref:`backend diagram`, the stratas are shown
as rounded boxes.

A note on interfaces
--------------------

The interface consists of *procedure names* and `data transfer objects
(DTO)`_. The *DTO* is passed as an argument to the procedure to enable
communication between the stratas. In :ref:`backend diagram`, the
interfaces, i.e. procedure names and DTOs, are represented by the
two-sided arows. It is abstract representation -- arrows say nothing
about procedure names or DTOs, only about the existence of the
interfaces.

.. _stratified design: https://scribe.rip/clean-code-development/stratified-design-over-layered-design-125727c7e15
.. _data transfer objects (DTO): https://en.wikipedia.org/wiki/Data_transfer_object


Design documents for backend
----------------------------

This `repository`_ consists of the ``doc`` and ``hot_tm_proposal``
directories. The ``doc`` directory contains the source code for the
unofficial design documents that can be built using `Sphinx`_.  The
``hot_tm_proposal`` is Python3 package for the testing of the backend
design.

.. _repository: https://git.sr.ht/~qeef/dd-hot-tm
.. _Sphinx: https://www.sphinx-doc.org/en/master/

The backend of HOT TM covers several separated concerns, from *API* to
*Database*, as shown in the :ref:`backend diagram`:

.. graphviz::
   :name: backend diagram
   :caption: Backend diagram

    digraph {
        rankdir="LR"

        node [shape="none"]
        cliw [label="Web\npage"]
        josm [label="JOSM"]
        cli [label="Other\nclients"]

        node [shape="box" style="rounded"]
        api [label="API"]
        dots [label="..." shape="none"]
        db [label="Database"]

        edge [dir="both"]
        cli -> api [style="dotted"]
        cliw -> api [style="dotted"]
        josm -> api [style="dotted"]

        api -> dots -> db
    }


:ref:`backend diagram` and the packages described below outline the core
of the architecture of HOT TM. However, there are still many unknowns.
The following documents elaborate on specific backend problems like the
database schema, interfaces design and strata implementations.

.. toctree::
   :maxdepth: 1

   database-tasks-history
   api-endpoints


``hot_tm_proposal`` Python 3 package
------------------------------------

.. automodule:: hot_tm_proposal