In this guide (4 items)

Claude Code Guide — Domain, Ports & Use Cases

Project-agnostic. Part of the Claude Code Guide suite. Covers: Step 1 (domain model), Step 2 (inbound + outbound ports, command), Step 3 (use case).

Replace com.example.platform / platform-service placeholders with your project’s actual package and service name when applying patterns.

Companion files:

claude-code-guide.md — index + required reading order.
ccg-adapters-and-wiring.md — Step 4 (REST/JDBC/Kafka adapters) + Step 5 (bootstrap wiring).
ccg-bugfix-and-testing.md — bug-fix workflow + test patterns.
ccg-reference.md — common tasks, anti-patterns, checklists.

🎯 When Adding a New Feature

Follow these steps in order. Steps 1-3 (this file) define the inside (domain + application). Steps 4-5 (next file) define the outside (adapters + wiring).

Step 1: Define Domain Model (if needed)

Location: domain/src/main/kotlin/com/example/platform/domain/

1
// Example: domain/Invoice.kt — regular class (NOT data class). data class would
2
// auto-expose copy(status = PAID) and let callers skip markAsPaid's CANCELLED guard.
3
class Invoice private constructor(
4
    val id: UUID,
5
    val organizationId: UUID,
6
    val amount: Money,
7
    val status: InvoiceStatus,
8
    val issuedAt: Instant,
9
    val dueDate: LocalDate,
10
    val version: Long,
11
) {
12
    init {
13
        require(amount.isPositive()) { "amount must be positive" }
14
        require(version >= 0)        { "version must be non-negative" }
15
    }
16

17
    fun markAsPaid(): Invoice {
18
        require(status != InvoiceStatus.CANCELLED) { "Cannot pay cancelled invoice" }
19
        return Invoice(id, organizationId, amount, InvoiceStatus.PAID, issuedAt, dueDate, version + 1)
20
    }
21

22
    fun cancel(): Invoice {
23
        require(status == InvoiceStatus.PENDING) { "Only pending invoices can be cancelled" }
24
        return Invoice(id, organizationId, amount, InvoiceStatus.CANCELLED, issuedAt, dueDate, version + 1)
25
    }
26

27
    fun isOverdue(currentDate: LocalDate): Boolean =
28
        status == InvoiceStatus.PENDING && currentDate.isAfter(dueDate)
29

30
    companion object {
31
        fun issue(id: UUID, organizationId: UUID, amount: Money, dueDate: LocalDate, clock: Clock): Invoice =
32
            Invoice(id, organizationId, amount, InvoiceStatus.PENDING, clock.instant(), dueDate, version = 0)
33

34
        // For persistence rehydration only — JDBC/JPA mappers call this.
35
        fun rehydrate(
36
            id: UUID, organizationId: UUID, amount: Money, status: InvoiceStatus,
37
            issuedAt: Instant, dueDate: LocalDate, version: Long,
38
        ): Invoice = Invoice(id, organizationId, amount, status, issuedAt, dueDate, version)
39
    }
40
}
41

42
enum class InvoiceStatus { PENDING, PAID, CANCELLED }

Java equivalent:

1
public final class Invoice {
2
    private final UUID id;
3
    private final UUID organizationId;
4
    private final Money amount;
5
    private final InvoiceStatus status;
6
    private final Instant issuedAt;
7
    private final LocalDate dueDate;
8
    private final long version;
9

10
    private Invoice(UUID id, UUID organizationId, Money amount, InvoiceStatus status,
11
                    Instant issuedAt, LocalDate dueDate, long version) {
12
        if (!amount.isPositive()) throw new IllegalArgumentException("amount must be positive");
13
        if (version < 0)          throw new IllegalArgumentException("version must be non-negative");
14
        this.id = id;
15
        this.organizationId = organizationId;
16
        this.amount = amount;
17
        this.status = status;
18
        this.issuedAt = issuedAt;
19
        this.dueDate = dueDate;
20
        this.version = version;
21
    }
22

23
    public static Invoice issue(UUID id, UUID organizationId, Money amount,
24
                                LocalDate dueDate, Clock clock) {
25
        return new Invoice(id, organizationId, amount, InvoiceStatus.PENDING,
26
                           clock.instant(), dueDate, 0L);
27
    }
28

29
    public static Invoice rehydrate(UUID id, UUID organizationId, Money amount,
30
                                    InvoiceStatus status, Instant issuedAt,
31
                                    LocalDate dueDate, long version) {
32
        return new Invoice(id, organizationId, amount, status, issuedAt, dueDate, version);
33
    }
34

35
    public Invoice markAsPaid() {
36
        if (status == InvoiceStatus.CANCELLED) {
37
            throw new IllegalStateException("Cannot pay cancelled invoice");
38
        }
39
        return new Invoice(id, organizationId, amount, InvoiceStatus.PAID, issuedAt, dueDate, version + 1);
40
    }
41

42
    public Invoice cancel() {
43
        if (status != InvoiceStatus.PENDING) {
44
            throw new IllegalStateException("Only pending invoices can be cancelled");
45
        }
46
        return new Invoice(id, organizationId, amount, InvoiceStatus.CANCELLED, issuedAt, dueDate, version + 1);
47
    }
48

49
    public boolean isOverdue(LocalDate currentDate) {
50
        return status == InvoiceStatus.PENDING && currentDate.isAfter(dueDate);
51
    }
52

53
    // Getters only — no setters.
54
    public UUID getId()             { return id; }
55
    public UUID getOrganizationId() { return organizationId; }
56
    public Money getAmount()        { return amount; }
57
    public InvoiceStatus getStatus(){ return status; }
58
    public Instant getIssuedAt()    { return issuedAt; }
59
    public LocalDate getDueDate()   { return dueDate; }
60
    public long getVersion()        { return version; }
61
}
62

