Library / SDK
ddd-by-examples/library avatar
ddd-by-examples/library

ddd-by-examples/library: a DDD reference implementation in Java

A comprehensive Domain-Driven Design example with problem space strategic analysis and various tactical patterns.

6,051 stars849 forksJavaMIT

At a glance

What is it?
A Java modular monolith that models a public library with bounded contexts, hexagonal architecture and event-driven aggregates. It is a teaching codebase, not a library you add to a dependency list.
Who is it for?
Adopt ddd-by-examples/library if you are learning how strategic DDD decisions turn into package boundaries, or if you need a worked example to argue a design in a code review. Do not adopt it as a foundation for a production library system: the README itself calls the domain model a simplified abstraction, the consistency choice is immediate rather than eventual, and there is no release artifact to depend on.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 59 days ago.
What is it written in?
Mainly Java, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • ddd-by-examples/library6,051 ★ · +180
Star history
Repository2026-09-232026-11-15
ddd-by-examples/library5.9k6.1k

180 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What ddd-by-examples/library actually is, and who it is for

This is a sample application built around a single domain: a public library where patrons place books on hold at branches. The README describes the rules in detail. A book is either circulating or restricted, holds can be open-ended or closed-ended, a regular patron is limited to five holds while a researcher patron has no limit, and a branch rejects a hold when the patron already has more than two overdue checkouts there.

The intended reader is a developer or architect who already knows the vocabulary and wants to see it applied. The README walks through process discovery before it shows any code. That ordering is the point. If you want a Spring CRUD starter, this is the wrong repository, because the CRUD path exists only for the bounded contexts that Event Storming showed to have no complex logic.

It is also not a consumable dependency. The repository has no published GitHub releases, and the README never presents the project as something you install into another application. You read it, run it, and copy patterns out of it.

Bounded contexts, hexagonal lending, and CRUD everywhere else

The architecture note in the README is explicit about the split. Each bounded context gets its own package, which makes the system a modular monolith. The README adds that nothing prevents moving contexts into Maven modules or out into microservices later, which is the usual argument for the package-first approach.

The interesting part is that contexts do not share one local architecture. The lending context, where the README says real business logic lives, gets a domain model and hexagonal architecture. Contexts that turned out to lack complex logic get CRUD-like local architecture. That asymmetry is the most transferable idea in the repository: architectural uniformity across a system is treated as a cost, not a virtue.

The README also states that read and write models were separated into CQRS for cases such as Patron Profiles and Daily Sheets. Those two are described as daily-sheet-like views, one scoped to a single patron and not necessarily daily, the other used by the branch to sweep expiring holds and overdue checkouts at the beginning of a day.

Aggregates communicate through events. The README records the contention honestly: eventual consistency fits business boundaries better, but it needs a message broker or an event store, so the project started with immediate consistency. That is a deliberate simplification with a stated price, and it is the first thing to reconsider if you copy the model.

Running the library example with Docker and a first hold request

The repository ships a Dockerfile and a docker-compose.yml, so the fastest path does not require you to build the jar by hand. The compose file defines three services: the application, Prometheus and Grafana. The application service builds from the Dockerfile in the repository root and is published on port 8080, with SPRING_PROFILES_ACTIVE set to local. Prometheus listens on 9090 and Grafana on 3000.

yaml
services:
  app:
    image: spring/library:latest
    container_name: 'library'
    build:
      context: ./
      dockerfile: Dockerfile
    environment:
      - "SPRING_PROFILES_ACTIVE=local"
    ports:
      - '8080:8080'

That is the application service as it appears in the repository's docker-compose.yml. Prometheus listens on 9090 with ./monitoring/prometheus mounted at /etc/prometheus/, and Grafana listens on 3000 with ./monitoring/grafana/provisioning/ mounted under /etc/grafana/provisioning/.

If you prefer to run the jar directly, the Dockerfile shows what the image expects. It is based on openjdk:11.0.1-jre-slim-stretch, exposes 8080, copies the jar to /app.jar and starts it with java -jar. The build argument names the jar library-0.0.1-SNAPSHOT.jar.

dockerfile
FROM openjdk:11.0.1-jre-slim-stretch
EXPOSE 8080
WORKDIR /app
ARG JAR=library-0.0.1-SNAPSHOT.jar

COPY  /target/$JAR /app.jar
ENTRYPOINT ["java","-jar","/app.jar"]

The domain rules it does document are the ones to exercise: add a book with a non-empty title and a price, add an instance of it as circulating or restricted, then try a hold as a regular patron and watch the five-hold limit and the overdue-checkout rejection at the branch.

