docs: add extra info about technical decisions (react, python)

Author: spwoodcock

decisions/README.md

@@ -0,0 +1,67 @@
+# Use React as our main frontend library
+
+## Context and Problem Statement
+
+At HOTOSM we mostly develop web applications, which require a frontend
+component.
+
+We need to balance:
+
+- Complexity / learning curve.
+- Existing knowledge of staff.
+- Knowledge of key contractors for various tools.
+- Performance.
+- Existing library support (community & ecosystem).
+- Scalability & maintainability.
+
+## Considered Options
+
+- Angular
+- Vue
+- React
+- Svelte
+- Solid
+- Qwik
+- Vanilla JS + Web Components
+
+## Decision Outcome
+
+This decision was made many years ago (~2018) with the introduction
+of Tasking Manager v3.
+
+The decision was to use React, as that is where the industry was
+centered around at that time.
+
+Due to technical debt, skills / knowledge with React within the team, and
+with various contractors, this decision has been carried forward into
+future projects, in an attempt to standardize:
+
+- The learning curve / pool of experience.
+- Speed and ease of setting up new projects.
+- Avoiding the churn of frontend libraries: contractors must use React.
+
+This decision still stands as of 2025, however, it is becoming
+[increasingly apparent](https://www.zachleat.com/web/react-criticism)
+that this should be revisited in the near future.
+
+There is also the higher level discussion for
+[if we need a frontend framework at all](https://infrequently.org/2024/11/if-not-react-then-what),
+as much of our functionality could be implemented with simpler HTML-first
+technologies such as HTMX, with
+[progressive enhancement](https://www.gov.uk/service-manual/technology/using-progressive-enhancement).
+
+As a result, some flexibility is possible to choose more suitable tools for
+newly started projects.
+
+### Consequences
+
+- Good, the many people have React experience. It broadens the pool of available
+  contractors, and fits well with existing skills in the team.
+- Bad, because performance is superceded by frameworks that do not rely on the
+  virtual-DOM, such as Svelte and Solid.
+- Bad, because React is not as user friendly as it claims to be. It's far easier
+  to write bad React code, in comparison to frameworks like Svelte.
+- Bad, because this unfriendliness to new developers does not only affect performance,
+  but also extends to the code complexity and ease of understanding / onboarding.
+- Bad, because we don't necessarily need a web framework for all our tools!
+  We could probably build more resilient code using HTML with progressive enhancement.

decisions/0001-draw-io.md renamed to docs/decisions/0001-draw-io.md

@@ -0,0 +1,60 @@
+# Use Python as our main backend language
+
+## Context and Problem Statement
+
+At HOTOSM we mostly develop:
+
+- Web applications.
+- Data processing pipelines.
+
+We need a backend language that is:
+
+- Beginner friendly, allowing for easy community contribution.
+- Simply and quick to develop with, making us responsive when needed.
+- Reasonably performant.
+- General purpose, allowing us to achieve lots with the same skillset.
+- Good existing library support, reducing code duplication.
+
+## Considered Options
+
+- Python
+- Golang
+- Rust
+- C++
+- JavaScript
+- Java / Kotlin
+
+## Decision Outcome
+
+Python was chosen as the best compromise across all languages listed.
+
+JavaScript would have the benefit of keeping our stack to a single language,
+however, it is doesn't have great performance. It is also more complex than
+Python, particularly when it comes to asynchronous programming.
+
+Rust and C++ are too low-level and complex for our use cases (unless a specific
+performance critical need arises).
+
+Golang is an excellent beginners language, however, may be slightly too low-level
+to recommend it to everyone (requiring knowledge of pointers etc). It's a good
+choice for specific cases, but library support is also lacking.
+
+Java is popular because of historic use, and is still arguably a good language,
+however it's pros do not outweight the cons when compared to more modern
+languages such as Golang or Rust.
+
+### Consequences
+
+- Good, the many people have Python experience. It broadens the pool of available
+  contractors, and fits well with existing skills in the team.
+- Good, because it's the most versatile language listed as of 2025, including
+  excellent support for Web APIs, Machine Learning libraries, backend processing.
+- Good, because it's very intuitive and simple to learn, often being a great first
+  language to learn for junior developers.
+- Good, because of a huge amount of existing libraries in Python, meaning we have
+  to code less!
+- Bad, because we use separate languages for frontend / backend development.
+- Bad, it's not the most performant language of the bunch, particularly due to the
+  Global Interpreter Lock.
+- Bad, because far from perfect dependency management (which might be solved
+  with the advent of <https://github.com/astral-sh/uv>)

decisions/0002-mkdocs.md renamed to docs/decisions/0002-mkdocs.md

@@ -0,0 +1,7 @@
+# Architectural Decisions
+
+Markdown Architectural Decision Records documenting the technical decision
+taken across HOTOSM projects.
+
+These decisions are advisory, with some scope for variation in projects if
+specific requirements arise.

docs/decisions/0003-react.md

@@ -140,6 +140,11 @@ nav:
           # - Cheat Sheet: dev-guide/containers/containers-cheat-sheet.md
           - Local Kubernetes: dev-guide/containers/kubernetes-local-kind.md
           - Production DB: dev-guide/containers/production-db.md
+      - Tech Decisions:
+          - React: decisions/0003-react.md
+          - Python: decisions/0004-python.md
+          - API Documentation: decisions/0002-mkdocs.md
+          - Technical Diagrams: decisions/0001-draw-io.md
   - DevOps:
       - Reusable Workflows: https://hotosm.github.io/gh-workflows/
   - Our Development Practices: dev-practices.md