pgorecki/python-ddd

This system is a Python-based auction platform built with Domain-Driven Design principles, exposing functionality via a FastAPI REST interface and a CLI. It enables sellers to manage product listings through a catalog module and allows users to participate in auctions by placing and retracting bids within the bidding module. The application handles user authentication and identity management through a dedicated IAM module, persisting all data in PostgreSQL using SQLAlchemy and Alembic for schema migrations.

25 changes.

The project established a Python Domain-Driven Design foundation, configuring infrastructure for database migrations, testing, and dependency injection. Core bounded contexts for catalog listings and bidding were implemented with full domain models, application layers, and PostgreSQL persistence. An HTTP API and CLI entry point were launched to expose these features, alongside initial scaffolding for identity and access management.

13 changes.

This period focused on implementing the core bidding module, including PostgreSQL-backed persistence with JSONB storage and application-level query handlers for retrieving listing details. Significant effort was dedicated to expanding test coverage across the bidding, catalog, and seedwork layers, verifying domain logic, infrastructure repositories, and application commands. The work also involved initializing the catalog module's application layer and establishing event handling for listing publications.

The catalog module now exposes application-layer query handlers to retrieve listing data. Users can fetch all listings, get details for a specific listing by ID, or retrieve listings associated with a seller. These queries map database models to data access objects, providing structured data for the API layer.

src/modules/catalog/application/query · high confidence

The application now includes the necessary configuration files to manage database schema changes using Alembic. This adds a README, an environment script (env.py) configured to target the 'ListingMetadata' model from the catalog module, and a standard migration template (script.py.mako). Users can now generate and apply database migrations for the PostgreSQL database.

migrations · high confidence

A new command-line interface has been added to the application, allowing users to execute queries and commands directly via the terminal. The entry point (\\_\main\\_.py\) demonstrates how to configure the application container, create database schemas, retrieve all listings, and create new listing drafts using the transaction context. This provides a concrete example of how to interact with the catalog module's domain logic and infrastructure from the command line.

src/cli · high confidence

The IAM module now includes a concrete database implementation for storing and retrieving user data. A new SQLAlchemy model defines the user schema (including email, password, access token, and superuser status), and a repository class provides methods to look up users by email or access token, enabling persistent user management within the system.

src/modules/iam/infrastructure · high confidence

The bidding module now includes a concrete infrastructure implementation for persisting auction listings. This change introduces a SQLAlchemy-based repository that stores listing data in a PostgreSQL database using a JSONB column, handling the serialization and deserialization of complex domain objects like bids, money, and timestamps. This provides the underlying data access layer required for the bidding functionality.

src/modules/bidding/infrastructure · high confidence

The bidding module now exposes application-level query handlers to retrieve specific listing information. Users can fetch detailed data for a single listing via the \GetBiddingDetails\ query, which maps the internal listing model to a Data Access Object (DAO) containing the ID, end time, and bids. Additionally, a \GetPastdueListings\ query has been introduced to identify listings that have passed their end time, though this specific functionality is currently a placeholder returning an empty list.

src/modules/bidding/application/query · high confidence

The application layer for the Identity and Access Management (IAM) module has been introduced, providing the core logic for user lifecycle and authentication. This includes an IamService that handles user creation with password hashing via bcrypt, and authentication flows supporting both email/password login and access token lookup. The implementation defines specific exceptions for invalid credentials and access tokens, along with a repository interface for persisting and retrieving user data by email or access token.

src/modules/iam/application · high confidence

The application now exposes an HTTP(S) REST API built on FastAPI, serving as the primary entry point for external clients. This API provides endpoints for managing the product catalog (creating, reading, deleting, and publishing listings) and handling auctions (placing and retracting bids). It also includes an IAM module for user authentication via OAuth2 password flow and a diagnostics endpoint for debugging. The service runs on port 8000 by default and includes integration tests to verify the new functionality.

src/api · high confidence

This change introduces the core domain layer for the catalog module, defining the Listing and Seller aggregates along with their associated value objects, business rules, and domain events. Users can now create and update listing drafts, which triggers a ListingDraftUpdatedEvent, and publish listings, which enforces business rules (such as requiring a price greater than zero and a draft status) before triggering a ListingPublishedEvent. The domain also defines the structural interfaces for listing persistence via a generic repository and establishes the status enum (DRAFT, PUBLISHED) and rule checks for ownership and deletion constraints.

src/modules/catalog/domain · high confidence

Added Alembic configuration and the first migration script to establish the 'catalog\_listing' table, which stores a UUID primary key and a JSONB data column, enabling the application to manage database schema changes for catalog data.

src/alembic · high confidence

This change introduces the core application layer for the new bidding module, enabling users to place and retract bids on listings. It defines the \PlaceBidCommand\ and \RetractBidCommand\ handlers, which interact with the domain repository to execute these actions. Additionally, it sets up event-driven logic to automatically create a new auction listing when a \ListingPublishedEvent\ occurs and to log notifications when a bid is placed (\BidWasPlaced\).

