From 4c4e078581532925e37cdcd47e7657295faee798 Mon Sep 17 00:00:00 2001
From: pacien
Date: Wed, 28 Jul 2021 16:58:04 +0200
Subject: docs: motivate FastAPI framework choice

---
 readme.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/readme.md b/readme.md
index b5844f2..6fab8d8 100644
--- a/readme.md
+++ b/readme.md
@@ -110,6 +110,59 @@ of annotated raw SQL queries, exposing them as callable Python functions.
 [embrace]: https://pypi.org/project/embrace/
 [DAO]: https://en.wikipedia.org/wiki/Data_access_object
 
+#### CGI scripts vs. Services
+
+The most simple and primitive way of making Python programs accessible from a
+web browser would be through the Common Gateway Interface ([CGI]). Through it,
+the user is able to execute the scripts by visiting a matching URL, to then
+visualise its output directly in their browser.
+
+[CGI]: https://en.wikipedia.org/wiki/Common_Gateway_Interface
+
+The other approach is to make the program a server application as a persistent
+service process, in charge of accepting, handling and replying to network
+requests by itself.
+
+The former, identical to the way the oldest PHP scripts are run, has become
+less popular in favour of the latter, mainly for performance and
+maintainability concerns for real applications outside of trivial, independent,
+and self-contained scripts. For those reasons, this project will be implemented
+as a service process.
+
+#### Comprehensive vs. Light-weight frameworks
+
+While bare Python could be used to create such a web service, it is desirable
+to work at a higher abstraction level to focus on the application-specific
+features rather than the standard protocol implementation details.
+
+Python frameworks such as [Django] offer comprehensive solutions for building
+web applications based on the Model-View-Controller ([MVC] or MTV/MVT) design
+pattern, ensuring [separation of concerns] while abstracting lower level logic.
+This kind of complete solutions provide routing logic to map requests to
+user-defined handlers, and are integrated with a Object-Relational Mapper as
+well as with a templating engine to generate HTML pages dynamically.
+
+[Django]: https://www.djangoproject.com/
+[MVC]: https://en.wikipedia.org/wiki/Model-view-controller
+[separation of concerns]: https://en.wikipedia.org/wiki/Separation_of_concerns
+
+Other more light-weight frameworks such as [Flask] or the more recent [FastAPI]
+instead focus on the first part, taking care of unpacking and routing requests
+to the user-defined handlers, while leaving the rest to the application
+developers. This approach does not fully impose an entire environment, and
+allows better composability with libraries which can be freely chosen.
+
+[Flask]: https://flask.palletsprojects.com/
+[FastAPI]: https://fastapi.tiangolo.com/
+
+Because the use of an ORM is not desirable in this project for the reasons
+detailed in a previous section, the choices of frameworks is limited to these
+light-weight frameworks. Here, FastAPI is preferred over Flask due to its more
+modern architecture, using parameters and [dependency injection] over
+thread-local global variables.
+
+[dependency injection]: https://en.wikipedia.org/wiki/Dependency_injection
+
 ### Project structure overview
 
 * `./sql/`
-- 
cgit v1.2.3