ddd-by-examples/library

This system is a library lending service that manages the lifecycle of books and patrons, supporting core operations such as cataloging, placing holds, checking out items, and tracking overdue returns. It is built as a modular monolith using a hexagonal architecture, with distinct domains for the catalogue and lending logic, and employs domain events to synchronize state between aggregates and read models. The application exposes a RESTful API for patron profiles and lending actions, backed by JDBC persistence and integrated with Prometheus and Grafana for operational monitoring.

This change introduces the foundational configuration files for the monitoring stack. It adds a Prometheus configuration that scrapes metrics from the 'library' service at /actuator/prometheus every 10 seconds, and a Grafana provisioning setup that automatically configures a Prometheus datasource. Additionally, a default Grafana admin password is set and user sign-up is disabled, while a pre-built JVM Micrometer dashboard JSON is included to visualize application metrics like uptime and restarts.

monitoring · high confidence

The system now provides a new infrastructure layer to retrieve a patron's current lending status. A Spring configuration registers a \PatronProfiles\ bean that uses a JDBC-based read model to query the database for active holds and checkouts, allowing users to view their current patron profile data.

src/main/java/io/pillopl/library/lending/patronprofile/infrastructure · high confidence

The application now includes the initial database schema definitions for the catalogue, lending, patron, and daily sheet (read model) domains, establishing the necessary tables and sequences for book, patron, hold, and checkout data. Additionally, Spring Boot Actuator endpoints are configured to expose health, metrics, and Prometheus data, enabling integration with external monitoring tools like Grafana.

src/main/resources · high confidence

This change introduces the core catalogue module, enabling users to define book metadata (title, author, ISBN) and create specific book instances with restricted or circulating types. It includes the domain models (Book, BookInstance), the Catalogue service for managing these entities, and the necessary Spring configuration to persist data in an embedded H2 database and publish domain events upon instance creation.

src/main/java/io/pillopl/library/catalogue · high confidence

This change introduces the core domain model for the patron profile feature within the lending module. It adds value objects to represent individual checkouts and holds, along with view models (CheckoutsView, HoldsView) that aggregate these items. The central PatronProfile entity now exposes methods to look up specific active checkouts and holds by book ID, and a PatronProfiles interface is defined to fetch a patron's profile data by their ID.

src/main/java/io/pillopl/library/lending/patronprofile/model · high confidence

This change introduces the infrastructure layer for managing book lending states. It adds a Spring configuration that wires up a JDBC-based repository and event handlers, enabling the system to persist book states (Available, OnHold, CheckedOut) with optimistic locking and to synchronize book state changes in response to domain events such as patron holds, checkouts, returns, and catalog additions.

src/main/java/io/pillopl/library/lending/book/infrastructure · high confidence

The repository is initialized with essential operational and legal files. A Dockerfile and Dockerfile.build are added to containerize the Java application (using OpenJDK 11 and Maven 3.6), exposing port 8080. A docker-compose.yml is introduced to orchestrate the application alongside Prometheus and Grafana for monitoring. The project includes an MIT License, a .gitignore file, and a lombok.config to enable generated annotations. A comprehensive README.md documents the domain logic (library lending), architecture (hexagonal, modular monolith), and development assumptions.

(repo-wide) · high confidence

The lending module now includes a new daily sheet capability that identifies books that are overdue and holds that are about to expire. This is implemented via a \DailySheet\ interface and a \SheetsReadModel\ infrastructure component that persists state in \holds\_sheet\ and \checkouts\_sheet\ database tables. The system listens for patron events (such as \BookPlacedOnHold\, \BookCheckedOut\, \BookReturned\, etc.) to keep these sheets up to date, and exposes queries to retrieve lists of overdue checkouts and expiring holds, which can then be converted into domain events for further processing.

src/main/java/io/pillopl/library/lending/dailysheet · high confidence

