Merge pull request #106 from febus982/refactor

Application structure refactor

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 .
 

docker-compose.yaml

@@ -17,6 +17,8 @@ services:
     environment:
       OTEL_SERVICE_NAME: "bootstrap-fastapi-worker"
       OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
+      CELERY__broker_url: "redis://redis:6379/0"
+      CELERY__result_backend: "redis://redis:6379/1"
     volumes:
       - './src:/app'
       - './pyproject.toml:/app/pyproject.toml'
@@ -33,6 +35,8 @@ services:
     environment:
       OTEL_SERVICE_NAME: "bootstrap-fastapi-worker"
       OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
+      CELERY__broker_url: "redis://redis:6379/0"
+      CELERY__result_backend: "redis://redis:6379/1"
     volumes:
       - './src:/app'
       - './pyproject.toml:/app/pyproject.toml'
@@ -56,6 +60,8 @@ services:
     environment:
       OTEL_SERVICE_NAME: "bootstrap-fastapi-dev"
       OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
+      CELERY__broker_url: "redis://redis:6379/0"
+      CELERY__result_backend: "redis://redis:6379/1"
     ports:
       - '8000:8000'
     volumes:
@@ -86,6 +92,8 @@ services:
     environment:
       OTEL_SERVICE_NAME: "bootstrap-fastapi-http"
       OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
+      CELERY__broker_url: "redis://redis:6379/0"
+      CELERY__result_backend: "redis://redis:6379/1"
     ports:
       - '8001:8000'
     volumes:

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

@@ -38,31 +38,36 @@ the concrete class whenever the protocol is expected:
 def main():
     Container()
     service = BookService()
-    
-# file `books/_data_access_interfaces.py`
+
+
+# file `books/_gateway_interfaces.py`
 class BookRepositoryInterface(Protocol):
     async def save(self, book: BookModel) -> BookModel:
         ...
 
-# file `domains/books/service.py`
-from domains.books._data_access_interfaces import BookRepositoryInterface
+
+# file `domains/books/_service.py`
+from domains.books._gateway_interfaces import BookRepositoryInterface
 from dependency_injector.wiring import Provide, inject
 
+
 class BookService:
     book_repository: BookRepositoryInterface
 
     @inject
     def __init__(
-        self,
-        book_repository: BookRepositoryInterface = Provide["book_repository"],
+            self,
+            book_repository: BookRepositoryInterface = Provide["book_repository"],
     ) -> 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
 
+
 class Container(DeclarativeContainer):
     # Note that dependency-injector package only allows string references
     book_repository: Factory[BookRepositoryInterface] = Factory(
@@ -122,24 +127,27 @@ concrete classes because nested imported modules, solving nothing.
 ///
 
 ```python
-# file `domains/books/service.py`
+# file `domains/books/_service.py`
 from dependency_injector.containers import DynamicContainer
-from domains.books._data_access_interfaces import BookRepositoryInterface
+from domains.books._gateway_interfaces import BookRepositoryInterface
+
 
 class BookService:
     book_repository: BookRepositoryInterface
 
     def __init__(
-        self,
-        container: DynamicContainer,
+            self,
+            container: DynamicContainer,
     ) -> None:
         self.book_repository = container.book_repository()
 
+
 # entrypoint
-from domains.books.service import BookService
+from domains.books._service import BookService
 from dependency_injector.providers import Factory
 from sqlalchemy_bind_manager._repository import SQLAlchemyAsyncRepository
 
+
 def main():
     container = DynamicContainer()
     # Note that dependency-injector package only allows string references
@@ -196,18 +204,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`
-from domains.books._data_access_interfaces import BookRepositoryInterface
+# file `bootstrap/factories.py`
+from domains.books._gateway_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
+
+# file `domains/books/_service.py`
+from domains.books._gateway_interfaces import BookRepositoryInterface
+from bootstrap.factories import book_repository_factory
+
 
 class BookService:
     book_repository: BookRepositoryInterface
@@ -258,13 +268,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` package contains logic that is shared among the external layer
+(i.e. `http_app`, `celery_worker`, etc.).
+
+It contains the following submodules and packages (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/celery_worker.md

@@ -1,6 +1,6 @@
 # Celery worker
 
-The `celery_worker` module is a small entrypoint to run Celery workers and beat.
+The `celery_worker` package is a small entrypoint to run Celery workers and beat.
 
 The `Celery` class has to be initialised to invoke tasks from domain logic,
 in addition to the worker, therefore we initialise it together with the generic

docs/packages/common.md

@@ -1,6 +1,6 @@
 # Domains
 
-The `domains` module contains all the application domain logic separated by domains
+The `domains` package contains all the application domain logic separated by domains
 (this template provides a single domain: `books`).
 
 Each domain should be self-contained and not invoke logic from other domains directly.
@@ -15,4 +15,34 @@ Using interfaces will:
 
 ## Book domain structure
 
-[TODO] Refactor needed to implement a better structure to the domain
+The `domains.book` package provides an example implementation for a domain. It contains
+a list of public and protected modules.
+
+Public package and modules are used by the application to invoke the
+domain functionalities:
+
+* The main `domains.book` package provides the entrypoint for our application:
+  the `BookService` class. We export it here from the `domains.book._service`
+  module to hide protected entities that should not be accessed directly.
+* The `domains.book.interfaces` provides the `BookServiceInterface` protocol
+  to be used for Inversion of Control (we don't currently use it in this
+  application because Clean Architecture doesn't enforce Inversion of Control
+  from the `http` application, and we don't have yet implemented other domains)
+* The `domains.book.dto` provides the data transfer objects required to invoke
+  the `BookService` class.
+* The `domains.book.events` provides the event data structures that the domain
+  is able to emit. They can be used by other domains to implement event handlers.
+
+Protected package and modules are used by the implementation of the books domain
+and can be used to bootstrap the application:
+
+* The `domains.book._gateway_interfaces` contains the gateway protocols against
+  which the domain logic is implemented. We use them to configure the dependency
+  injection container.
+* The `domains.book._models` contains the domain models. We use them also
+  to bootstrap the SQLAlchemy imperative mapping in `bootstrap.storage.SQLAlchemy`
+  package.
+* The `domains.book._service` contains the `BookService` implementation.
+* The `domains.book._tasks` contains the implementation of celery tasks
+  for operations that can be queued without waiting for a result (e.g.
+  send an email, invalidate cache).

docs/packages/domains.md

@@ -1,6 +1,6 @@
 # Gateways
 
-The `gateways` module contains the implementations of the drivers
+The `gateways` package contains the implementations of the drivers
 handling communication with external services (i.e. database repositories,
 event producers, HTTP clients).
 

docs/packages/gateways.md

@@ -1,4 +1,4 @@
 # HTTP App
 
-The `http_app` module contains the implementation of [FastAPI](https://fastapi.tiangolo.com/)
+The `http_app` package contains the implementation of [FastAPI](https://fastapi.tiangolo.com/)
 framework and the logic relevant to HTTP communication (routes, graphql schema, HTTP error handling)