If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/citerus/dddsample-core shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 11mo ago
• 11 active contributors
• Distributed ownership (top contributor 36% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 11mo ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live citerus/dddsample-core repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/citerus/dddsample-core.

What it runs against: a local clone of citerus/dddsample-core — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in citerus/dddsample-core | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 370 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of citerus/dddsample-core. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/citerus/dddsample-core.git
#   cd dddsample-core
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of citerus/dddsample-core and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "citerus/dddsample-core(\\.git)?\\b" \\
  && ok "origin remote is citerus/dddsample-core" \\
  || miss "origin remote is not citerus/dddsample-core (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main/java/se/citerus/dddsample/Application.java" \\
  && ok "src/main/java/se/citerus/dddsample/Application.java" \\
  || miss "missing critical file: src/main/java/se/citerus/dddsample/Application.java"
test -f "src/main/java/se/citerus/dddsample/domain/model/cargo/Cargo.java" \\
  && ok "src/main/java/se/citerus/dddsample/domain/model/cargo/Cargo.java" \\
  || miss "missing critical file: src/main/java/se/citerus/dddsample/domain/model/cargo/Cargo.java"
test -f "src/main/java/se/citerus/dddsample/application/impl/BookingServiceImpl.java" \\
  && ok "src/main/java/se/citerus/dddsample/application/impl/BookingServiceImpl.java" \\
  || miss "missing critical file: src/main/java/se/citerus/dddsample/application/impl/BookingServiceImpl.java"
test -f "src/main/java/se/citerus/dddsample/domain/model/cargo/Delivery.java" \\
  && ok "src/main/java/se/citerus/dddsample/domain/model/cargo/Delivery.java" \\
  || miss "missing critical file: src/main/java/se/citerus/dddsample/domain/model/cargo/Delivery.java"
test -f "src/main/java/se/citerus/dddsample/domain/shared/Specification.java" \\
  && ok "src/main/java/se/citerus/dddsample/domain/shared/Specification.java" \\
  || miss "missing critical file: src/main/java/se/citerus/dddsample/domain/shared/Specification.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 370 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~340d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/citerus/dddsample-core"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A reference implementation of Domain-Driven Design (DDD) principles built as a Spring Boot 3.3.10 cargo tracking application. It models a real-world shipping domain with bounded contexts (Booking, Handling, Pathfinding) and demonstrates tactical DDD patterns—Value Objects, Aggregates, Repositories, Application Services—using Java with an in-process HSQL database and REST API for handling reports. Single Spring Boot application with clear bounded contexts: se.citerus.dddsample.application (Application Services: BookingServiceImpl, CargoInspectionServiceImpl, HandlingEventServiceImpl), se.citerus.dddsample.domain.model (Domain entities and value objects), com.pathfinder (separate routing context). Configuration in DDDSampleApplicationContext and PathfinderApplicationContext. REST endpoint at POST /dddsample/handlingReport backed by API docs in api-docs.yaml.

Enterprise Java developers and architects learning DDD who need a working reference model to understand how aggregates, repositories, and application services work together in a production-like Spring Boot application. Educational resource curated by Eric Evans (DDD author) and Citerus consulting.

Actively maintained but educational-grade: the project has CI/CD (GitHub Actions pipeline in .github/workflows/pipeline.yml), uses Spring Boot 3.3.10 (current LTS), includes test coverage, and moved from SourceForge to GitHub in recent years. It's a living reference implementation rather than a production framework—suitable for learning but not actively deployed at scale.

Low risk for learning/reference use. Spring Boot parent dependency is current (3.3.10). No visible high-risk patterns: the codebase is small (~350KB Java), maintainer risk is mitigated by Citerus + Domain Language stewardship, and breaking changes are unlikely given its stable reference nature. Main risk: if you fork it for production, you inherit responsibility for security/performance upgrades.

Upgrading from legacy Java/Spring to modern Spring Boot 3.3.10 (parent POM in pom.xml). Recent additions: Dependabot configuration (.github/dependabot.yml) for dependency management, REST API formalization with OpenAPI spec (api-docs.yaml), and DrawIO architecture diagram (dddsample.drawio.xml). Active discussion on Google Groups (linked in README).

git clone https://github.com/citerus/dddsample-core.git
cd dddsample-core
./mvnw spring-boot:run
# Open http://localhost:8080/dddsample in browser

On Windows, use mvnw.cmd instead of ./mvnw. To verify build and tests: ./mvnw verify.

Daily commands: Development: ./mvnw spring-boot:run (starts on port 8080). Production simulation: same command (uses embedded HSQL). Testing: ./mvnw verify. Documentation site: ./mvnw site:run (then http://localhost:8080). API testing: curl --data-binary @src/test/resources/sampleHandlingReport.json -H 'Content-Type: application/json;charset=UTF-8' http://localhost:8080/dddsample/handlingReport.

• src/main/java/se/citerus/dddsample/Application.java — Spring Boot entry point; understand how the application initializes and which components are loaded.
• src/main/java/se/citerus/dddsample/domain/model/cargo/Cargo.java — Core domain entity representing cargo; demonstrates DDD aggregate design and state transitions.
• src/main/java/se/citerus/dddsample/application/impl/BookingServiceImpl.java — Primary application service orchestrating cargo booking; shows how domain objects interact with repositories and domain services.
• src/main/java/se/citerus/dddsample/domain/model/cargo/Delivery.java — Value object encapsulating cargo delivery state; critical for understanding DDD value object patterns used throughout.
• src/main/java/se/citerus/dddsample/domain/shared/Specification.java — Abstract specification pattern implementation; foundation for query logic and business rule evaluation across domain.
• pom.xml — Maven configuration defining Spring Boot 3.3.10 parent and all dependencies; required for build understanding.
• src/main/java/se/citerus/dddsample/infrastructure/messaging/jms/JmsApplicationEventsImpl.java — JMS event publishing; shows how domain events propagate through the system via messaging infrastructure.

Add a New Handling Event Type

1. Add the event type to the enumeration in src/main/java/se/citerus/dddsample/domain/model/handling/HandlingEvent.java (check Type enum) (src/main/java/se/citerus/dddsample/domain/model/handling/HandlingEvent.java)
2. Update HandlingEventFactory.createHandlingEvent() to validate rules for the new type (src/main/java/se/citerus/dddsample/domain/model/handling/HandlingEventFactory.java)
3. Register a JMS consumer in src/main/java/se/citerus/dddsample/infrastructure/messaging/jms/ following CargoHandledConsumer pattern (src/main/java/se/citerus/dddsample/infrastructure/messaging/jms/CargoHandledConsumer.java)
4. Update HandlingEventServiceImpl.registerHandlingEvent() to handle the new type in business logic (src/main/java/se/citerus/dddsample/application/impl/HandlingEventServiceImpl.java)

Add a New Cargo Specification Rule (for Routing)

1. Create a new specification class in src/main/java/se/citerus/dddsample/domain/model/cargo/ extending RouteSpecification or use composition (src/main/java/se/citerus/dddsample/domain/model/cargo/RouteSpecification.java)
2. Implement the Specification interface (isSatisfiedBy method) to test cargo eligibility (src/main/java/se/citerus/dddsample/domain/shared/Specification.java)
3. Integrate the specification into Cargo.isEligibleForBooking() or Delivery state transition logic (src/main/java/se/citerus/dddsample/domain/model/cargo/Cargo.java)

Add a New Application Service (Use Case)

1. Create a service interface in src/main/java/se/citerus/dddsample/application/ (e.g., CargoTransferService.java) (src/main/java/se/citerus/dddsample/application/BookingService.java)
2. Implement the interface in src/main/java/se/citerus/dddsample/application/impl/ with transaction boundaries and repository calls (src/main/java/se/citerus/dddsample/application/impl/BookingServiceImpl.java)
3. Register the implementation bean in DDDSampleApplicationContext.java (src/main/java/se/citerus/dddsample/config/DDDSampleApplicationContext.java)
4. Publish domain events via ApplicationEvents.cargoWasXXX() at the service layer (src/main/java/se/citerus/dddsample/application/ApplicationEvents.java)

Add a New Voyage Constraint or Validation

1. Update Schedule or CarrierMovement classes in src/main/java/se/citerus/dddsample/domain/model/voyage/ (src/main/java/se/citerus/dddsample/domain/model/voyage/Schedule.java)
2. Add validation logic in Voyage aggregate or create a domain specification for route feasibility (src/main/java/se/citerus/dddsample/domain/model/voyage/Voyage.java)
3. Call the validation in RoutingService domain service or in BookingServiceImpl when assigning itinerary (src/main/java/se/citerus/dddsample/domain/service/RoutingService.java)

No major traps, but notable quirks: (1) HSQL runs in-memory by default—data is lost on restart (not an issue for learning, but expect no persistence). (2) The pathfinder module (com.pathfinder) is semi-independent with its own Spring context (PathfinderApplicationContext.java)—changing it without understanding the separation may break routing. (3) Port 8080 is hardcoded in examples; if it's in use, you'll get a bind error (change via Spring properties if needed). (4) JavaScript must be enabled on localhost in your browser for the web UI at /dddsample to work.

• Bounded Context — This codebase explicitly separates Booking, Handling, and Pathfinding into distinct contexts (different Java packages with independent configs); understanding context boundaries is core to DDD design
• Aggregate — Cargo, Handling Event, and Route are modeled as Aggregates with clear root entities and invariants; you need to grasp how aggregates enforce consistency boundaries and how repositories load/save them as units
• Value Object — Entities like Leg, Port, and Location are Value Objects (immutable, compared by value not identity); this codebase uses them extensively to model domain concepts safely and avoid primitive obsession
• Repository Pattern — The application layer uses repositories to abstract persistence (likely in the domain.model package, backed by Spring Data or JPA); understanding how repos bridge domain objects and databases is essential for DDD
• Application Service — BookingServiceImpl, CargoInspectionServiceImpl, and HandlingEventServiceImpl in se.citerus.dddsample.application.impl orchestrate domain logic into use cases; they are the thin glue layer that prevents domain logic from leaking into controllers
• Domain Event — Handling Events (cargo received, customs cleared, etc.) are captured as domain events in the model; the application listens and reacts to these events to maintain consistency across aggregates
• Ubiquitous Language — The code uses shipping domain terminology consistently (Cargo, Leg, Handling Event, Port, Location)—this alignment between code and domain expert language is the heart of DDD, visible in class names and method signatures

• spring-projects/spring-boot — The parent framework and runtime—understanding Spring Boot 3.3.10 internals is essential for running and extending this application
• EventStore/EventStoreDB — A companion pattern if you want to replace the in-memory HSQL store with Event Sourcing, a natural DDD progression for capturing domain events (Handling Events in this domain)
• vaadin/flow — Modern Java web framework that pairs well with Spring Boot for building richer UIs than the basic /dddsample page without leaving the Java ecosystem
• eclipse-ee4j/jpa-api — JPA/Hibernate is implied but not visible in the file list—likely used for persistence in domain.model repositories, understanding the ORM impedance mismatch with DDD is key learning
• Netflix/Hystrix — Fault-tolerance library relevant if you want to add resilience patterns (circuit breakers) around the Pathfinder service calls in a microservices evolution of this monolith

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for domain model cargo package

The cargo domain model (src/main/java/se/citerus/dddsample/domain/model/cargo/) contains critical DDD aggregates like Cargo, Itinerary, Leg, Delivery, and RouteSpecification, but there's no visible test coverage in src/test. These value objects and entities are foundational to the DDD sample and need robust tests to demonstrate proper domain behavior validation.

• [ ] Create src/test/java/se/citerus/dddsample/domain/model/cargo/ directory structure
• [ ] Add CargoTest covering factory creation, invariants, and state transitions
• [ ] Add ItineraryTest and LegTest validating routing logic and voyage constraints
• [ ] Add DeliveryTest for complex calculation logic and transport status updates
• [ ] Add RouteSpecificationTest for origin/destination and deadline validation
• [ ] Ensure tests demonstrate DDD concepts: value object equality, aggregate boundaries, and domain rules

Add integration tests for application services layer

The application services (BookingServiceImpl, HandlingEventServiceImpl, CargoInspectionServiceImpl in src/main/java/se/citerus/dddsample/application/impl/) orchestrate domain logic but lack visible test coverage. Adding integration tests with Spring context would validate the application layer's coordination of repositories, factories, and domain events.

• [ ] Create src/test/java/se/citerus/dddsample/application/impl/ directory
• [ ] Add BookingServiceImplTest covering booking workflow with mocked CargoRepository and RoutingService
• [ ] Add HandlingEventServiceImplTest validating event creation and Cargo state updates
• [ ] Add CargoInspectionServiceImplTest for delivery milestone inspection logic
• [ ] Use @SpringBootTest or @WebMvcTest to test service layer with Spring context
• [ ] Include tests for ApplicationEvents publishing and handling

Create REST endpoint integration tests and API documentation validation

The repo contains api-docs.yaml for OpenAPI documentation, but there's no visible test coverage validating that actual REST endpoints (likely in a presentation layer not shown) match the documented specification. Add tests to ensure API contract compliance and prevent documentation drift.

• [ ] Create src/test/java/se/citerus/dddsample/interfaces/ directory (or appropriate REST controller location)
• [ ] Add REST controller integration tests using MockMvc for booking, cargo tracking, and handling endpoints
• [ ] Validate responses match api-docs.yaml schemas using OpenAPI assertion libraries (e.g., assertj-swagger or spring-cloud-contract)
• [ ] Add parameterized tests for common error cases (invalid tracking IDs, routing failures)
• [ ] Include test for 404 handling for non-existent cargos to demonstrate proper REST conventions
• [ ] Reference api-docs.yaml in test documentation comments for traceability

• The src/main/java/se/citerus/dddsample/domain/model/ directory has no visible test doubles or test factories—add a DDD Test Fixtures file (e.g., CargoTestFactory.java) with builder patterns for Cargo, Leg, and Handling Event to make domain testing more readable and maintainable: Easy (pattern work, no new concepts)
• The Pathfinder module (com.pathfinder.internal.GraphDAOStub.java) returns stub graph data—extend it with a simple algorithm test that verifies GraphTraversalServiceImpl.findShortestPath() correctly routes between 3+ real ports, then document the expected behavior in src/main/java/com/pathfinder/api/package.html: Medium (requires understanding graph traversal and test setup)
• The REST endpoint POST /dddsample/handlingReport is documented in api-docs.yaml, but there's no visible Java REST controller test class or integration test that validates the API contract—add an HandlingReportControllerTest.java in src/test/ that POSTs the sample JSON and verifies cargo state transitions: Medium (REST testing, Spring test setup)

• High · Outdated Spring Boot Version — pom.xml - spring-boot-starter-parent version 3.3.10. The project uses Spring Boot 3.3.10, which may contain known security vulnerabilities. Spring Boot versions should be kept up-to-date with the latest stable releases to ensure all security patches are applied. Fix: Update to the latest stable Spring Boot 3.x version (check https://spring.io/projects/spring-boot for current releases). Review release notes for security fixes.
• Medium · Missing Dependency Security Scanning — pom.xml. The pom.xml file is incomplete in the provided content, making it impossible to perform a full dependency vulnerability analysis. There may be transitive dependencies with known CVEs that are not visible. Fix: Run 'mvn dependency:tree' and use tools like OWASP Dependency-Check or Snyk to identify vulnerable dependencies. Consider adding a Maven security plugin to the build pipeline.
• Medium · Default Port Exposure — Application.java and README.md. The application runs on the default port 8080 without visible security configuration. The README explicitly mentions accessing http://localhost:8080/dddsample, suggesting default configuration is used in production scenarios. Fix: Configure Spring Security with proper authentication/authorization. Use HTTPS instead of HTTP. Set a custom port in application.properties. Implement rate limiting and access controls.
• Medium · No Visible Security Configuration — src/main/java/se/citerus/dddsample/config/ - Missing security configuration. The codebase structure does not show any Spring Security configuration files (SecurityConfig, WebSecurityConfigurerAdapter implementations). This suggests security may not be properly configured. Fix: Implement Spring Security configuration with: CSRF protection, authentication mechanism, authorization rules, HTTPS enforcement, security headers (X-Frame-Options, X-Content-Type-Options, etc.)
• Medium · Potential SQL Injection via Repository Pattern — src/main/java/se/citerus/dddsample/domain/model/*/Repository.java files. Multiple repository classes (CargoRepository, HandlingEventRepository, LocationRepository, VoyageRepository) are present without visible implementation details. If raw SQL queries are used instead of parameterized queries, SQL injection is possible. Fix: Ensure all repositories use parameterized queries or ORM frameworks (JPA/Hibernate) which prevent SQL injection. Never concatenate user input into SQL queries. Use prepared statements.
• Medium · No Visible Input Validation — src/main/java/se/citerus/dddsample/domain/model/*/. Value objects like TrackingId, UnLocode, VoyageNumber are created without visible validation logic shown in the file structure. These could accept malicious or invalid input. Fix: Implement strict input validation in constructors of value objects. Use Bean Validation (@Valid, @NotNull, @Pattern, etc.). Validate all user inputs at application boundaries.
• Low · Incomplete Security Headers Configuration — src/main/java/se/citerus/dddsample/config/. No visible configuration for security headers (Content-Security-Policy, X-Frame-Options, Strict-Transport-Security, etc.) in the provided files. Fix: Configure Spring Security to add security headers. Add filter or configuration for: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Strict-Transport-Security.
• Low · No Visible Error Handling Configuration — src/main/java/se/citerus/dddsample/application/. No @ControllerAdvice or GlobalExceptionHandler visible in the file structure. This may lead to verbose error messages exposing internal application details. Fix: Implement a global exception handler to catch exceptions and return generic error messages to users. Log detailed errors server-side only. Avoid exposing stack traces or internal details.
• Low · No Visible Logging Configuration — src/main/config/. No log4j2.xml or logback-spring.xml visible in the file structure. Proper logging configuration is needed to track security events. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.