* Rename common to bootstrap (meaningful naming)

* Move storage initialisation from `gateways` to `bootstrap`

* Update documentation

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

Author: febus982

Dockerfile

@@ -68,7 +68,7 @@ COPY --chown=nonroot:nonroot poetry.lock .
 COPY --chown=nonroot:nonroot src/alembic ./alembic
 COPY --chown=nonroot:nonroot src/domains ./domains
 COPY --chown=nonroot:nonroot src/gateways ./gateways
-COPY --chown=nonroot:nonroot src/common ./common
+COPY --chown=nonroot:nonroot src/bootstrap ./bootstrap
 COPY --chown=nonroot:nonroot src/alembic.ini .
 COPY --chown=nonroot:nonroot Makefile .
 

docs/api-documentation.md

@@ -14,5 +14,6 @@ The example `books` domain provides 2 endpoints to demonstrate this approach
 * `/api/books/v2` (POST)
 
 /// note | Media type versioning
+
 An improvement could be moving to [media type versioning](https://opensource.zalando.com/restful-api-guidelines/#114)
 ///

docs/inversion-of-control.md

@@ -58,7 +58,7 @@ class BookService:
     ) -> None:
         self.book_repository = book_repository
 
-# file `common/di_container.py`
+# file `bootstrap/di_container.py`
 from sqlalchemy_bind_manager._repository import SQLAlchemyAsyncRepository
 from dependency_injector.containers import DeclarativeContainer
 from dependency_injector.providers import Factory
@@ -196,18 +196,20 @@ the life cycle of the concrete classes is handled in the correct order
 and we don't end up in circular dependencies.
 ///
 
-
 ```python
-# file `common/factories.py`
+# file `bootstrap/factories.py`
 from domains.books._data_access_interfaces import BookRepositoryInterface
 
+
 def book_repository_factory() -> BookRepositoryInterface:
     from sqlalchemy_bind_manager._repository import SQLAlchemyAsyncRepository
     return SQLAlchemyAsyncRepository()
 
+
 # file `domains/books/service.py`
 from domains.books._data_access_interfaces import BookRepositoryInterface
-from common.factories import book_repository_factory
+from bootstrap.factories import book_repository_factory
+
 
 class BookService:
     book_repository: BookRepositoryInterface
@@ -258,13 +260,13 @@ We would need to implement the functionalities a dependency injection container
 ///
 
 ```python
-# file `common/injectors.py` (Theoretical)
+# file `bootstrap/injectors.py` (Theoretical)
 def inject_book_repository(f):
     @functools.wraps(f)
     def wrapper(*args, **kwds):
         # This allows overriding the decorator
         if "book_repository" not in kwds.keys():
-            from gateways.storage import BookRepository
+            from bootstrap.storage import BookRepository
             kwds["book_repository"] = BookRepository()
         elif not isinstance(kwds["book_repository"], BookRepositoryInterface):
             import warnings

docs/packages/bootstrap.md

@@ -0,0 +1,30 @@
+# Bootstrap
+
+The `bootstrap` module contains logic that is shared among the external layer
+(i.e. `http_app`, `celery_worker`, etc.).
+
+It contains 3 submodules (and related responsibilities):
+
+* `bootstrap.bootstrap`: The application initialisation logic (database, logging,
+  celery tasks) necessary to run the domain logic. It uses `bootstrap.config` and
+  `bootstrap.di_container` subpackages. It does not contain the specific HTTP
+  framework initialisation (or other frameworks such as GRPC).
+* `bootstrap.config`: The application config models, based on `BaseSettings`
+  and `BaseModel` from `pydantic` package to get the values from
+  environment variables.
+* `bootstrap.di_container`: The dependency injection container configuration.
+* `bootstrap.storage`: The storage configuration (SQLAlchemy). This setup uses
+  [Imperative Mapping](https://docs.sqlalchemy.org/en/20/orm/mapping_styles.html#imperative-mapping)
+  so that our models remains simple classes.
+
+/// warning | Note about SQLAlchemy ORM Imperative Mapping
+
+Even if the code for models appears to remain simple classes, imperative mapping
+transforms them behind the scenes. However, the code in our application should not
+rely on such specific capabilities otherwise we would bind our code to SQLAlchemy.
+
+To handle database operations we use a repository class that is aware of SQLAlchemy.
+In this way, should we need to change our storage implementation (e.g. switch to MongoDB),
+we'll only need to change the repository class, without having to change anything in
+our application logic.
+///

docs/packages/common.md

@@ -79,7 +79,7 @@ branch = true
 source = ["src"]
 omit = [
     "src/alembic/*",
-    "src/common/config.py",
+    "src/bootstrap/config.py",
 ]
 # It's not necessary to configure concurrency here
 # because pytest-cov takes care of that

pyproject.toml

@@ -1,8 +1,8 @@
 import logging
 from asyncio import get_event_loop
 
-from common.bootstrap import application_init
-from common.config import AppConfig
+from bootstrap.bootstrap import application_init
+from bootstrap.config import AppConfig
 from sqlalchemy.ext.asyncio import AsyncEngine
 
 from alembic import context

src/alembic/env.py

@@ -0,0 +1,2 @@
+from .bootstrap import application_init
+from .config import AppConfig

src/bootstrap/__init__.py

@@ -2,11 +2,11 @@
 from dependency_injector.containers import DynamicContainer
 from dependency_injector.providers import Object
 from domains import init_celery, init_domains
-from gateways.storage import init_storage
 from pydantic import BaseModel, ConfigDict
 
 from .config import AppConfig, init_logger
 from .di_container import Container
+from .storage import init_storage
 
 
 class InitReference(BaseModel):