n1nj4t4nuk1/python-ddd-example

This system is a multi-service Python application built on a CQRS and event-driven architecture, comprising a Backoffice service for user management and a PhotoStore service for image uploads. It provides endpoints to create and filter users, as well as upload and register photos with metadata. The architecture relies on in-memory command and event buses for internal communication, with persistence handled by MongoDB and Minio object storage.

A new domain event, UserCreatedDomainEvent, has been introduced to capture and serialize user creation details. This change adds the necessary structure to track when a new user is created within the backoffice context, including entity data and metadata for event processing.

src/contexts/backoffice/users/domain/domainevents · high confidence

Introduced a new abstract Logger interface defining the contract for logging operations. The interface extends a base Interface and declares abstract methods for debug, info, error, and critical log levels, establishing the foundation for future concrete logging implementations.

src/contexts/shared/domain/logger · high confidence

Users can now be created via the backoffice interface. This change introduces the command, handler, and creator logic for adding a new user, including the persistence of the user entity and publishing of domain events.

src/contexts/backoffice/users/application/createone · high confidence

The backoffice users domain now includes specific error classes for handling user-related failures. A new UserAlreadyExistsError is introduced to handle cases where a user registration or creation attempt duplicates an existing account. Additionally, UserInvalidValueError and UserNotFoundError are added to manage invalid input values and missing user records respectively. These classes implement a standard interface for error serialization, ensuring consistent error reporting for user domain events.

src/contexts/backoffice/users/domain/errors · high confidence

Users can now upload and create new photos through a new use case. This introduces a command and handler to process photo uploads, a creator service to persist the photo and publish domain events, and a command object carrying the photo ID, name, user ID, and file data.

src/contexts/photostore/photo/application · medium confidence

A new parser has been added to convert dictionary-based query parameters into structured criteria objects. This enables the system to interpret $ord (sort), $dir (order direction), $limit, $offset, and $page parameters, as well as standard key-value pairs for filtering. The parser returns a tuple of filters, an optional sort order, and an optional limit/offset for pagination.

src/contexts/shared/Infrastructure/parsers · medium confidence

Introduced a new JSON response error handler that maps domain errors (UserAlreadyExistsError, UserInvalidValueError, UserNotFoundError) to appropriate HTTP status codes. Added a PyMongo-based user repository implementation that handles unique key constraints and persists user entities. Included a configuration factory to retrieve MongoDB connection details from environment variables.

src/contexts/backoffice/users/infrastructure · high confidence

A new logging implementation, NativeConsoleLogger, has been added to the shared infrastructure layer. This class implements the Logger interface and uses Python's standard logging module to output messages to the console with a formatted header (name, level, message). It provides methods for debug, info, error, and critical log levels, enabling developers to capture and display application logs in a structured format.

src/contexts/shared/Infrastructure/logger · high confidence

Introduced a new set of domain classes in the shared criteria module to support query construction. This includes the main Criteria class and supporting value objects for filtering (Filter, FilterField, FilterOperator, FilterValue), ordering (OrderBy, OrderAttribute, OrderDirection), and pagination (Limit, LimitOffset, UpperLimit). These classes provide the structural foundation for applying filters, sorting, and limiting results in the application.

src/contexts/shared/domain/criteria · high confidence

New utility functions have been added to the application's core utilities. A new BytifyUploadFile utility provides a method to encode uploaded files into base64 format, facilitating storage in systems like Minio. Additionally, a Uuid class has been introduced to validate whether a given string is a valid UUID of a specified version, ensuring data integrity for identifier fields.

src/utils · high confidence

A new in-memory implementation of the command bus has been introduced, allowing commands to be dispatched to their corresponding handlers via a simple dictionary mapping. This provides a lightweight, non-persistent way to route commands to handlers during development or testing, raising the question of whether this is a temporary or permanent addition to the infrastructure layer.

src/contexts/shared/Infrastructure/commandbus · high confidence

The backoffice application is now structured with a clear separation between the FastAPI application logic and the server runner. A new \BackofficeApp\ class encapsulates the FastAPI instance and route registration, while \BackofficeServer\ handles the Uvicorn server startup using environment variables for host and port configuration. The \boot.py\ entry point initializes and runs the server, providing a clean entry point for the backoffice service.

src/apps/backoffice · high confidence

A new environment variable management system has been introduced to centralize access to configuration values. The \EnvVar\ enum defines typed constants for various infrastructure services, including Backoffice, Photo Store, User, Photo, and Photo Registry settings. This includes specific MinIO connection details (host, port, access key, secret key, region, and secure flag) alongside standard host and port configurations for other services. The \EnvManager\ class provides a static method to retrieve and parse these environment variables, ensuring consistent access to configuration data across the application.

src/contexts/shared/Infrastructure/environment · high confidence

