Domain Driven Kit

Executable DDD for Spring Boot.
Domain building blocks out of the box, architecture rules enforced in CI, and the same guardrails for humans and AI coding agents.

English · 简体中文 · Documentation · Roadmap

Highlights

• 🧱 Domain building blocks: Identifier, ValueObject, Entity, AggregateRoot, domain events and specifications, with zero framework dependencies enforced by tests
• 🛡️ Architecture rules that fail the build: ArchUnit rules for three- and four-layer projects, included in every generated project
• 🗄️ Safe persistence: a generic MyBatis-Plus repository with optimistic locking; missing or duplicate mappers fail at startup
• ⚡ Two-level cache: Caffeine + Redis with cross-instance invalidation, Redis failure fallback and a deserialization allow-list
• 🤖 AI-agent ready: generated projects ship AGENTS.md, CLAUDE.md and Claude Code Skills; architecture failures come with a report agents can act on; use cases can be exposed as MCP tools
• 🧩 Eleven Spring Boot starters under one ddk.* namespace: web, MyBatis, Redis, cache, data sources, tracing, Seata, domain events, MCP, concurrency control, ArchGuard
• 🚀 Start in minutes: Maven archetypes and a runnable example, built and tested in CI on Java 21 and 25

Why DDK

domain-driven-kit is not a heavy business framework. It is an evolving Java DDD engineering toolkit that turns layered architecture, response contracts, exception handling, pagination, object mapping, repository abstractions, Spring Boot starters and architecture rules into reusable code.

It is designed for teams that want to:

• Start a Java project with a clear DDD / layered architecture baseline
• Keep Controller, Application, Domain and Infrastructure responsibilities explicit
• Standardize repeated backend concerns such as API responses, exceptions, pagination and repository boundaries
• Move architecture rules into tests and CI with ArchUnit instead of leaving them only in documentation

Quick Start

Generate a four-layer service in one command. The script builds DDK, installs it into your local Maven repository and runs the archetype:

curl -fsSL https://raw.githubusercontent.com/poppycoderr/domain-driven-kit/main/scripts/ddk.sh | bash -s -- new order-service --group com.acme
cd order-service && mvn verify

Use --layers 3 for the three-layer skeleton, or DDK_REF=v0.3.0 to build a released version. Run ddk.sh help for all options.

To build DDK by hand instead:

Requirements:

• JDK 21
• Maven 3.9+
• Spring Boot 4.1.x (Jackson 3)

Build locally:

git clone https://github.com/poppycoderr/domain-driven-kit.git
cd domain-driven-kit
mvn -B -ntp verify
mvn -B install

Use in another project. Import the BOM first, then drop the versions:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.ddk</groupId>
            <artifactId>ddk-dependencies</artifactId>
            <version>0.4.0-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>com.ddk</groupId>
        <artifactId>ddk-web-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>com.ddk</groupId>
        <artifactId>ddk-mybatis-starter</artifactId>
    </dependency>

    <!-- Architecture rules belong on the test classpath only -->
    <dependency>
        <groupId>com.ddk</groupId>
        <artifactId>ddk-archguard-starter</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

See the full guide: Quick Start.

Modules

DDK is maintained by one person and is still pre-release: build it locally, try the archetypes and use it as a reference. Releases are published on GitHub rather than Maven Central for now.

Domain Model

com.ddk.core.domain does exactly three things:

• Gives identity a type. Identifier makes UserId(1) different from OrderId(1), so swapped arguments fail at compile time
• Separates value equality from identity equality. ValueObject (an empty interface, so a record can implement it) and Entity
• Gives domain events a place to be collected and published. AggregateRoot registers them, DomainEventPublisher publishes them after commit

The package depends on no framework at all — not Spring, MyBatis or Jackson. That constraint is enforced by DomainPackagePurityTest, not by a note in the docs.

The primitives provide mechanism without dictating process, and you can adopt only the part you need.

Architecture Guard

Core constraints:

• adapter adapts external protocols and should not contain business rules
• application orchestrates use cases, transactions and domain objects
• domain owns business rules and should not depend on Spring, MyBatis, Jackson or other frameworks
• infrastructure implements repository and external dependency contracts defined by the domain layer

Written in a document these are suggestions; written as a test they are constraints:

class ArchitectureTest {

    private final JavaClasses classes = new ClassFileImporter()
            .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_JARS)
            .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
            .importPackages("com.example.myapp");

    @Test
    void layered_architecture_is_respected() {
        CommonArchRules.LAYERED_ARCHITECTURE_RULE.check(classes);
    }

    @Test
    void domain_stays_framework_free() {
        CommonArchRules.DOMAIN_MUST_NOT_DEPEND_ON_FRAMEWORKS.check(classes);
    }
}

A violation fails the build. See ddk-examples/ddk-example-user for a working example.

Module Layout

domain-driven-kit
├── ddk-dependencies      BOM, so downstream projects stop writing versions
├── ddk-core              Core abstractions: domain model, exception, response, pagination, mapper, repository contract
├── ddk-mybatis           MyBatis-Plus repository implementation and query adapters
├── ddk-starters          Spring Boot starter modules
│   ├── ddk-web-starter
│   ├── ddk-mybatis-starter
│   ├── ddk-redis-starter
│   ├── ddk-cache-starter
│   ├── ddk-db-starter
│   ├── ddk-tracer-starter
│   ├── ddk-seata-starter
│   ├── ddk-event-starter
│   ├── ddk-mcp-starter
│   ├── ddk-concurrency-starter
│   └── ddk-archguard-starter
├── ddk-archetypes        3-layer / 4-layer project skeletons
└── ddk-examples          Example applications

Inside ddk-core:

com.ddk.core
├── domain        Domain model primitives, zero framework dependencies
├── repository    The GenericRepository contract
├── page          PageQuery / PageResponse / Sort
├── mapper        MapperProvider and @EnhancedMapper
├── response      ApiResponse
└── exception     ErrorCode and the exception hierarchy

Roadmap

The foundation (domain model, repositories, nine starters, archetypes and examples) is complete, and v0.1.0 is released. Next milestones:

1. v0.1 Modern baseline and first release: Spring Boot 4.1 / Jackson 3 and the first GitHub Release
2. v0.2 AI collaboration: generated projects ship AGENTS.md and Skills, ArchGuard reports violations agents can act on, an MCP starter on Spring AI
3. v0.3 Reliable domain events: transactional outbox, RocketMQ / Kafka delivery, idempotent consumers
4. v0.4 Middleware integrations: Redisson aggregate locks, XXL-Job, Flyway, springdoc, Elasticsearch read models
5. v1.0 Production ready: the ddk-mall reference application, native images, a frozen public API

See ROADMAP.md for the full plan.

Documentation

• DDK documentation
• Quick Start
• Domain Model Primitives
• Layering and Architecture Guard
• Development and Refactoring Plan

Contributing

Issues and PRs are welcome. The most useful contributions right now are:

• Starter auto-configuration fixes
• Tests and runnable examples
• DDD layering examples and documentation
• Clearer trade-off analysis for existing design decisions

Run mvn verify before opening a PR: it checks formatting with Spotless (fix with mvn spotless:apply) and requires at least 70% line and 50% branch coverage per module. Main code is @NullMarked: mark anything that may be null with @Nullable, or NullAway fails the compile.

Built With

• Code and docs are written in IntelliJ IDEA with the help of Claude Code and Codex; every change is reviewed, tested and passes CI before it is merged.
• The documentation site codesphere is built with VitePress; earlier versions used docsify.

License

Apache License 2.0. Free to use, modify and distribute, including commercially; keep the copyright and license notices, and state changes made to modified files.