1
Core (Domain + Application)
2
    ↓ depends on
3
Ports (Interfaces)
4
    ↑ implemented by
5
Adapters (Infrastructure)

1
// Port (Application Layer)
2
interface OrganizationRepositoryPort {
3
    fun save(organization: Organization): Organization
4
}
5

6
// Adapter (Infrastructure Layer)
7
@Component
8
class OrganizationJdbcAdapter : OrganizationRepositoryPort {
9
    override fun save(organization: Organization): Organization {
10
        // JDBC implementation details (map to entity, persist, map back)
11
        return organization
12
    }
13
}

1
// Command Side (Mutates state)
2
fun interface CreateOrganizationPort {
3
    fun execute(command: CreateOrganizationCommand): Organization
4
}
5

6
// Query Side (Returns data)
7
fun interface GetOrganizationByIdPort {
8
    fun execute(id: UUID): Organization
9
}

1
// Aggregate Root — regular class (NOT data class), private ctor + factory,
2
// invariants in `init`, state transitions own their guard rules.
3
class Organization private constructor(
4
    val id: UUID,
5
    val name: OrganizationName,
6
    val status: OrganizationStatus,
7
    val updatedAt: Instant,
8
    val version: Long,
9
) {
10
    init { require(version >= 0) { "version must be non-negative" } }
11

12
    fun transitionTo(newStatus: OrganizationStatus, clock: Clock): Organization {
13
        require(status.canTransitionTo(newStatus)) {
14
            "Illegal transition from $status to $newStatus"
15
        }
16
        return Organization(id, name, newStatus, clock.instant(), version + 1)
17
    }
18

19
    fun isActive(): Boolean = status == OrganizationStatus.ACTIVE
20

21
    companion object {
22
        fun create(id: UUID, name: OrganizationName, clock: Clock): Organization =
23
            Organization(id, name, OrganizationStatus.PENDING_APPROVAL, clock.instant(), version = 0)
24
    }
25
}
26

27
// State-transition rules live on the enum — cohesive with the type.
28
enum class OrganizationStatus {
29
    PENDING_APPROVAL, ACTIVE, INACTIVE, SUSPENDED;
30

31
    fun canTransitionTo(target: OrganizationStatus): Boolean = when (this) {
32
        PENDING_APPROVAL -> target == ACTIVE || target == INACTIVE
33
        ACTIVE           -> target == INACTIVE || target == SUSPENDED
34
        INACTIVE         -> target == ACTIVE
35
        SUSPENDED        -> target == ACTIVE || target == INACTIVE
36
    }
37
}

1
Request DTO → Command → Use Case → Domain Entity

1
// Command
2
data class CreateOrganizationCommand(
3
    val name: String,
4
    val contactEmail: String,
5
    // ... other fields
6
)
7

8
// Command Handler (Use Case)
9
class CreateOrganizationUseCase : CreateOrganizationPort {
10
    override fun execute(command: CreateOrganizationCommand): Organization {
11
        val organization = command.toOrganization()
12
        return repository.save(organization)
13
    }
14
}

1
// Port (Application)
2
interface OrganizationRepositoryPort {
3
    fun save(organization: Organization): Organization
4
    fun findById(id: UUID): Organization?
5
    fun update(organization: Organization): Organization
6
}
7

8
// Adapter (Infrastructure)
9
@Component
10
class OrganizationRepositoryAdapter(
11
    private val jdbcRepo: OrganizationJdbcRepository
12
) : OrganizationRepositoryPort {
13
    override fun save(organization: Organization): Organization {
14
        val entity = organization.toDatabaseEntity()
15
        val saved = jdbcRepo.save(entity)
16
        return saved.toDomainModel()
17
    }
18
}

1
Request → Cache → Metrics → Database

1
// Base Port
2
interface ChainablePort<T> {
3
    fun setDelegate(delegate: T)
4
}
5