The system now supports storing and retrieving photos using Minio as the underlying object storage. A new \MinioPhotoRepository\ handles photo persistence, mapping domain entities to Minio bucket operations, while a \MinioPhotoConfigFactory\ loads Minio connection details (host, port, credentials) from environment variables. Additionally, a \JsonResponseErrorHandler\ is introduced to map domain errors to appropriate HTTP JSON responses, improving error reporting for photo-related operations.

src/contexts/photostore/photo/infrastructure · high confidence

A new BackofficeUsersResponse class has been added to the application layer to handle the serialization of user data. This response object aggregates a list of User entities and optional metadata, providing a to\_primitives method that returns a dictionary containing the users under a 'data' key and, if present, pagination or other metadata under a 'metadata' key. This change establishes a consistent structure for the backoffice users endpoint, ensuring that user listings include both the user data and any associated query metadata.

src/contexts/backoffice/users/application · high confidence

Added new classes to support storing files in a Minio object storage system. The \MinioClientFactory\ manages Minio client instances, \MinioConfiguration\ handles connection settings (host, port, credentials), and the abstract \MinioRepository\ provides base functionality for saving and retrieving objects, enabling the system to persist data to Minio buckets.

src/contexts/shared/Infrastructure/persistence/minio · high confidence

Added a new MongoDB persistence infrastructure, including a PyMongo client factory, configuration, and a generic repository base class. The repository supports querying by criteria, sorting, and pagination (limit/skip), with a utility to translate domain criteria into MongoDB query operators.

src/contexts/shared/Infrastructure/persistence/mongo · high confidence

The PhotoStore application is introduced, providing a new API for uploading photos and checking system status. Users can now POST to /api/photos to upload images, which are then stored in Minio and registered in a MongoDB-based registry. Additionally, a /status endpoint is exposed to verify the service is running. The implementation includes a FastAPI-based server, dependency injection via a container, and controllers handling the photo creation command.

src/apps/photostore · high confidence

Added the User domain entity along with its associated value objects, UserId and UserName. The User entity now encapsulates user identification and name, providing methods to create instances from primitives and serialize back to a dictionary representation.

src/contexts/backoffice/users/domain/entities · high confidence

A new abstract base class BackofficeController is added to define a standard interface for handling HTTP requests in the backoffice application. Concrete implementations are provided for user management: a GET endpoint (UsersGetController) that retrieves users by applying criteria-based filtering, ordering, and pagination, and a POST endpoint (UserPostController) that creates a new user by dispatching a command through the application's command bus. Additionally, a basic status check endpoint (StatusGetController) is introduced to verify the service is running.

src/apps/backoffice/controllers · high confidence

Added new base classes for domain modeling: a ValueObject class that encapsulates a typed value, and an AggregateRoot abstract class that manages domain events. The AggregateRoot provides methods to record and retrieve domain events, supporting event sourcing patterns within the shared domain layer.

src/contexts/shared/domain/valueobj · high confidence

Added new domain error classes—CommandNotRegisteredError, QueryNotRegisteredError, and ValueObjectValidationError—each inheriting from a new DomainError base class. These classes provide a standardized way to handle and serialize domain-specific errors, ensuring consistent error reporting and identification via unique error IDs.

src/contexts/shared/domain/errors · high confidence

Users can now utilize an in-memory event bus for handling domain events within the shared infrastructure layer. This new \InMemoryEventBus\ class manages event subscriptions and allows for publishing domain events to registered subscribers. The implementation supports dynamic addition of subscribers via \add\_subscriber\ and \add\_subscribers\ methods, ensuring that events are routed to all relevant handlers.

src/contexts/shared/Infrastructure/eventbus · high confidence

Added a new in-memory implementation of the QueryBus interface, allowing queries to be dispatched to their corresponding handlers via a simple dictionary mapping. This provides a lightweight, dependency-injection-friendly way to handle queries without external infrastructure.

src/contexts/shared/Infrastructure/querybus · high confidence

The application now supports running distinct services (backoffice and photostore) via a central main.py entry point, which routes to specific booters based on command-line arguments. Additionally, a Makefile is introduced to standardize build, dependency installation, testing, and service execution, while a Dockerfile is added to containerize the Python 3.9 environment.

(repo-wide) · high confidence

A new photo registry context has been added to the system, enabling the storage and retrieval of photo metadata including name, user ID, and tags. This feature introduces a domain model for PhotoRegistry, a repository interface and its MongoDB implementation, and an event handler that automatically creates a registry entry when a new photo is created. Users will now have their photos automatically registered with associated metadata and tags upon creation.

src/contexts/photostore/photoregistry · high confidence

A new abstract base class, UserRepository, is added to define the contract for user data access. It specifies an asynchronous find\_by\_criteria method for retrieving users based on search conditions, alongside a create\_one method for adding new users. This establishes the domain interface required for the backoffice's user management features.

src/contexts/backoffice/users/domain · high confidence