The lending module now explicitly models the lifecycle of a book through new domain classes: AvailableBook, BookOnHold, and CheckedOutBook, each implementing the Book interface. These classes encapsulate the state transitions triggered by patron events (such as placing a hold, checking out, returning, or canceling a hold) and include logic to prevent duplicate holds via the BookDuplicateHoldFound event. A new BookRepository interface is also introduced to manage persistence of these book states.

src/main/java/io/pillopl/library/lending/book/model · high confidence

The application now includes a foundational domain event system, introducing the \DomainEvent\ interface and \DomainEvents\ publisher contract within the \commons.events\ package. This infrastructure supports asynchronous communication by providing multiple publisher strategies: a simple synchronous forwarder (\JustForwardDomainEventPublisher\), a persistent store-and-forward mechanism (\StoreAndForwardDomainEventPublisher\) that batches and periodically publishes events every 3 seconds, and a metrics-enabled wrapper (\MeteredDomainEventPublisher\) that tracks event counts via Micrometer. These components are wired together in \DomainEventsConfig\ to provide a robust, observable event publishing capability for the library's domain logic.

src/main/java/io/pillopl/library/commons/events · high confidence

The lending module now includes dedicated Spring configuration classes (LendingConfig and LendingDatabaseConfig) that wire together infrastructure components such as book, patron, and daily sheet configurations, along with domain event publishing. It sets up an embedded H2 database with specific SQL scripts for patrons, lending books, and sheets, and provides JDBC templates and transaction management. Additionally, a local profile initializer is added to seed sample book and patron data for development purposes.

src/main/java/io/pillopl/library/lending · high confidence

The application now supports a new checkout flow where patrons can check out books that are on hold, facilitated by the new CheckOutBookCommand and CheckingOutBookOnHold service which validates holds and publishes success or failure events. Additionally, a new RegisteringOverdueCheckout service has been introduced to identify overdue checkouts via the DailySheet and publish OverdueCheckoutRegistered events, enabling the system to track and process overdue items.

src/main/java/io/pillopl/library/lending/patron/application/checkout · high confidence

The library now exposes a RESTful web API for managing patron profiles, including endpoints to retrieve a patron's current holds and checkouts, view individual hold/checkout details, place new holds, and cancel existing holds. The API is built with Spring HATEOAS (HAL Forms) to provide hypermedia links for navigation and actions, ensuring a consistent and discoverable interface for clients interacting with the lending system.

src/main/java/io/pillopl/library/lending/patronprofile/web · high confidence

Patrons can now place holds on available books (supporting both open-ended and fixed-duration holds) and cancel existing holds. This change introduces the application-layer services (PlacingOnHold, CancelingHold) and command objects that coordinate with the patron domain model to publish hold-related events, including automatic cancellation handling for duplicate holds.

src/main/java/io/pillopl/library/lending/patron/application/hold · high confidence

The \Resource.java\ file, which contained the domain classes \Resource\, \Patron\, \LibraryBranchId\, and \OverdueResources\ along with their hold logic, has been deleted from the \io.pillopl.books\ package. This change removes the previous implementation where the Resource entity drove the holding process, clearing the way for the new domain structure introduced in subsequent commits.

src/main/java/io/pillopl/books · high confidence

The Maven wrapper configuration has been updated to use Apache Maven version 3.5.3 instead of 3.5.4. This change affects the version of the build tool downloaded and used by the project when running Maven commands via the wrapper.

.mvn · high confidence

The system now supports optimistic locking for aggregate persistence to prevent data loss from concurrent updates. This is enabled by a new \Version\ value object to track state revisions and an \AggregateRootIsStale\ exception to signal conflicts. Additionally, new \Result\ and \BatchResult\ enums provide standardized return types for command execution outcomes.

src/main/java/io/pillopl/library/commons/aggregates · high confidence

