Refactor books domain and update documentation.

Do not run celery without explicit configuration

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

Author: febus982

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/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 `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
@@ -198,16 +206,16 @@ and we don't end up in circular dependencies.
 
 ```python
 # file `bootstrap/factories.py`
-from domains.books._data_access_interfaces import BookRepositoryInterface
+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
+# file `domains/books/_service.py`
+from domains.books._gateway_interfaces import BookRepositoryInterface
 from bootstrap.factories import book_repository_factory
 
 

docs/packages/bootstrap.md

@@ -1,9 +1,9 @@
 # Bootstrap
 
-The `bootstrap` module contains logic that is shared among the external layer
+The `bootstrap` package contains logic that is shared among the external layer
 (i.e. `http_app`, `celery_worker`, etc.).
 
-It contains 3 submodules (and related responsibilities):
+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

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/domains.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/gateways.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/http_app.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)

src/bootstrap/config.py

@@ -1,6 +1,6 @@
 import logging
 from pathlib import Path
-from typing import Dict, List, Literal
+from typing import Dict, List, Literal, Optional
 
 import structlog
 from opentelemetry import trace
@@ -18,11 +18,11 @@ class CeleryConfig(BaseModel):
     timezone: str = "UTC"
 
     # Broker config
-    broker_url: str = "redis://redis:6379/0"
+    broker_url: Optional[str] = None
     broker_connection_retry_on_startup: bool = True
 
     # Results backend config
-    result_backend: str = "redis://redis:6379/1"
+    result_backend: Optional[str] = None
     redis_socket_keepalive: bool = True
 
     # Enable to ignore the results by default and not produce tombstones
@@ -36,14 +36,14 @@ class CeleryConfig(BaseModel):
     task_send_sent_event: bool = True
 
     # Recurring tasks triggered directly by Celery
-    # beat_schedule: dict = {}
-    beat_schedule: dict = {
-        "recurrent_example": {
-            "task": "domains.books.tasks.book_cpu_intensive_task",
-            "schedule": 5.0,
-            "args": ("a-random-book-id",),
-        },
-    }
+    beat_schedule: dict = {}
+    # beat_schedule: dict = {
+    #     "recurrent_example": {
+    #         "task": "domains.books._tasks.book_cpu_intensive_task",
+    #         "schedule": 5.0,
+    #         "args": ("a-random-book-id",),
+    #     },
+    # }
 
 
 class AppConfig(BaseSettings):

src/bootstrap/di_container.py

@@ -1,10 +1,10 @@
 from dependency_injector.containers import DeclarativeContainer, WiringConfiguration
 from dependency_injector.providers import Dependency, Factory, Singleton
-from domains.books._data_access_interfaces import (
+from domains.books._gateway_interfaces import (
     BookEventGatewayInterface,
     BookRepositoryInterface,
 )
-from domains.books.models import BookModel
+from domains.books._models import BookModel
 from gateways.event import NullEventGateway
 from sqlalchemy_bind_manager import SQLAlchemyBindManager
 from sqlalchemy_bind_manager.repository import SQLAlchemyAsyncRepository

src/bootstrap/storage/SQLAlchemy/default_bind_tables.py

@@ -1,4 +1,4 @@
-from domains.books.models import BookModel
+from domains.books._models import BookModel
 from sqlalchemy import Column, Integer, String, Table
 from sqlalchemy.orm import registry