63
public enum InvoiceStatus { PENDING, PAID, CANCELLED }

See java-code-style.md for Java-specific domain modeling patterns.

Rules:

No Spring annotations
No @Entity or @Table
Use data class (Kotlin) ONLY for value objects with no invariants; entities/aggregates with behavior or guards use a regular class with private constructor + factory (a data class would auto-expose copy() and let callers skip those guards). In Java, an immutable class with getters + private constructor + factory.
Immutable by default (val in Kotlin, final fields in Java)
Business logic here, not in use cases

Step 2: Define Ports in Application Layer

2.1 Inbound Port (Use Case Interface)

Location: application/src/main/kotlin/com/example/platform/port/inbound/

1
fun interface CreateInvoicePort : ChainablePort<CreateInvoicePort> {
2
    fun execute(command: CreateInvoiceCommand): Invoice
3
}

Java equivalent:

1
@FunctionalInterface
2
public interface CreateInvoicePort extends ChainablePort<CreateInvoicePort> {
3
    Invoice execute(CreateInvoiceCommand command);
4
}

Use fun interface (Kotlin) or @FunctionalInterface (Java) for single-method contracts. This enables lambda syntax. Ports extend ChainablePort<T> to support the chain of responsibility pattern (see hexagonal-architecture.md).

2.2 Command (if using CQRS)

Location: application/src/main/kotlin/com/example/platform/command/

1
data class CreateInvoiceCommand(
2
    val organizationId: UUID,
3
    val amount: BigDecimal,
4
    val currency: String,
5
    val dueDate: LocalDate,
6
    val traceId: String
7
)

Java equivalent:

1
public record CreateInvoiceCommand(
2
    UUID organizationId,
3
    BigDecimal amount,
4
    String currency,
5
    LocalDate dueDate,
6
    String traceId
7
) {}

2.3 Outbound Ports (Repository only — no publisher port)

Location: application/src/main/kotlin/com/example/platform/port/outbound/

1
interface InvoiceRepositoryPort {
2
    fun save(invoice: Invoice): Invoice
3
    fun findById(id: UUID): Invoice?
4
    fun findByOrganizationId(organizationId: UUID): List<Invoice>
5
}
6

7
// Outbox port: provided by codehuntersio-sdk-event-messaging — NOT redeclared per service.
8
// Inject `OutboxRepositoryPort` + `OutboxEventFactory` directly from the SDK.
9
// See messaging.md §4.3 + §4.3.1.

Java equivalent:

1
public interface InvoiceRepositoryPort {
2
    Invoice save(Invoice invoice);
3
    Optional<Invoice> findById(UUID id);
4
    List<Invoice> findByOrganizationId(UUID organizationId);
5
}
6

7
// No InvoicePublisherPort. Use cases publish via OutboxRepositoryPort from the SDK.

2.3.1 Why no publisher port in use cases

A domain-specific XxxPublisherPort (e.g. InvoicePublisherPort) is an attractive nuisance: it invites the use case to call the broker — directly or via a “publish first, outbox on failure” callback. Both are dual-write. The use case has only one outbound dependency for event emission: OutboxRepositoryPort. The SDK dispatcher (SendOutboxMessagesUseCase + MessagePublisherPort) handles broker I/O on the other side of a local TX boundary. See messaging.md §4 and ArchUnit rules in hexagonal-architecture.md §ArchUnit.