Adds the foundational classes and interfaces for a Command/Query (CQRS) pattern and an event bus. This includes abstract base classes for commands, queries, and their respective handlers and buses, as well as domain event and subscriber interfaces. These changes provide the internal structure for handling commands, executing queries, and publishing domain events, enabling a more decoupled and scalable application architecture.

src/contexts/shared/domain · high confidence

The backoffice users context now supports finding users by a set of filters, an optional sort order, and a limit. This is implemented via a new FindUsersByCriteriaQuery, its handler, and a finder that delegates to the user repository's find\_by\_criteria method, enabling the backoffice to retrieve users with advanced filtering and pagination.

src/contexts/backoffice/users/application/findall · medium confidence

The backoffice application has been refactored to use dependency injection for route registration. The new \\_\init\\_.py\ file registers status and user routes, which now inject their respective controllers (\StatusGetController\, \UsersGetController\, \UserPostController\) via the \BackofficeContainer\. This change replaces the previous mechanism for wiring routes and controllers, ensuring that the \status\_get\_controller\, \users\_get\_controller\, and \user\_post\_controller\ are provided by the DI container.

src/apps/backoffice/routes · medium confidence

The Photo domain entity has been introduced, including value objects for the photo's name, file content, and a new tags collection. The entity now supports creation from primitives and includes domain events for photo creation. Additionally, specific domain errors for invalid values and duplicate photos have been added to handle validation failures.

src/contexts/photostore/photo/domain/entities · high confidence

Added the PhotoCreatedDomainEvent class to the photo context, enabling the system to publish a domain event when a photo is created. This event captures the photo's ID, user ID, name, and newly added tags, and provides methods to construct the event from primitive data structures and serialize it back to a dictionary format for downstream consumers.

src/contexts/photostore/photo/domain/domainevents · high confidence

A new Photo domain entity and its corresponding abstract repository interface are added to the photo store context. The PhotoRepository defines the contract for persisting photo data, specifically introducing a create\_one method, which establishes the foundation for photo storage operations within the application's domain layer.

src/contexts/photostore/photo/domain · high confidence

The Backoffice application now uses a centralized container to manage dependencies, wiring together controllers, command/query handlers, repositories, and infrastructure components like the event bus and database clients. This change replaces ad-hoc instantiation with a structured, testable architecture that makes it easier to swap out implementations or mock dependencies during testing.

src/apps/backoffice/dependencies · high confidence

Added test infrastructure for the backoffice users context; Added test utilities for async and data generation.

The project's Python dependencies have been updated to specific versions, including upgrading starlette to 0.40.0, urllib3 to 2.5.0, and pydantic to 1.10.13, while also adding deepfinder 1.2.0 and deepcomparer 0.1.0.

(dependencies) · medium confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 65 → 68 (+3.8)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 97 → 97 (-0.0)
• Architecture 100 → 84 (-16.5)
• Maturity 48 → 57 (+9.5)
• Readiness 70 → 66 (-3.5)
• Security 77 → 91 (+14.2)
• Domain Modelling 100 → 100 (+0.0)

• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Duplicated block (15 lines × 2) (src/contexts/backoffice/users/infrastructure/JsonResponseErrorHandler.py)
• Duplicated block (7 lines × 2) (src/contexts/photostore/photo/domain/domainevents/PhotoCreatedDomainEvent.py)
• High CVE: [GHSA redacted] (requirements.txt)
• High CVE: [GHSA redacted] (requirements.txt)
• High CVE: [GHSA redacted] (requirements.txt)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Medium CVE: [GHSA redacted] (requirements.txt)
• Medium CVE: PYSEC-2026-2132 (requirements.txt)
• Medium IaC: CKV_DOCKER_3 (Dockerfile)
• No exposed public API
• Test reliability not included
• dormant codebase — no living knowledge left to concentrate

• Critical CVE: [GHSA redacted] (requirements.txt)
• Documentation: no installation or build instructions (README.md)
• Documentation: no project overview (README.md)
• Duplicated block (17 lines × 2) (src/contexts/backoffice/users/infrastructure/JsonResponseErrorHandler.py)
• Duplicated block (5 lines × 2) (src/contexts/backoffice/users/infrastructure/persistence/PyMongoUserRepository.py)
• Duplicated block (5 lines × 2) (src/contexts/photostore/photo/domain/domainevents/PhotoCreatedDomainEvent.py)
• Duplicated block (7 lines × 2) (src/apps/backoffice/BackofficeApp.py)
• Duplicated block (9 lines × 2) (src/contexts/photostore/photo/domain/domainevents/PhotoCreatedDomainEvent.py)
• Duplicated block (9 lines × 2) (src/contexts/shared/Infrastructure/persistence/minio/MinioClientFactory.py)
• High CVE: [GHSA redacted] (requirements.txt)
• High CVE: [GHSA redacted] (requirements.txt)
• High CVE: [GHSA redacted] (requirements.txt)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 32 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

n1nj4t4nuk1/python-ddd-example was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.