English | 中文
jfoundry is a practical DDD framework for Java, built on jMolecules and designed for Hexagonal Architecture and Onion Architecture.
It helps business projects make domain modeling, architecture boundaries, and reliable integration executable in code. The core defines DDD concepts, architecture semantics, application contracts, domain events, persistence SPI, and messaging SPI without depending on a runtime framework. Spring, Quarkus, and Helidon assemble the same core through peer runtime integration modules.
JFoundry is not a full application framework and does not require an application to adopt every module. It is a composable capability platform: applications select the DDD, persistence, messaging, reliable-integration, and runtime capabilities they need, while framework-specific adapters remain outside the runtime-neutral core.
DDD projects often lose their intended boundaries in implementation: domain code imports framework or ORM APIs, transaction ownership is unclear, repositories become generic query interfaces, and external events are not delivered reliably. jfoundry provides:
- jMolecules-based DDD, Hexagonal, Onion, and CQRS semantics.
- Explicit dependency direction across domain, application, infrastructure, and runtime integration.
- Reusable ArchUnit rules for executable architecture constraints.
- Optional production capabilities for persistence, message delivery, reliable messaging, transactions, and runtime assembly.
The domain model stays independent of Spring, ORM, HTTP, brokers, and database clients. Application contracts orchestrate use cases and define capability SPI; infrastructure implements technical adapters; runtime integrations assemble them.
runtime integration
-> application / infrastructure adapters
-> application contracts
-> domain
Dependencies point inward. This keeps runtime integrations outside the core rather than making a particular framework a requirement for every application.
Domain Event and Outbox are independent capabilities: in-process Domain Event dispatch does not require Outbox, and generic Outbox does not require Domain Event. Applications that need reliable externalization select the explicit Domain Event Outbox composition; the optional persistence bridge keeps automatic aggregate-event collection convenient without coupling generic persistence to events.
At repository level, jfoundry-core/ groups the runtime-neutral modules, jfoundry-runtime/ groups the Spring, Quarkus, and Helidon integrations, and jfoundry-boms/ contains dependency management. These are source directory groupings, not Maven aggregator modules. The number of modules reflects two independent axes—capability and runtime or implementation—not a requirement to depend on the whole repository.
domain-architecture-skills is the
Domain Architecture Plugin that complements JFoundry at design time. It guides an AI coding agent
from requirements through domain modeling and architecture decisions. Users do not choose an
architecture style first: $domain-architecture-workflow uses confirmed business needs, external
boundaries, and project constraints to decide whether a full style is justified and, when it is,
whether Hexagonal or Onion fits. Only then does it
map the decision to JFoundry modules and ArchUnit rules. CQRS remains an optional, targeted pattern.
The plugin enters JFoundry only after the framework is selected. It is installed separately and is not a runtime dependency.
See Adoption Readiness and Validated Scope for the evidence and boundaries of using the plugin together with JFoundry.
Explore the jfoundry expense approval demo, an end-to-end reference project that validates the workflow with a deliberately small business domain, complete architecture and integration paths, and maintained Hexagonal and Onion Simple variants.
requirements -> domain modeling -> architecture decision -> optional jfoundry landing -> implementation handoff
| Area | Capability |
|---|---|
| Domain modeling | Aggregates, value objects, domain events, repository contracts, and domain exceptions |
| Architecture | Hexagonal and Onion semantics with ArchUnit rules |
| Application | Application services, transaction boundaries, CQRS, and domain-event orchestration |
| Persistence | Aggregate persistence contracts with JPA and MyBatis-Plus implementations |
| Web | RFC 9457 Problem Details and safe HTTP diagnostic logging for Spring MVC, Quarkus REST, and Helidon MP JAX-RS, plus Spring and MicroProfile REST Client logging |
| Message delivery | Runtime-neutral outbound transport contracts with explicit Kafka, RabbitMQ, and RocketMQ adapters |
| Reliable messaging | Transactional Outbox, Inbox idempotency, messaging, and serialization SPI |
| Runtime integration | Spring Framework and Spring Boot assembly; Quarkus and Helidon CDI/Jakarta Transactions, JPA, and Outbox/Inbox assembly |
JFoundry keeps capabilities independently selectable. A typical application chooses one path rather than importing the complete project:
| Need | Typical composition |
|---|---|
| DDD modeling and architecture constraints | Domain and architecture capabilities |
| In-process domain events | Domain Event capability; Outbox is not required |
| Generic reliable messaging | Outbox or Inbox capability with a selected store, transport, and serialization adapter |
| Reliable domain-event externalization | Domain Event + Outbox composition; add the optional persistence bridge when automatic aggregate-event collection is desired |
| Aggregate persistence | Persistence contract with a JPA or MyBatis-Plus implementation |
| Runtime assembly | The matching Spring, Quarkus, or Helidon integration |
This composition model keeps the default footprint small while allowing the framework to provide production-oriented capabilities when an application explicitly opts into them.
- Choose a capability: start with the Capability Catalog to map a business need to its supported runtime dependency.
- Architecture and modeling: start with Getting Started, then select an architecture style and review modeling conventions.
- Aggregate persistence: read Aggregate Persistence, then choose the peer implementation that fits the project: JPA or MyBatis-Plus.
- Web: read Web, then select RFC 9457 Problem Details or runtime-specific HTTP server and REST Client diagnostic logging.
- Message delivery: read Message Delivery to select a direct Kafka, RabbitMQ, RocketMQ, or application-owned transport adapter.
- Reliable messaging: read Reliable Messaging, then choose its JPA or MyBatis-Plus store from the corresponding JPA or MyBatis-Plus guide.
- Spring Boot: use Spring Boot Runtime Assembly for starter-based, conditional auto-configuration of selected capabilities; see the Spring Boot auto-configuration reference for its properties, conditions, and bean precedence.
- Quarkus: use Quarkus Runtime Integration for explicit extension composition, CDI transactions, Problem Details and HTTP logging, domain-event dispatch, JPA-backed reliable messaging, Kafka and RabbitMQ delivery, and Native Image verification.
- Helidon MP: use Helidon MP Runtime Integration for explicit CDI/JTA, JPA, Outbox/Inbox, Kafka and RabbitMQ delivery, Problem Details, and HTTP logging. Its Native Image support currently verifies CDI/Web only; Helidon Narayana JTA Native execution remains experimental upstream.
Every application imports the runtime-neutral BOM, then adds only the starters and capability implementations it requires. A Spring Boot, Quarkus, or Helidon application additionally imports its matching runtime BOM; runtime BOMs manage their platform ecosystems and do not replace the JFoundry BOM.
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.github.xfoundries</groupId>
<artifactId>jfoundry-dependencies</artifactId>
<version>${jfoundry.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>// Money.java
import org.jfoundry.domain.valueobject.ValueObject;
import java.math.BigDecimal;
public record Money(BigDecimal amount, String currency) implements ValueObject {
}// OrderId.java
import org.jmolecules.ddd.types.Identifier;
public record OrderId(String value) implements Identifier {
}// Order.java
import org.jfoundry.domain.entity.agg.BaseAggregateRoot;
public final class Order extends BaseAggregateRoot<Order, OrderId> {
private Money total;
public Order(OrderId id, Money total) {
super(id);
this.total = total;
}
public void changeTotal(Money total) {
this.total = total;
}
}- Getting Started
- Adoption Readiness and Validated Scope
- Support Policy
- Supply-Chain Security
domain-architecture-skills
- Capability Catalog
- Aggregate Persistence
- Web
- Message Delivery
- Reliable Messaging: Outbox And Inbox
- Application Transactions
- Distributed Locks
- Compatibility Matrix
- Maven Central Publishing
- Native Image verification status: review the scoped runtime and capability evidence together with the Compatibility Matrix; it is not a blanket support claim.
For the complete documentation structure, see the Documentation Index.
./mvnw validate
./mvnw test
./mvnw clean install