src/modules/bidding/application/command · high confidence

The Bidding module has been added to the application, establishing the foundational structure for the bidding bounded context. This includes the initial module initialization and documentation outlining the core concepts (Listings, Bids, Bidders) and the basic user story for placing a bid, setting the stage for competitive price offering functionality.

src/modules/bidding · high confidence

The repository has been initialized with the foundational structure for a Python Domain-Driven Design auction application. This includes setting up the development environment with Python 3.11, configuring code formatting and linting via pre-commit hooks (Black, isort, autoflake), and defining test execution strategies with pytest markers for unit and integration tests. The project also introduces database migration support via Alembic, containerized development dependencies using Docker Compose with PostgreSQL, and comprehensive documentation outlining the domain logic, context maps, and setup instructions.

(repo-wide) · high confidence

This change establishes the foundational structure for the application, introducing configuration for Alembic database migrations and MyPy type checking. It sets up the core module organization and provides a comprehensive testing suite via pytest fixtures, which configure an in-memory database session and an authenticated API client for integration tests.

src · high confidence

The catalog module has been introduced to support the seller portal, enabling sellers to create, update, and delete listing drafts, as well as publish them immediately. This initial implementation establishes the core business rules and user stories for managing product listings, with additional features like scheduled publishing and detailed listing views marked as pending.

src/modules/catalog · high confidence

The bidding module's domain layer now defines the core data structures and logic for managing auctions. This includes the \Listing\ aggregate root, which handles placing and retracting bids, calculating current and next minimum prices, and determining time remaining. Business rules enforce that bids must meet minimum price thresholds, retraction is restricted within 12 hours of listing end and 1 hour of placement, and cancellation is allowed only if sufficient time remains or no bids exist. The domain also introduces specific events (\BidWasPlaced\, \HighestBidderWasOutbid\, \BidWasRetracted\, \ListingWasCancelled\) to track state changes and value objects for \Bid\, \Bidder\, and \Seller\.

src/modules/bidding/domain · high confidence

The IAM module now includes domain entities to represent users within the system. A new \User\ entity has been added to store core identity information such as email, password hash, access token, and superuser status, while an \AnonymousUser\ class is provided to handle unauthenticated access scenarios.

src/modules/iam/domain · high confidence

The catalog module now exposes application-level commands to manage listing drafts, including creating, updating, deleting, and publishing them. These commands enforce business rules such as ownership checks and status constraints (e.g., preventing deletion of published listings) and integrate with the domain repository and event publishing mechanisms to ensure consistent state transitions.

src/modules/catalog/application/command · high confidence

The infrastructure layer now provides concrete repository implementations for data persistence. An in-memory repository is available for testing or lightweight scenarios, while a new SQLAlchemy-based generic repository handles database operations. This repository introduces an identity map pattern to track entities within a session, ensuring that updates are collected and persisted together via \persist\_all\, and automatically collects domain events from tracked entities before commit.

src/seedwork/infrastructure · high confidence

A new Identity and Access Management (IAM) module has been added to the application, providing the foundational structure for managing electronic or digital identities. This change introduces the initial module scaffolding, including documentation and initialization files, to support future implementation of user access control and authentication features.

src/modules/iam · high confidence

The listing module's domain layer has been stripped of its core definitions. Specifically, the AuctionItem entity, the DraftCreatedEvent, and the AuctionItemPriceMustBeGreaterThanZero business rule (which enforced that prices must be greater than zero) have been deleted, along with their associated unit tests. This removes the validation logic and domain structures previously maintained in this module.

src/modules/listing · high confidence

The application now uses the \dependency\_injector\ library for managing dependencies, replacing the previous manual wiring. A new \src/config\ module provides \ApiConfig\ for environment-based settings (such as database URLs and debug flags) and defines \ApplicationContainer\ and \TransactionContainer\ to handle application-level and transaction-scoped dependency resolution. This change introduces a structured approach to initializing the database engine, repositories, and services, ensuring that each transaction gets its own isolated container with specific dependencies like the database session and correlation ID.

src/config · high confidence

The application infrastructure in src/seedwork/application has been restructured to replace the previous Pydantic-based Command base class with a new Command class inheriting from Lato's Command. This change introduces a robust command execution pipeline via the TransactionContext, which now automatically collects domain events from repositories after a command handler runs and processes those events (including dispatching further commands or integration events) before returning. The layer also adds explicit result types (CommandResult, QueryResult, EventResult) and an inbox/outbox mechanism for asynchronous event delivery.

src/seedwork/application · high confidence

The application layer for the catalog module is now initialized via a new \\_\init\\_.py\ file that registers the module using \lato.ApplicationModule\ and dynamically imports the command and query modules, replacing the previous seedwork-based application structure.