6
// Concrete Port
7
interface OrganizationRepositoryPort : ChainablePort<OrganizationRepositoryPort> {
8
    fun findById(id: UUID): Organization?
9
}
10

11
// Cache Decorator
12
@Component
13
class OrganizationCacheAdapter(
14
    private val redisTemplate: RedisTemplate<String, Organization>
15
) : OrganizationRepositoryPort {
16
    private lateinit var delegate: OrganizationRepositoryPort
17

18
    override fun setDelegate(delegate: OrganizationRepositoryPort) {
19
        this.delegate = delegate
20
    }
21

22
    override fun findById(id: UUID): Organization? {
23
        val cacheKey = "org:$id"
24

25
        // Try cache first
26
        return redisTemplate.opsForValue().get(cacheKey)
27
            ?: delegate.findById(id)?.also { org ->
28
                // Cache miss → delegate → cache result
29
                redisTemplate.opsForValue().set(cacheKey, org)
30
            }
31
    }
32
}
33

34
// Metrics Decorator
35
@Component
36
class OrganizationMetricsAdapter(
37
    private val meterRegistry: MeterRegistry
38
) : OrganizationRepositoryPort {
39
    private lateinit var delegate: OrganizationRepositoryPort
40

41
    override fun setDelegate(delegate: OrganizationRepositoryPort) {
42
        this.delegate = delegate
43
    }
44

45
    override fun findById(id: UUID): Organization? {
46
        val sample = Timer.start(meterRegistry)
47
        return try {
48
            delegate.findById(id)
49
        } finally {
50
            sample.stop(meterRegistry.timer("repository.findById.duration",
51
                Tags.of("entity", "organization")))
52
        }
53
    }
54
}
55

56
// Wiring (Bootstrap)
57
@Configuration
58
class UseCaseConfig {
59
    @Bean
60
    fun organizationRepository(
61
        jdbc: OrganizationJdbcAdapter,
62
        cache: OrganizationCacheAdapter,
63
        metrics: OrganizationMetricsAdapter
64
    ): OrganizationRepositoryPort {
65
        // Chain: Request → Cache → Metrics → JDBC
66
        metrics.setDelegate(jdbc)
67
        cache.setDelegate(metrics)
68
        return cache
69
    }
70
}

1
Controller
2
    ↓
3
Cache (checks Redis)
4
    ↓ (miss)
5
Metrics (records timing)
6
    ↓
7
JDBC (queries database)
8
    ↑ (returns Organization)
9
Metrics (records timing)
10
    ↑
11
Cache (stores in Redis)
12
    ↑
13
Controller

1
USE CASE (synchronous, one local TX):
2
    Transaction {
3
        repo.save(aggregate)
4
        outbox.save(factory.create(...))   ← same TX, atomic
5
    }                                       ← commit OR rollback both
6

7
DISPATCHER (asynchronous, separate process / scheduled tick):
8
    ShedLock(name=outbox-${app}) {
9
        claim batch (PENDING || stale IN_FLIGHT)  ← atomic UPDATE → IN_FLIGHT
10
        for each: publish via MessagePublisherPort
11
            ok   → status=PUBLISHED
12
            err  → attempts++, status=PENDING, next_attempt_at = now+backoff
13
            err & attempts>=max → status=FAILED
14
    }

1
data class OutboxMessage<T>(
2
    val id: UUID,
3
    val origin: String,           // spring.application.name of producer
4
    val routingKey: String?,
5
    val topic: String,
6
    val key: String?,             // aggregate id (Kafka partition key)
7
    val message: T,               // EventMessage<T> serialized as String at rest
8
    val status: OutboxStatus = OutboxStatus.PENDING,
9
    val attempts: Int = 0,
10
    val error: String? = null,
11
    val occurredAt: Instant,       // set by the caller (inject Clock; no now() in domain)
12
    val nextAttemptAt: LocalDateTime? = null,
13
    val publishedAt: LocalDateTime? = null,
14
    val claimedAt: LocalDateTime? = null,    // claim-based dispatch
15
    val claimedBy: String? = null,           // instanceId = appName@pid
16
)
17

