jMolecules

Mar 19, 2026 · 4 min read

jmolecules software-architecture annotations java kotlin

Contents

What is jMolecules

jMolecules is an annotation library that makes architectural concepts explicit in your Java and Kotlin code. Instead of relying on naming conventions or documentation to communicate which class is an Aggregate Root, which package is the Domain Layer, or which interface is a Port — you annotate them directly.

jMolecules Architecture Patterns — Three complementary approaches to structuring Java and Kotlin applications

The library provides annotations for three major architecture styles:

When combined with ArchUnit, jMolecules enforces dependency rules at compile time. Violations are caught automatically in your CI/CD pipeline — no manual architectural reviews needed.

Why Use It

Explicit Architecture

Annotations declare intent. A class annotated @AggregateRoot communicates its role to every reader — humans and tools alike.

Compile-Time Enforcement

ArchUnit integration detects dependency violations during build. The Infrastructure layer importing from the Domain layer? Caught before merge.

Documentation as Code

Architecture decisions live in the code, not in stale wiki pages. Refactor and the documentation moves with the code.

Framework Agnostic

Pure Java annotations with zero runtime dependencies. Works with Spring Boot, Quarkus, Micronaut, or plain Java.

Architecture Patterns

jMolecules organizes its annotations into three packages, each targeting a different architectural style. Click through to the detailed guides:

Layered Architecture

Four layers — Interface, Application, Domain, Infrastructure — with strict top-down dependency direction. Each layer may only depend on the layer directly below it.

Read the guide →

Hexagonal Architecture

Ports & Adapters pattern. The domain sits at the center, isolated from external concerns via primary and secondary ports with dependency inversion.

Read the guide →

DDD Building Blocks

Tactical DDD patterns: Aggregate Roots, Entities, Value Objects, Repositories, Services, Factories, and Domain Events with enforced boundaries.

Read the guide →

Getting Started

Add the dependency

Gradle (Kotlin DSL):

// jMolecules annotations
implementation("org.jmolecules:jmolecules-ddd:1.9.0")
implementation("org.jmolecules:jmolecules-layered-architecture:1.9.0")
implementation("org.jmolecules:jmolecules-hexagonal-architecture:1.9.0")

// ArchUnit integration (test scope)
testImplementation("org.jmolecules.integrations:jmolecules-archunit:1.9.0")

Maven:

<dependency>
    <groupId>org.jmolecules</groupId>
    <artifactId>jmolecules-ddd</artifactId>
    <version>1.9.0</version>
</dependency>
<dependency>
    <groupId>org.jmolecules.integrations</groupId>
    <artifactId>jmolecules-archunit</artifactId>
    <version>1.9.0</version>
    <scope>test</scope>
</dependency>

Annotate your code

package com.example.order.domain

import org.jmolecules.ddd.annotation.*

@AggregateRoot
class Order(val id: OrderId, val items: List<OrderItem>) {
    fun total(): Money = items.fold(Money.ZERO) { sum, item -> sum + item.subtotal }
}

@ValueObject
data class Money(val amount: BigDecimal, val currency: String)

@Repository
interface OrderRepository {
    fun save(order: Order)
    fun findById(id: OrderId): Order?
}

Enforce with ArchUnit

import org.jmolecules.archunit.JMoleculesArchitectureRules

class ArchitectureTest {
    @Test
    fun `DDD rules are respected`() {
        JMoleculesArchitectureRules
            .ensureDddCompliance()
            .check(ArchConfiguration.importedClasses())
    }
}
The ArchUnit rules verify that Repositories only reference Aggregate Roots, Value Objects have no mutable state, and domain objects never depend on infrastructure — all at build time.