ddd-by-examples/library

What this project is

This is a worked example of a public library system built to demonstrate Domain-Driven Design rather than to serve as a production application. Starting from a written domain description, it walks through Big Picture EventStorming, Example Mapping and Design Level EventStorming, then turns those results into a modular monolith with two bounded contexts: catalogue, which is mostly CRUD, and lending, which carries the real business logic with a hexagonal architecture (README overview).

The lending model covers holds, checkouts, restricted books, researcher versus regular patrons, overdue limits and daily sheets. The codebase illustrates several tactical patterns: aggregates that communicate through events, a choice between immediate and eventual consistency, immutable domain objects, pure functions declared in the domain and implemented in infrastructure, state-as-types (AvailableBook, BookOnHold, CheckedOutBook), Vavr Option/Either/Try containers, pattern matching, and repositories backed by plain SQL, JdbcTemplate and Spring Data JDBC instead of JPA. ArchUnit tests protect the package boundaries, and BDD-style Groovy tests use a small domain DSL (design notes).

It suits Java developers who already know Spring and want a concrete, readable reference for connecting DDD concepts to code, as well as teams discussing bounded contexts, aggregate consistency or functional domain modeling.

Quick start

Requirements: Java 11 and Maven (build instructions).

Run the application from the repository root:

$ mvn spring-boot:run

The embedded Tomcat starts on port 8080 with an empty context path. To produce a jar instead:

$ mvn clean package

Then build and run the container:

$ docker build -t spring/library .
$ docker run -ti --rm --name spring-library -p 8080:8080 spring/library

For metrics, docker-compose up starts the app together with Prometheus and Grafana; the app exposes Micrometer metrics at http://localhost:8080/actuator/prometheus, Prometheus at port 9090 and Grafana at port 3000, using the local Spring profile with initial data (monitoring setup).

Constraints

• The build targets Java 11 and Maven; the README does not document newer JDK support.
• The project is explicitly described as still under construction, so APIs and model code may change.
• The domain model is simplified for teaching purposes, not a complete lending implementation.
• Spring is confined to the infrastructure layer and each context uses its own application context; the README recommends keeping one persistence strategy per application or team even though the example mixes plain SQL with Spring Data JDBC.
• Licensed under MIT.

HotRepo's take

The repository was recorded at 5,992 stars and 845 forks, gaining 11 stars in the 2026-11-08 daily snapshot of the Java list, where it reached position 10. It has no recorded placement on the all-language daily list, so the evidence describes a steady reference project rather than a breakout trend. For a learning repository, that pattern fits: the value lies in the curated progression from Event Storming notes to architectural rules and tested code, and the Java-list visibility suggests it is still being found by developers studying DDD in Spring applications.