18
enum class OutboxStatus { PENDING, IN_FLIGHT, PUBLISHED, FAILED }

1
class CreateOrganizationUseCase(
2
    private val transaction: TransactionPort,
3
    private val organizations: OrganizationRepositoryPort,
4
    private val outbox: OutboxRepositoryPort,
5
    private val events: OutboxEventFactory,
6
) : CreateOrganizationPort {
7

8
    override fun execute(command: CreateOrganizationCommand): Organization =
9
        transaction.run {
10
            val org = organizations.save(command.toOrganization())
11
            outbox.save(events.create(
12
                topic = "platform.organizations",
13
                traceId = command.traceId,
14
                aggregate = org.id.toString(),
15
                eventName = "OrganizationCreated",
16
                eventType = EventTypes.EVENT,
17
                payload = OrganizationCreatedPayload.from(org),
18
            ))
19
            org
20
        }
21
}

1
@Component
2
class OutboxScheduler(private val sendOutboxMessages: SendOutboxMessagesPort) {
3

4
    @Scheduled(fixedDelayString = "\${outbox.task.fixed-delay:5000}")
5
    @SchedulerLock(
6
        name = "\${outbox.task.lock-name:outbox-\${spring.application.name:unknown}}",
7
        lockAtMostFor = "\${outbox.task.lock-at-most:60000}",
8
        lockAtLeastFor = "\${outbox.task.lock-at-least:10000}",
9
    )
10
    fun tick() = runCatching { sendOutboxMessages.execute() }
11
        .onFailure { log.error("outbox tick failed", it) }
12
}

1
┌──────────────────────────────────────────────────────────┐
2
│  USE CASE (synchronous)                                  │
3
│                                                          │
4
│  Controller / Listener                                   │
5
│    ↓                                                     │
6
│  Transaction {                                           │
7
│    repo.save(aggregate)               ✓                  │
8
│    outbox.save(factory.create(...))   ✓                  │
9
│  } ← atomic; both or neither                             │
10
│    ↓                                                     │
11
│  Return to caller — broker NOT contacted yet             │
12
└──────────────────────────────────────────────────────────┘
13

14
┌──────────────────────────────────────────────────────────┐
15
│  DISPATCHER (asynchronous, ticks every 5s)               │
16
│                                                          │
17
│  ShedLock(outbox-${app}) acquired                        │
18
│    ↓                                                     │
19
│  Atomic claim: PENDING + stale IN_FLIGHT → IN_FLIGHT     │
20
│    ↓                                                     │
21
│  For each row: MessagePublisherPort.publish(...)         │
22
│    ok  → status=PUBLISHED, clear claim                   │
23
│    err → attempts++, backoff                              │
24
│          attempts >= max → status=FAILED                  │
25
│    ↓                                                     │
26
│  Lock released                                           │
27
└──────────────────────────────────────────────────────────┘

1
// Use Case depends on abstractions (ports) — outbox-first; no publisher port
2
class CreateOrganizationUseCase(
3
    private val transaction: TransactionPort<Organization>,
4
    private val repository: OrganizationRepositoryPort,
5
    private val outbox: OutboxRepositoryPort,           // SDK
6
    private val events: OutboxEventFactory,             // SDK
7
) : CreateOrganizationPort {
8
    // Use case implementation
9
}
10

11
// Wiring (Bootstrap)
12
@Configuration
13
class UseCaseConfig {
14
    @Bean
15
    fun createOrganizationPort(
16
        transaction: TransactionPort<Organization>,
17
        repository: OrganizationRepositoryPort,
18
        outbox: OutboxRepositoryPort,
19
        events: OutboxEventFactory,
20
    ): CreateOrganizationPort = CreateOrganizationUseCase(transaction, repository, outbox, events)
21
}