The consistency choice and the model-code gap

The README is unusually candid about the gap between the model on the Event Storming wall and the code. It has sections titled Architecture-code gap and Model-code gap, and it warns that the domain model is a simplified abstraction of reality for the purpose of the project. Treat every aggregate boundary in the code as an illustration, not as a validated design.

The consistency decision compounds this. Immediate consistency was chosen to avoid needing a broker or event store, and the README says eventual consistency would have been the better fit for aggregate boundaries. In a real library system, the daily sheet that expires holds and flags overdue checkouts is exactly the kind of process that tolerates a delay, while a hold placed on a book is not. The README adds that it made the consistency model easy to change, providing tests for each option and basic implementations based on a DomainEvents interface.

There is a second boundary to watch. The README notes that a book can be both circulating and restricted for the same ISBN, which is why the instance carries that decision rather than the book. If you flatten instance into book when adapting the model, you lose the signed-copy case the README uses as its example.

How this differs from a Spring Data CRUD service

The obvious alternative for a Java team is a Spring Boot service with Spring Data repositories, where entities map to tables and business rules live in service methods. That approach is faster to start and needs no Event Storming session. The difference here is not stylistic.

In the CRUD approach, the hold limit, the researcher-patron rule and the overdue rejection end up spread across service methods and validators, and the database schema becomes the de facto model. In this repository, those rules sit inside the lending context's domain model, and the README states that the hexagonal split lets you unit test the business logic without stubbing dependencies.

The cost is real too. Two local architectures in one codebase mean a new contributor has to learn which context follows which style, and the README's own framing of CRUD contexts as those lacking complex logic is a judgement that will be wrong for some teams. ArchUnit is used to enforce the boundaries, which helps, but the enforcement only covers the rules someone wrote down.

Maintenance, licence and what upgrading costs you

The repository is not archived, and the last push was on 2026-09-17. The repository has no published GitHub releases, so there is no versioned artifact to track and no changelog to read before upgrading. If you vendor code from it, you are copying a snapshot rather than depending on a maintained package.

The practical upgrade cost is the stack. The Dockerfile pins openjdk:11.0.1-jre-slim-stretch, and the compose file pins prom/prometheus:v2.4.3 and grafana/grafana:5.2.4. Those are fixed versions in the repository, so the example runs reproducibly, but a team adopting the patterns on a current JDK or a current Grafana will be adapting rather than upgrading.

The licence is MIT, which is permissive and places few conditions on reuse. That is a statement about the licence text, not legal advice; if you plan to redistribute modified code, read the LICENSE file in the repository root and get your own review.

Editorial conclusion

Adopt ddd-by-examples/library if you are learning how strategic DDD decisions turn into package boundaries, or if you need a worked example to argue a design in a code review. Do not adopt it as a foundation for a production library system: the README itself calls the domain model a simplified abstraction, the consistency choice is immediate rather than eventual, and there is no release artifact to depend on. Before copying anything, read docs/big-picture.md, docs/example-mapping.md and docs/design-level.md, then open the lending context and check that its aggregate boundaries match the ones your own domain experts drew.

Frequently asked questions

What is ddd-by-examples/library?

It is a Java example application that models a public library domain using Domain-Driven Design, with problem-space analysis through Event Storming and tactical patterns such as aggregates and events in the code. The README describes it as a project driven by real business requirements, covering holds, checkouts, overdue rules and researcher patrons.

How do you run ddd-by-examples/library locally?

The repository includes a docker-compose.yml that builds the application from the Dockerfile and publishes it on port 8080, alongside Prometheus on 9090 and Grafana on 3000. The Dockerfile expects library-0.0.1-SNAPSHOT.jar, built from the Maven project in the repository.

Does ddd-by-examples/library use microservices or a monolith?

The README states that each bounded context is assigned to a separate package, which makes the system a modular monolith. It adds that there is nothing preventing you from moving contexts into Maven modules or into microservices later.

Why does ddd-by-examples/library use immediate consistency instead of eventual consistency?

The README says eventual consistency fits aggregate boundaries better, but it requires infrastructure such as a message broker or an event store. The project chose immediate consistency to avoid that infrastructure at the start.

Official sources

  1. ddd-by-examples/library on GitHub
  2. Issues
  3. License: MIT
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/ddd-by-examples-library.svg)](https://hysenlabs.com/projects/ddd-by-examples-library)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/ddd-by-examples-library.svg)](https://hysenlabs.com/projects/ddd-by-examples-library)

Was this useful?