Naming. Repositories follow <Entity>RepositoryPort. The single canonical messaging port is MessagePublisherPort (provided by the SDK; consumed only by the dispatcher) — see ports-and-commands.md.

Step 3: Implement Use Case

Location: application/src/main/kotlin/com/example/platform/usecase/

1
class CreateInvoiceUseCase(
2
    private val transaction: TransactionPort<Invoice>,
3
    private val invoiceRepository: InvoiceRepositoryPort,
4
    private val outboxRepository: OutboxRepositoryPort,    // SDK port
5
    private val outboxEventFactory: OutboxEventFactory,    // SDK factory
6
    private val clock: Clock,
7
) : CreateInvoicePort {
8

9
    override fun execute(command: CreateInvoiceCommand): Invoice =
10
        transaction.run {
11
            val invoice = command.toInvoice(clock)
12
            val saved = invoiceRepository.save(invoice)
13
            outboxRepository.save(outboxEventFactory.create(
14
                topic = "platform.invoices",
15
                traceId = command.traceId,
16
                aggregate = saved.id.toString(),
17
                eventName = "InvoiceCreated",
18
                eventType = EventTypes.EVENT,
19
                payload = InvoiceCreatedPayload.from(saved),
20
            ))
21
            saved
22
        }
23
}

Java equivalent:

1
public class CreateInvoiceUseCase implements CreateInvoicePort {
2

3
    private final TransactionPort<Invoice> transaction;
4
    private final InvoiceRepositoryPort invoiceRepository;
5
    private final OutboxRepositoryPort outboxRepository;
6
    private final OutboxEventFactory outboxEventFactory;
7
    private final Clock clock;
8

9
    public CreateInvoiceUseCase(TransactionPort<Invoice> transaction,
10
                                InvoiceRepositoryPort invoiceRepository,
11
                                OutboxRepositoryPort outboxRepository,
12
                                OutboxEventFactory outboxEventFactory,
13
                                Clock clock) {
14
        this.transaction = transaction;
15
        this.invoiceRepository = invoiceRepository;
16
        this.outboxRepository = outboxRepository;
17
        this.outboxEventFactory = outboxEventFactory;
18
        this.clock = clock;
19
    }
20

21
    @Override
22
    public Invoice execute(CreateInvoiceCommand command) {
23
        return transaction.run(() -> {
24
            Invoice invoice = CommandMapper.toInvoice(command, clock);
25
            Invoice saved = invoiceRepository.save(invoice);
26
            outboxRepository.save(outboxEventFactory.create(
27
                "platform.invoices",
28
                command.traceId(),
29
                saved.getId().toString(),
30
                "InvoiceCreated",
31
                EventTypes.EVENT,
32
                InvoiceCreatedPayload.from(saved)
33
            ));
34
            return saved;
35
        });
36
    }
37
}

Rules:

No Spring annotations (@Service, @Transactional).
Use TransactionPort<R> for transactional boundaries.
Publish events ONLY via OutboxRepositoryPort.save(...) — the SDK dispatcher publishes asynchronously. No MessagePublisherPort, no XxxPublisherPort, no callback.
Use case keeps both writes (business + outbox) in the same local transaction; either both commit or both roll back.
Keep thin — orchestration only, business logic in domain.
See messaging.md for envelope, factory, dispatcher and pre-merge checklist.

Mapper (Command → Domain)

Location: application/src/main/kotlin/com/example/platform/mapper/

1
fun CreateInvoiceCommand.toInvoice(clock: Clock): Invoice = Invoice.issue(
2
    id = UUID.randomUUID(),
3
    organizationId = this.organizationId,
4
    amount = Money(this.amount, Currency.getInstance(this.currency)),
5
    dueDate = this.dueDate,
6
    clock = clock,
7
)

Use extension functions for mapping (Kotlin).

Java equivalent:

1
public final class CommandMapper {
2

3
    private CommandMapper() {
4
        // Utility class - prevent instantiation
5
    }
6

7
    public static Invoice toInvoice(CreateInvoiceCommand command, Clock clock) {
8
        return Invoice.issue(
9
            UUID.randomUUID(),
10
            command.organizationId(),
11
            new Money(command.amount(), Currency.getInstance(command.currency())),
12
            command.dueDate(),
13
            clock
14
        );
15
    }
16
}

In Java, use static methods in a utility class instead of Kotlin extension functions. See java-code-style.md for additional mapper patterns.