Docs update (#105)

* Switch to MADR3 ADR format

* Move PUML diagrams and fix links

* Install Mermaid2 plugin

* Move documentation to mkdocs site and improve it

Signed-off-by: Federico Busetti <[email protected]>

Author: febus982

.adr-dir

@@ -9,7 +9,7 @@
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
 
-This is an example implementation of microservice applying
+This is an example implementation of a python application applying
 concepts from [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
 and [SOLID principles](https://en.wikipedia.org/wiki/SOLID).
 
@@ -18,53 +18,26 @@ and [SOLID principles](https://en.wikipedia.org/wiki/SOLID).
 * The application frameworks are decoupled from the domain logic
 * The storage layer is decoupled from the domain logic
 
-In this way our components are loosely coupled and the application logic
-(the domains package) is completely independent of the chosen framework
-and the persistence layer.
+This template provides out of the box some commonly used functionalities:
 
-## HTTP API Docs and versioning
+* API Documentation using [FastAPI](https://fastapi.tiangolo.com/)
+* Async tasks execution using [Celery](https://docs.celeryq.dev/en/stable/index.html)
+* Repository pattern for databases using [SQLAlchemy](https://www.sqlalchemy.org/) and [SQLAlchemy bind manager](https://febus982.github.io/sqlalchemy-bind-manager/stable/)
+* Database migrations using [Alembic](https://alembic.sqlalchemy.org/en/latest/) (configured supporting both sync and async SQLAlchemy engines)
+* [TODO] Producer and consumer to emit and consume events using [CloudEvents](https://cloudevents.io/) format on [Confluent Kafka](https://docs.confluent.io/kafka-clients/python/current/overview.html)
 
-API documentation is provided by [FastAPI](https://fastapi.tiangolo.com/features/)
-on `/docs` and `/redoc` paths using OpenAPI format.
+## Documentation
 
-I believe that versioning an API at resource level provides a much more
-flexible approach than versioning the whole API.
+The detailed documentation is available:
 
-The example `books` domain provides 2 endpoints to demonstrate this approach
+* Online on [GitHub pages](https://febus982.github.io/bootstrap-python-fastapi/)
+* Offline by running `make docs` after installing dependencies with `make dev-dependencies`
 
-* `/api/books/v1` (POST)
-* `/api/books/v2` (POST)
+## How to use
 
-## Package layers
-
-This application is structured following the principles of Clean Architecture.
-Higher level layers can import directly lower level layers. An inversion of control
-pattern has to be used for lower level layers to use higher level ones.
-
-Packages are ordered from the highest level to the lowest one.
-
-------
-
-* `alembic` (database migration manager)
-* `http_app` (http presentation layer)
-* `celery_worker` (async tasks runner)
-* `gateways` (database connection manager, repository implementation, event emitter, etc.)
-
-------
-
-* `domains` (services, repository interfaces)
-
-------
-
-## Class dependency schema
-
-![](architecture.png)
-
-## Data flow and layers responsibilities
-
-![](flow.png)
-
-## How to run
+Create your GitHub repository using this template (The big green `Use this template` button).
+Optionally tweak name and authors in the `pyproject.toml` file, however the metadata
+are not used when building the application, nor are referenced anywhere in the code.
 
 Using Docker:
 
@@ -104,4 +77,4 @@ The following setup makes sure the production image will keep to a minimal size
 Using the following pipeline the "test" image is instead ~850MB, more than 400MB that would
 end up as a cost in traffic on each image pull.
 
-![](docker-container.png)
+![](docs/puml/docker-container.png)

README.md

@@ -1,3 +1,9 @@
 nav:
   - Home: index.md
+  - api-documentation.md
+  - architecture.md
+  - src packages: packages
+  - inversion-of-control.md
+  - dockerfile.md
+  - ...
   - ADR: adr

architecture.png

@@ -0,0 +1,20 @@
+# source: https://github.com/adr/madr/blob/3.0.0/template/.markdownlint.yml
+default: true
+
+# Allow arbitrary line length
+#
+# Reason: We apply the one-sentence-per-line rule. A sentence may get longer than 80 characters, especially if links are contained.
+#
+# Details: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md013---line-length
+MD013: false
+
+# Allow duplicate headings
+#
+# Reasons:
+#
+# - The chosen option is considerably often used as title of the ADR (e.g., ADR-0015). Thus, that title repeats.
+# - We use "Examples" multiple times (e.g., ADR-0010).
+# - Markdown lint should support the user and not annoy them.
+#
+# Details: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md024---multiple-headings-with-the-same-content
+MD024: false

architecture.puml

@@ -1,3 +1,3 @@
 nav:
   - Summary: summary.md
-  - ...
+  - ... | regex=^\d{4}-

docker-container.png

@@ -1,19 +1,36 @@
-# 1. Record architecture decisions
-
-Date: 2024-01-11
-
-## Status
-
-Accepted
-
-## Context
-
-We need to record the architectural decisions made on this project.
-
-## Decision
-
-We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
-
-## Consequences
-
-See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).
+---
+# source: https://github.com/adr/madr/blob/3.0.0/template/adr-template.md
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+date: 2024-02-03
+# status: {proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)}
+# date: {YYYY-MM-DD when the decision was last updated}
+# deciders: {list everyone involved in the decision}
+# consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
+# informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
+---
+# Use Markdown Any Decision Records
+
+## Context and Problem Statement
+
+We want to record any decisions made in this project independent whether decisions concern the architecture ("architectural decision record"), the code, or other fields.
+Which format and structure should these records follow?
+
+## Considered Options
+
+* [MADR](https://adr.github.io/madr/) 3.0.0 – The Markdown Any Decision Records
+* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
+* Other templates listed at <https://schubmat.github.io/DecisionCapture>
+* Formless – No conventions for file format and structure
+
+## Decision Outcome
+
+Chosen option: "MADR 3.0.0", because
+
+* Implicit assumptions should be made explicit.
+  Design documentation is important to enable people understanding the decisions later on.
+  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+* MADR allows for structured capturing of any decision.
+* The MADR format is lean and fits our development style.
+* The MADR structure is comprehensible and facilitates usage & maintenance.
+* The MADR project is vivid.