src/modules/catalog/application · high confidence

The catalog module now includes a handler for the ListingPublishedEvent. When a listing is published, this handler logs an informational message confirming the event, currently serving as a placeholder implementation.

src/modules/catalog/application/event · high confidence

The catalog module now stores listing data in a PostgreSQL database using SQLAlchemy. A new repository implementation maps domain entities to a database model that persists listing details (title, description, price, seller) in a JSONB column, replacing any previous in-memory or alternative storage approach for this specific component.

src/modules/catalog/infrastructure · high confidence

The domain layer has been refactored to replace simple placeholder classes with fully implemented dataclasses and generic interfaces. Entity and AggregateRoot now use Python dataclasses, with AggregateRoot gaining event registration and collection capabilities. A new GenericRepository interface is introduced to standardize entity persistence operations (add, remove, get\_by\_id, persist). Additionally, concrete value objects like Money and Email are now implemented with validation logic, replacing the previous stubs.

src/seedwork/domain · high confidence

Added application-layer tests for catalog listing commands; Added integration test for listing creation on draft publish; Added integration tests for IAM service duplicate validation; Added tests for the bidding listing repository and data mapper; Added tests for the catalog listing repository; Added tests for the deprecated seedwork Application module; Added unit and integration tests for seedwork infrastructure components; Added unit tests for bidding domain logic; Added unit tests for catalog domain entities and business rules; Added unit tests for domain entities and value objects.

The project has upgraded its Python runtime requirement from 3.9 to 3.10 and performed a significant dependency refresh. Key library updates include FastAPI to 0.110.0, SQLAlchemy to 1.4.22, and Pydantic to 1.8.2 (with the addition of pydantic-settings). New dependencies such as Alembic for database migrations, bcrypt for authentication, and the 'lato' framework have been introduced, while development tooling now includes mypy and black.

(dependencies) · high confidence

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

• CAI 57 → 53 (-4.0)
• Rubric changed (rubric-2026.08.17 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 100 → 98 (-1.7)
• Architecture 100 → 83 (-17.3)
• Maturity 57 → 59 (+2.1)
• Readiness 46 → 36 (-9.5)
• Security 85 → 82 (-3.0)
• Domain Modelling 61 → 68 (+6.2)

• Context and decision are both about choosing Python over .NET Core/C#; the title "3. Use .NET Core and C# language" is a generic placeholder with no direction (which framework to pick) or problem it addresses (docs/architecture_decision_log/003_use_python.md)
• Context is a duplicate title and the decision restates the architecture (Modular Monolith) without any rationale or trade-offs; consequences are boilerplate list with no real meaning (docs/architecture_decision_log/002_use_modular_monolith.md)
• Context is thin and the body only states that ADRs are created for advanced monolith projects but does not explain why ADL plus ADR structure (Status/Context/Decision/Consequences) is needed (docs/architecture_decision_log/001_initial.md)
• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — no supported dependency manifest was read
• High: security finding (details withheld)
• High: security finding (details withheld)
• Informative title ('4. Separate commands and queries') is uninformative rather than conveying the decision's rationale (docs/architecture_decision_log/005_separate_commands_and_queries.md)
• No exposed public API
• Test reliability not included
• The Bidding process example assumes a single seller (Alice) and only one bidder at a time, but the text implies multi-round bidding where Charlie outbids Bob in step 4 before being outbid by Bob again. The narrative is slightly non-sequential. (src/modules/bidding/README.md)
• The decision is not yet stated ('Decision TBA') despite the strong context; trade-offs of each solution are only hinted and not fully shown before the clip (docs/architecture_decision_log/006_error_handling_during_operation_execution.md)
• dormant codebase — no living knowledge left to concentrate

• Context is thin and the body only states that ADRs are created for advanced monolith projects but does not explain why ADL plus ADR structure (Status/Context/Decision/Consequences sections) is needed (docs/architecture_decision_log/001_initial.md)
• Critical CVE: [GHSA redacted] (poetry.lock)
• Critical CVE: [GHSA redacted] (poetry.lock)
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (41 lines × 2) (migrations/env.py)
• FixmeComment (src/modules/catalog/application/query/get_listings_of_seller.py)
• High CVE: [GHSA redacted] (poetry.lock)
• High CVE: [GHSA redacted] (poetry.lock)
• High CVE: [GHSA redacted] (poetry.lock)
• High CVE: [GHSA redacted] (poetry.lock)
• High CVE: [GHSA redacted] (poetry.lock)
• High CVE: [GHSA redacted] (poetry.lock)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Low IaC: WD-COMPOSE-0002 (docker-compose.dev.yml)
• Low IaC: WD-COMPOSE-0002 (docker-compose.dev.yml)
• Medium CVE: [GHSA redacted] (poetry.lock)
• Medium CVE: [GHSA redacted] (poetry.lock)
• …and 19 more

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

pgorecki/python-ddd 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.