The patron module now uses Spring Data JDBC to store patron state, including their holds and overdue checkouts, in the database. This change adds new infrastructure classes (PatronDatabaseEntity, HoldDatabaseEntity, OverdueCheckoutDatabaseEntity) and a PatronsDatabaseRepository that maps domain events to database rows, replacing previous in-memory or alternative storage mechanisms. A new PatronConfiguration class wires up the repository and application services, enabling durable storage of patron data.

src/main/java/io/pillopl/library/lending/patron/infrastructure · high confidence

The patron model now enforces specific business rules for library interactions: patrons are limited to a maximum of five holds, and checkouts are capped at 60 days. Additionally, regular patrons are restricted from holding restricted books or placing open-ended holds, and holds are rejected if the patron has two or more overdue items at the specific branch.

src/main/java/io/pillopl/library/lending/patron/model · high confidence

Added architecture and test fixture tests; Added architecture tests to enforce hexagonal architecture and framework isolation; Added integration tests for the catalogue database layer; Added tests for book lending application logic; Added tests for book model state transitions and infrastructure mapping; Added tests for catalogue book management and value object validation; Added tests for patron checkout and overdue registration workflows; Added tests for patron event handling and entity mapping; Added unit tests for Patron model lending behaviors; Added unit tests for daily sheet event transformation logic; Added unit tests for patron hold application services; Integration tests for metered domain event publishing; Integration tests for the library lending domain; Removed obsolete domain tests for patron holding limits.

The project has been upgraded from Spring Boot 2.1.1 to version 2.2.0.M6 and the Java runtime requirement has been raised from version 8 to 11. This change introduces several new dependencies including Spring Boot Actuator, Spring Data JDBC, Spring HATEOAS, and Micrometer Prometheus registry, while removing the Groovy All dependency. To support the new milestone and snapshot dependencies, the Maven configuration now includes specific repositories for Spring milestones, snapshots, and release plugins.

(dependencies) · high confidence

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

• CAI 62 → 63 (+1.0)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 100 → 100 (-0.3)
• Architecture 100 → 80 (-20.2)
• Maturity 65 → 74 (+9.3)
• Readiness 46 → 46 (+0.0)
• Security 97 → 84 (-13.0)
• Domain Modelling 74 → 79 (+4.3)

• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Medium IaC: CKV_DOCKER_3 (Dockerfile)
• Medium IaC: CKV_DOCKER_3 (Dockerfile.build)
• No exposed public API
• Scanner failed to run — not a clean result
• Test reliability not included
• The 'Holding' topic has images, but no accompanying text explains what each image represents in terms of the business scenario or rule it models. (docs/example-mapping.md)
• dormant codebase — no living knowledge left to concentrate

• Coverage not measured — no coverage collector is wired up
• Dependency hygiene PARTLY measured — Maven/Gradle declarations read, no dependency graph resolved
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (5 lines × 2) (src/main/java/io/pillopl/library/lending/patron/application/checkout/CheckingOutBookOnHold.java)
• Duplicated block (5 lines × 2) (src/main/java/io/pillopl/library/lending/patron/infrastructure/HoldDatabaseEntity.java)
• High IaC: WD-DOCKER-0013 (Dockerfile)
• High IaC: WD-DOCKER-0013 (Dockerfile.build)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Medium IaC: WD-COMPOSE-0002 (docker-compose.yml)
• Medium IaC: WD-COMPOSE-0002 (docker-compose.yml)
• Medium IaC: WD-DOCKER-0003 (Dockerfile)
• Medium IaC: WD-DOCKER-0003 (Dockerfile.build)
• Medium IaC: WD-DOCKER-0003 (Dockerfile.build)
• No ADRs found
• No dependency advisory monitoring
• Scanner failed to run — not a clean result
• Scanner failed to run — not a clean result

• 1 commits — 0 feature/other, 1 fixes

• (repo) — 1 commit

• fix: Merge pull request #80 from dkarczmarski/fix-image-path-example-mapping-md

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

ddd-by-examples/library 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.