← Back to archive

Repo of the Day

ddd-by-examples/library

Published: Nov 16, 2026

Open repository ↗

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

Summary

ddd-by-examples/library is a Java example of Domain-Driven Design applied to a public-library lending system, where patrons place holds, check out books, and interact with branch-specific rules. It connects Event Storming, Example Mapping, and design-level discovery to a modular-monolith implementation using aggregates, domain events, hexagonal architecture, CQRS-style read/write separation, and type-based modeling.

What it is useful for

The repository is useful as a reference for turning a business domain into an explicit domain model:

  • Its domain includes concrete rules that can guide implementation, such as restricted books being available only to researcher patrons, regular patrons being limited to five active holds, and checkout periods of up to 60 days.
  • The lending context demonstrates a domain model with hexagonal architecture, while contexts with less complex logic use CRUD-like designs. Each bounded context initially lives in a separate package.
  • Aggregate states are represented by separate types such as AvailableBook, BookOnHold, and CheckedOutBook. A method such as placeOnHold(AvailableBook) makes invalid states harder to pass at compile time.
  • The README shows both immediate consistency through Spring application events and eventual consistency through stored, periodically published events. Tests are written so the application-facing assertions remain similar when the consistency model changes.
  • ArchUnit examples enforce boundaries, including rules that model code must not depend on infrastructure or Spring.
  • Persistence deliberately avoids JPA. The examples use plain SQL with JdbcTemplate and Spring Data JDBC, while domain and persistence models remain separate.

It is also a useful study of the architecture-code gap: package boundaries, immutable objects, pure domain functions, Vavr’s Option, Either, and Try, and CQRS-style separation between patron profiles and daily sheets.

The README explicitly says this is not a reference project for functional programming. It also notes the tradeoffs of eventual consistency and recommends choosing one persistence approach within an application or team.

How engineers can use it

Start with the README’s domain description, then follow its links to docs/big-picture.md, docs/example-mapping.md, and docs/design-level.md. Those documents show how the discovery process produced the model rather than presenting the code without its design context.

Next, trace one operation—such as placing a hold—from the lending model through its application and infrastructure layers. Compare the immediate- and eventual-consistency tests, then review the ArchUnit rules and persistence examples to see which patterns fit a real service.

The supplied README does not document a complete build, database setup, or application startup command, so consult the repository README before running the examples. For dependency inspection, it specifically documents mvn dependency:tree.