2026-03-28•22 min read•Architecture · Spring Boot · Kotlin

Hexagonal architecture with Spring Boot and Kotlin — a certificate service built from swappable modules

Ports and adapters in Kotlin — a Spring Boot certificate issuance engine where the core is framework-free and every adapter, and every certificate type, is a swappable module.

Prashant Chaturvedi

Engineer

Spring Boot makes it easy to start a service and easy to regret it a year later. Controllers grow business rules, JPA entities quietly become the domain model, and the one use case that actually matters cannot run without a database and two HTTP mocks. This article builds a government certificate issuance engine in Kotlin using hexagonal architecture — ports and adapters — where every adapter, and every certificate type, lives in its own Gradle module that you can swap without touching the core.

You should be comfortable with Spring Boot and Gradle; no prior exposure to ports and adapters is assumed. By the end you should be able to answer two questions for any new concern — does this belong in the domain, a port, or an adapter? and which module do I swap to change this behavior? Examples target Spring Boot 3.5.x, Kotlin 2.1.x, and JVM 21 with Gradle Kotlin DSL; treat versions as representative rather than prescriptive. Every code block in this article belongs to the same multi-module build — it compiles, the use-case test passes, and the architecture rule runs green. Infrastructure details like retries, security, and migrations are noted where they matter rather than built out in full.

What the engine has to survive

The running example is an income certificate — one of the most-issued documents on Indian service-delivery platforms like e-District. A citizen (or an assisted-service operator) applies, the engine checks the application against the rules for that certificate type, and records a decision that can be explained months later. Behind that one flow sits a list of pressures that punish naive layering:

Multiple entry points. A citizen-facing REST API; applications arriving from Common Service Centres over a message queue; a scheduled job that escalates applications breaching their delivery deadline.
Legally binding timelines. Right to Service legislation in several states mandates delivery within a fixed number of days, so SLA tracking is a domain concern, not a cron afterthought.
Several external systems. A citizen registry for demographics, a relational database for applications, and an event broker for downstream notifications.
Many certificate types. Income, domicile, caste, birth — each with its own rules, and new ones arrive as policy, not as rewrites.
Audit obligations. “Why was this application rejected, under which rules, at what time?” is a product requirement — the answer may be shown to the applicant.

A conventional Spring Boot service drifts into a dependency chain like this:

1
Controller -> Service -> JPA Repository -> PostgreSQL
2
                       -> HTTP Client   -> Citizen Registry

The acceptance decision is now entangled with controllers, entities, REST clients, and framework annotations. Swapping the registry client for a stub during local development, or adding a second certificate type, means editing code that was supposed to be stable. Testing the decision means Spring context startup and a database for what is, at heart, a rule evaluation over a citizen’s attributes.

Hexagonal architecture reverses the important dependency direction: adapters depend on the core; the core describes the capabilities it needs and knows nothing about the technologies that provide them.

The idea behind ports and adapters

Alistair Cockburn introduced the pattern in a 2005 technical report — his own name for it is ports and adapters — with a practical goal: an application that can work without either a UI or a database, drivable equally by a human user, an automated regression suite, a batch script, or another program, and testable without its eventual runtime infrastructure. “Hexagonal” is just the shape he drew, and he is explicit that the number six means nothing — the hexagon simply gives the application room for as many ports as it needs, unconstrained by a one-dimensional layer stack.

The drawing is deliberately asymmetric, and this is the part most summaries skip. On one side sit driving actors — the user, the test harness, the scheduler, the upstream producer — anything that starts the conversation. On the other side sit driven actors — the database, the registry, the broker — anything the application calls. Ports face both directions: inbound ports declare what the application offers its drivers; outbound ports declare what it needs from the driven side. You will also meet Cockburn’s vocabulary — primary and secondary actors — and the driving/driven pair; they map to inbound and outbound respectively.

The edges labeled “adapter” are literal: an adapter is the piece that converts a driver’s protocol into an inbound-port call, or an outbound-port call into a driven technology’s protocol. Notice the test harness on the driving side — Cockburn’s testability goal means a test is just another adapter, which is why the test strategy later in this article falls out of the design rather than fighting it.

The mechanism that makes the driven side replaceable is dependency inversion applied at the module boundary. The outbound port is an interface owned by the core — written in the use case’s vocabulary — and the adapter implements it. Both sides point inward:

That is the entire trick. The persistence adapter depends on a core interface, so PostgreSQL is a detail of the adapter module; the core could run against a stub or a different engine without recompilation. Contrast with conventional layering, where Service → Repository → PostgreSQL points every dependency at the database — the port flips the arrow by making the consumer own the contract.

The same dependency rule appears under other names — Jeffrey Palermo’s Onion Architecture and Robert C. Martin’s Clean Architecture share the “dependencies point inward” core with different ring vocabularies — so if you have met one, you have met the idea. What the pattern does not prescribe matters as much: nothing about modules, bounded contexts, or deployment topology. The Gradle layout in this article is one way to enforce the rule at compile time; the rule itself is the only non-negotiable part.

Ports and adapters, concretely

Applied to this engine, the four roles look like this:

The domain models business meaning and invariants — applications, certificate types, citizen facts, decisions, reasons. It imports no Spring MVC, JPA, Kafka, or database classes.
An inbound port is a use case the system offers: SubmitCertificateApplication, IssueCertificate, GetApplicationStatus. A REST controller and a Kafka consumer can invoke the same one.
An outbound port is a capability the use case needs from outside: LoadCitizenProfilePort, SaveCertificateApplicationPort, CertificateEventPublisherPort. The name describes a capability, never a technology — PostgresApplicationRepository is an adapter, not a port.
An adapter translates between a technology and a port: a Spring MVC controller inbound, a JPA persistence adapter or WebClient-based registry client outbound.

Follow the flow from the portals inward: callers reach the core only through inbound ports, and the core reaches the world only through outbound ports. The hexagon itself is a metaphor — nothing requires six sides. What matters is that the core can be driven by any adapter and can obtain any capability through a replaceable adapter.

Carving the build into modules

You can practice ports and adapters in a single package, but the discipline lasts longer when the build file enforces it — and module boundaries are what make adapters physically swappable. A Gradle multi-project build gives each boundary a home:

1
certificate-engine/
2
├── domain/
3
├── application/
4
├── policy-income-certificate/
5
├── adapter-in-rest/
6
├── adapter-in-messaging/
7
├── adapter-in-batch/
8
├── adapter-out-persistence/
9
├── adapter-out-registry/
10
├── adapter-out-registry-stub/
11
├── adapter-out-events/
12
├── bootstrap/
13
├── build.gradle.kts
14
└── settings.gradle.kts

The module names carry the role, not the language — everything here is Kotlin. Two module families deserve a second look: policy-income-certificate is a functionality module — adding a certificate type means adding a module, not editing the core — and adapter-out-registry-stub is the swap partner for adapter-out-registry, standing in for the citizen registry during local development.

1
rootProject.name = "certificate-engine"
2

3
include(
4
    "domain",
5
    "application",
6
    "policy-income-certificate",
7
    "adapter-in-rest",
8
    "adapter-in-messaging",
9
    "adapter-in-batch",
10
    "adapter-out-persistence",
11
    "adapter-out-registry",
12
    "adapter-out-registry-stub",
13
    "adapter-out-events",
14
    "bootstrap",
15
)

The dependency rule is the entire architecture in one line: dependencies point toward the core, and the core never depends on an adapter.

Read the arrows as “is depended upon by”: adapter-out-persistence depends on application so it can implement the outbound ports, but application has no compile-time knowledge that PostgreSQL or JPA exists. Gradle makes this literal — the module simply has no dependency that could supply a JPA import. adapter-out-registry and adapter-out-registry-stub implement the same outbound port, which is what makes them interchangeable.

The root build file declares plugin versions once; each subproject applies what it needs. There is no Spring dependency-management plugin: modules import the Spring Boot BOM through Gradle’s native platform(), which keeps one mechanism consistent across the build:

1
plugins {
2
    kotlin("jvm") version "2.1.21" apply false
3
    kotlin("plugin.spring") version "2.1.21" apply false
4
    kotlin("plugin.jpa") version "2.1.21" apply false
5
    id("org.springframework.boot") version "3.5.0" apply false
6
}
7

8
allprojects {
9
    group = "in.o612.eng.blogs"
10
    version = "0.1.0-SNAPSHOT"
11
    repositories { mavenCentral() }
12
}

Two module build files show the pattern everything else follows. The application module has a single dependency — the domain — and its only framework is the JDK:

1
plugins {
2
    kotlin("jvm")
3
}
4

5
kotlin {
6
    jvmToolchain(21)
7
}
8

9
dependencies {
10
    api(project(":domain"))
11

12
    testImplementation(platform("org.springframework.boot:spring-boot-dependencies:3.5.0"))
13
    testImplementation("org.junit.jupiter:junit-jupiter")
14
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
15
}
16

17
tasks.test {
18
    useJUnitPlatform()
19
}

An outbound adapter applies the Kotlin Spring and JPA plugins, depends on application for the ports it implements, and pulls in its own infrastructure stack:

1
plugins {
2
    kotlin("jvm")
3
    kotlin("plugin.spring")
4
    kotlin("plugin.jpa")
5
}
6

7
kotlin {
8
    jvmToolchain(21)
9
}
10

11
dependencies {
12
    implementation(project(":application"))
13
    implementation(platform("org.springframework.boot:spring-boot-dependencies:3.5.0"))
14
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
15
    runtimeOnly("org.postgresql:postgresql")
16
}

The kotlin("plugin.jpa") plugin generates the no-arg constructor JPA requires for entities, and kotlin("plugin.spring") opens classes that Spring proxies — both confined to the adapter module where they belong. The remaining adapters follow the same shape: depend on application, add the stack they translate.

The domain module knows nothing about Spring

domain holds the business model. Data classes and a value class carry most of it:

1
package `in`.o612.eng.blogs.certificates.domain
2

3
@JvmInline
4
value class ServiceCode(val value: String) {
5
    init {
6
        require(value.isNotBlank()) { "Service code must not be blank" }
7
    }
8
}

1
package `in`.o612.eng.blogs.certificates.domain
2

3
data class CitizenProfile(
4
    val citizenId: String,
5
    val resident: Boolean,
6
    val residenceYears: Int,
7
    val ageYears: Int,
8
    val annualHouseholdIncome: Long,
9
)

1
package `in`.o612.eng.blogs.certificates.domain
2

3
import java.time.Instant
4
import java.util.UUID
5

6
data class CertificateApplication(
7
    val applicationId: UUID,
8
    val serviceCode: ServiceCode,
9
    val citizenId: String,
10
    val status: ApplicationStatus,
11
    val reasons: List<String>,
12
    val policyVersion: String,
13
    val appliedAt: Instant,
14
)

ServiceCode is an inline value class — it validates at construction and costs no allocation at runtime. ApplicationStatus is an enum of ACCEPTED, REJECTED, and MANUAL_REVIEW; the third value exists because “the registry disagrees with the application” must never silently become REJECTED. Two plain exceptions round out the vocabulary:

1
package `in`.o612.eng.blogs.certificates.domain
2

3
class CitizenNotFoundException(citizenId: String) : RuntimeException("Citizen not found: $citizenId")
4

5
class UnknownServiceException(serviceCode: ServiceCode) : RuntimeException("Unknown service: ${serviceCode.value}")

One package detail is worth knowing because it appears in every Kotlin file in this project: in is a Kotlin keyword, so the in.o612.eng.blogs package escapes it with backticks in package and import statements. The compiled package name is still in.o612.eng.blogs.

CertificateApplication carries policyVersion: a decision you cannot trace back to the rules that produced it is not auditable, so the version is part of the model, not metadata added later.

Two remaining domain types define the seams everything else plugs into. ApplicationFacts gathers the evidence a policy evaluates — the citizen’s registry profile, what they declared, and whether a duplicate application is already in progress:

1
package `in`.o612.eng.blogs.certificates.domain
2

3
data class ApplicationFacts(
4
    val citizen: CitizenProfile,
5
    val declaredAnnualIncome: Long,
6
    val pendingApplicationExists: Boolean,
7
)

And ServicePolicy is the contract each certificate-type module implements — including slaDays, because the legal delivery window differs per service:

1
package `in`.o612.eng.blogs.certificates.domain
2

3
interface ServicePolicy {
4
    val serviceCode: ServiceCode
5
    val policyVersion: String
6
    val slaDays: Int
7

8
    fun evaluate(facts: ApplicationFacts): PolicyOutcome
9
}
10

11
data class PolicyOutcome(
12
    val status: ApplicationStatus,
13
    val reasons: List<String>,
14
)

The engine also emits domain events. A sealed interface keeps the set closed and lets adapters and consumers handle each event type exhaustively:

1
package `in`.o612.eng.blogs.certificates.domain
2

3
sealed interface CertificateEvent {
4
    val application: CertificateApplication
5
}
6

7
data class ApplicationDecided(
8
    override val application: CertificateApplication,
9
) : CertificateEvent
10

11
data class ApplicationEscalated(
12
    override val application: CertificateApplication,
13
) : CertificateEvent

ServicePolicy sits in the domain because it is business vocabulary: “a certificate service can evaluate an application and explain itself.” The concrete rules live in certificate-type modules that plug into this contract — the engine works with every ServicePolicy on the classpath and knows none of them by name.

Ports describe capabilities, not technologies

application defines the use cases and the capabilities they need. The inbound port is what any caller — the citizen API, the CSC channel, a future staff portal — invokes:

1
package `in`.o612.eng.blogs.certificates.application.port.inbound
2

3
import `in`.o612.eng.blogs.certificates.domain.CertificateApplication
4
import `in`.o612.eng.blogs.certificates.domain.ServiceCode
5

6
interface SubmitCertificateApplication {
7
    fun submit(command: SubmitApplicationCommand): CertificateApplication
8

9
    data class SubmitApplicationCommand(
10
        val serviceCode: ServiceCode,
11
        val citizenId: String,
12
        val declaredAnnualIncome: Long,
13
    )
14
}

The command is a domain-typed input, not a request DTO — declaredAnnualIncome is the applicant’s own declaration, which the policy will compare against registry data. The outbound ports are capabilities named after what the use case needs, declared as fun interface so tests and stubs can satisfy them with a lambda:

1
package `in`.o612.eng.blogs.certificates.application.port.outbound
2

3
import `in`.o612.eng.blogs.certificates.domain.CitizenProfile
4

5
fun interface LoadCitizenProfilePort {
6
    fun loadByCitizenId(citizenId: String): CitizenProfile
7
}

1
package `in`.o612.eng.blogs.certificates.application.port.outbound
2

3
import `in`.o612.eng.blogs.certificates.domain.CertificateApplication
4

5
fun interface SaveCertificateApplicationPort {
6
    fun save(application: CertificateApplication)
7
}

1
package `in`.o612.eng.blogs.certificates.application.port.outbound
2

3
import `in`.o612.eng.blogs.certificates.domain.ServiceCode
4

5
fun interface ExistsPendingApplicationPort {
6
    fun existsPendingFor(serviceCode: ServiceCode, citizenId: String): Boolean
7
}

1
package `in`.o612.eng.blogs.certificates.application.port.outbound
2

3
import `in`.o612.eng.blogs.certificates.domain.CertificateEvent
4

5
fun interface CertificateEventPublisherPort {
6
    fun publish(event: CertificateEvent)
7
}

Nothing in these signatures says PostgreSQL, REST, or Kafka. That is the point — and also the naming test: if a port’s name contains a technology, it is an adapter wearing the wrong clothes.

The use case orchestrates; the domain decides

The application service is the seam between the two. It gathers the facts through ports, hands them to whichever policy module owns the service, and records the outcome — again through ports:

1
package `in`.o612.eng.blogs.certificates.application
2

3
import `in`.o612.eng.blogs.certificates.application.port.inbound.SubmitCertificateApplication
4
import `in`.o612.eng.blogs.certificates.application.port.inbound.SubmitCertificateApplication.SubmitApplicationCommand
5
import `in`.o612.eng.blogs.certificates.application.port.outbound.CertificateEventPublisherPort
6
import `in`.o612.eng.blogs.certificates.application.port.outbound.ExistsPendingApplicationPort
7
import `in`.o612.eng.blogs.certificates.application.port.outbound.LoadCitizenProfilePort
8
import `in`.o612.eng.blogs.certificates.application.port.outbound.SaveCertificateApplicationPort
9
import `in`.o612.eng.blogs.certificates.domain.ApplicationDecided
10
import `in`.o612.eng.blogs.certificates.domain.ApplicationFacts
11
import `in`.o612.eng.blogs.certificates.domain.CertificateApplication
12
import `in`.o612.eng.blogs.certificates.domain.ServiceCode
13
import `in`.o612.eng.blogs.certificates.domain.ServicePolicy
14
import `in`.o612.eng.blogs.certificates.domain.UnknownServiceException
15
import java.time.Clock
16
import java.time.Instant
17
import java.util.UUID
18

19
class CertificateApplicationService(
20
    private val citizenProfiles: LoadCitizenProfilePort,
21
    private val applications: SaveCertificateApplicationPort,
22
    private val pendingApplications: ExistsPendingApplicationPort,
23
    private val events: CertificateEventPublisherPort,
24
    policies: List<ServicePolicy>,
25
    private val clock: Clock,
26
) : SubmitCertificateApplication {
27

28
    private val policiesByService: Map<ServiceCode, ServicePolicy> =
29
        policies.associateBy { it.serviceCode }
30

31
    override fun submit(command: SubmitApplicationCommand): CertificateApplication {
32
        val policy = policiesByService[command.serviceCode]
33
            ?: throw UnknownServiceException(command.serviceCode)
34
        val citizen = citizenProfiles.loadByCitizenId(command.citizenId)
35
        val pending = pendingApplications.existsPendingFor(command.serviceCode, command.citizenId)
36
        val outcome = policy.evaluate(
37
            ApplicationFacts(citizen, command.declaredAnnualIncome, pending),
38
        )
39

40
        val application = CertificateApplication(
41
            applicationId = UUID.randomUUID(),
42
            serviceCode = command.serviceCode,
43
            citizenId = command.citizenId,
44
            status = outcome.status,
45
            reasons = outcome.reasons,
46
            policyVersion = policy.policyVersion,
47
            appliedAt = Instant.now(clock),
48
        )
49
        applications.save(application)
50
        events.publish(ApplicationDecided(application))
51
        return application
52
    }
53
}

Read submit top to bottom and you have the whole use case: resolve the service’s policy, load the citizen’s profile, check for a duplicate pending application, evaluate the facts, stamp the decision with the policy version and an injected Clock, persist it, announce it. There is no @Service annotation — the class does not need Spring’s permission to exist.

The List<ServicePolicy> constructor parameter is where the plugin mechanism lives. Spring injects every registered ServicePolicy bean, and the service indexes them by service code. Add a module containing a new ServicePolicy bean and the use case serves a new certificate type — CertificateApplicationService never learns that anything changed.

A functionality module: one certificate type, one module

policy-income-certificate is the first service implementation. The policy is annotation-free Kotlin, and it distinguishes two kinds of failure: hard rejections (non-resident, insufficient residence history, underage, duplicate application) and a reviewable discrepancy — declared income that disagrees with the registry gets MANUAL_REVIEW, because an honest applicant may have had an income change the registry has not caught up with:

1
package `in`.o612.eng.blogs.certificates.policy.income
2

3
import `in`.o612.eng.blogs.certificates.domain.ApplicationFacts
4
import `in`.o612.eng.blogs.certificates.domain.ApplicationStatus
5
import `in`.o612.eng.blogs.certificates.domain.PolicyOutcome
6
import `in`.o612.eng.blogs.certificates.domain.ServiceCode
7
import `in`.o612.eng.blogs.certificates.domain.ServicePolicy
8
import kotlin.math.abs
9

10
class IncomeCertificatePolicy : ServicePolicy {
11

12
    override val serviceCode = ServiceCode("income-certificate")
13
    override val policyVersion = "income-certificate/2026.1"
14
    override val slaDays = 15
15

16
    override fun evaluate(facts: ApplicationFacts): PolicyOutcome {
17
        val rejections = buildList {
18
            if (!facts.citizen.resident) {
19
                add("Applicant is not a resident of the issuing jurisdiction")
20
            }
21
            if (facts.citizen.residenceYears < MIN_RESIDENCE_YEARS) {
22
                add("Minimum $MIN_RESIDENCE_YEARS years of continuous residence required")
23
            }
24
            if (facts.citizen.ageYears < MIN_AGE_YEARS) {
25
                add("Applicant must be at least $MIN_AGE_YEARS years old")
26
            }
27
            if (facts.pendingApplicationExists) {
28
                add("An application for this service is already in progress")
29
            }
30
        }
31
        if (rejections.isNotEmpty()) {
32
            return PolicyOutcome(ApplicationStatus.REJECTED, rejections)
33
        }
34

35
        val incomeMismatch =
36
            abs(facts.declaredAnnualIncome - facts.citizen.annualHouseholdIncome) > INCOME_TOLERANCE
37
        return if (incomeMismatch) {
38
            PolicyOutcome(
39
                ApplicationStatus.MANUAL_REVIEW,
40
                listOf("Declared income does not match registry records"),
41
            )
42
        } else {
43
            PolicyOutcome(ApplicationStatus.ACCEPTED, emptyList())
44
        }
45
    }
46

47
    companion object {
48
        const val MIN_RESIDENCE_YEARS = 3
49
        const val MIN_AGE_YEARS = 18
50
        const val INCOME_TOLERANCE = 10_000L
51
    }
52
}

Returning every violated reason rather than the first is deliberate — a rejection the citizen cannot understand is a grievance waiting to be filed. The module contributes its bean through a small configuration class; because its package sits under in.o612.eng.blogs.certificates, the bootstrap component scan picks it up as soon as the module is on the classpath:

1
package `in`.o612.eng.blogs.certificates.policy.income
2

3
import `in`.o612.eng.blogs.certificates.domain.ServicePolicy
4
import org.springframework.context.annotation.Bean
5
import org.springframework.context.annotation.Configuration
6

7
@Configuration
8
class IncomeCertificateModule {
9

10
    @Bean
11
    fun incomeCertificatePolicy(): ServicePolicy = IncomeCertificatePolicy()
12
}

1
plugins {
2
    kotlin("jvm")
3
}
4

5
kotlin {
6
    jvmToolchain(21)
7
}
8

9
dependencies {
10
    implementation(project(":domain"))
11
    implementation(platform("org.springframework.boot:spring-boot-dependencies:3.5.0"))
12
    implementation("org.springframework:spring-context")
13
}

This is “swap functionality by module” in its concrete form: a second service — a domicile certificate, a caste certificate — is a new directory implementing ServicePolicy, one line in settings.gradle.kts, one line in the bootstrap dependencies. The domain, the use case, and every adapter stay untouched.

Production note — Thresholds like MIN_RESIDENCE_YEARS are constants here for readability; a real platform versions them externally or loads them per policy version. The same applies to money: a Long of whole rupees keeps the example readable, but a Money value type with currency and scale belongs in the domain before amounts start flowing between systems.

Adapters translate; they do not decide

With the core and its policy seam in place, each adapter answers one narrow question: how do I convert my protocol into a port call, or a port call into my protocol?

The REST adapter is a translator

1
package `in`.o612.eng.blogs.certificates.rest
2

3
import `in`.o612.eng.blogs.certificates.application.port.inbound.SubmitCertificateApplication
4
import `in`.o612.eng.blogs.certificates.application.port.inbound.SubmitCertificateApplication.SubmitApplicationCommand
5
import `in`.o612.eng.blogs.certificates.domain.CertificateApplication
6
import `in`.o612.eng.blogs.certificates.domain.ServiceCode
7
import jakarta.validation.Valid
8
import jakarta.validation.constraints.NotBlank
9
import jakarta.validation.constraints.PositiveOrZero
10
import org.springframework.http.HttpStatus
11
import org.springframework.web.bind.annotation.PathVariable
12
import org.springframework.web.bind.annotation.PostMapping
13
import org.springframework.web.bind.annotation.RequestBody
14
import org.springframework.web.bind.annotation.RequestMapping
15
import org.springframework.web.bind.annotation.ResponseStatus
16
import org.springframework.web.bind.annotation.RestController
17

18
@RestController
19
@RequestMapping("/api/v1/services")
20
class CertificateApplicationController(
21
    private val submitApplication: SubmitCertificateApplication,
22
) {
23

24
    @PostMapping("/{serviceCode}/applications")
25
    @ResponseStatus(HttpStatus.CREATED)
26
    fun submit(
27
        @PathVariable serviceCode: String,
28
        @Valid @RequestBody request: SubmitApplicationRequest,
29
    ): CertificateApplicationResponse {
30
        val command = SubmitApplicationCommand(
31
            ServiceCode(serviceCode),
32
            request.citizenId,
33
            request.declaredAnnualIncome,
34
        )
35
        return CertificateApplicationResponse.from(submitApplication.submit(command))
36
    }
37
}
38

39
data class SubmitApplicationRequest(
40
    @field:NotBlank val citizenId: String,
41
    @field:PositiveOrZero val declaredAnnualIncome: Long,
42
)
43

44
data class CertificateApplicationResponse(
45
    val applicationId: String,
46
    val serviceCode: String,
47
    val citizenId: String,
48
    val status: String,
49
    val reasons: List<String>,
50
    val policyVersion: String,
51
    val appliedAt: String,
52
) {
53
    companion object {
54
        fun from(application: CertificateApplication) =
55
            CertificateApplicationResponse(
56
                applicationId = application.applicationId.toString(),
57
                serviceCode = application.serviceCode.value,
58
                citizenId = application.citizenId,
59
                status = application.status.name,
60
                reasons = application.reasons,
61
                policyVersion = application.policyVersion,
62
                appliedAt = application.appliedAt.toString(),
63
            )
64
    }
65
}

The controller does exactly three things: accept HTTP-shaped input, build a use-case command, and map the result back to HTTP. It contains no acceptance logic, which is what makes it safe to review quickly and cheap to change. @field:NotBlank and @field:PositiveOrZero require spring-boot-starter-validation in this module’s dependencies — they turn a missing citizenId or a negative income into a 400 rather than a registry lookup for garbage.

Domain errors get translated at the same boundary:

1
package `in`.o612.eng.blogs.certificates.rest
2

3
import `in`.o612.eng.blogs.certificates.domain.CitizenNotFoundException
4
import `in`.o612.eng.blogs.certificates.domain.UnknownServiceException
5
import org.springframework.http.HttpStatus
6
import org.springframework.web.bind.annotation.ExceptionHandler
7
import org.springframework.web.bind.annotation.ResponseStatus
8
import org.springframework.web.bind.annotation.RestControllerAdvice
9

10
@RestControllerAdvice
11
class ApiExceptionHandler {
12

13
    @ExceptionHandler(CitizenNotFoundException::class)
14
    @ResponseStatus(HttpStatus.NOT_FOUND)
15
    fun citizenNotFound(ex: CitizenNotFoundException) = mapOf("error" to ex.message)
16

17
    @ExceptionHandler(UnknownServiceException::class)
18
    @ResponseStatus(HttpStatus.NOT_FOUND)
19
    fun unknownService(ex: UnknownServiceException) = mapOf("error" to ex.message)
20
}

The domain throws plain exceptions with no HTTP semantics; the adapter owns the status codes. When a second transport arrives, the exceptions keep their meaning and the new adapter picks its own mapping.

A second inbound adapter proves the design

Common Service Centre operators submit applications on behalf of citizens — on a real platform this traffic arrives over a queue, not the public API. The consumer calls the same inbound port:

1
package `in`.o612.eng.blogs.certificates.messaging
2

3
import `in`.o612.eng.blogs.certificates.application.port.inbound.SubmitCertificateApplication
4
import `in`.o612.eng.blogs.certificates.application.port.inbound.SubmitCertificateApplication.SubmitApplicationCommand
5
import `in`.o612.eng.blogs.certificates.domain.ServiceCode
6
import org.springframework.kafka.annotation.KafkaListener
7
import org.springframework.stereotype.Component
8

9
@Component
10
class CscApplicationConsumer(
11
    private val submitApplication: SubmitCertificateApplication,
12
) {
13

14
    @KafkaListener(topics = ["csc.certificate-applications"])
15
    fun onCscApplication(message: CscApplicationMessage) {
16
        submitApplication.submit(
17
            SubmitApplicationCommand(
18
                ServiceCode(message.serviceCode),
19
                message.citizenId,
20
                message.declaredAnnualIncome,
21
            ),
22
        )
23
    }
24
}
25

26
data class CscApplicationMessage(
27
    val serviceCode: String,
28
    val citizenId: String,
29
    val declaredAnnualIncome: Long,
30
)

No acceptance logic was copied to get a second entry point — the consumer, the controller, and a future staff-portal adapter all converge on SubmitCertificateApplication. That is the entire sales pitch for inbound ports in one @KafkaListener method. (Message deserialization is configured in application.yaml; note the spring.json.trusted.packages setting, which restricts which classes the JSON deserializer may instantiate — keep it scoped to the messaging package.)

The batch adapter composes outbound ports directly

Not every adapter must funnel through an inbound port. Right to Service timelines create a different kind of job: scan for applications still pending past their service’s slaDays and escalate them. The job composes outbound ports — it reports on state rather than applying for anything — and because it iterates every registered ServicePolicy, a newly added certificate module gets SLA tracking for free:

1
package `in`.o612.eng.blogs.certificates.application.port.outbound
2

3
import `in`.o612.eng.blogs.certificates.domain.CertificateApplication
4
import `in`.o612.eng.blogs.certificates.domain.ServiceCode
5
import java.time.Instant
6

7
fun interface LoadOverdueApplicationsPort {
8
    fun pendingOlderThan(serviceCode: ServiceCode, cutoff: Instant): List<CertificateApplication>
9
}

1
package `in`.o612.eng.blogs.certificates.batch
2

3
import `in`.o612.eng.blogs.certificates.application.port.outbound.CertificateEventPublisherPort
4
import `in`.o612.eng.blogs.certificates.application.port.outbound.LoadOverdueApplicationsPort
5
import `in`.o612.eng.blogs.certificates.domain.ApplicationEscalated
6
import `in`.o612.eng.blogs.certificates.domain.ServicePolicy
7
import org.springframework.scheduling.annotation.Scheduled
8
import org.springframework.stereotype.Component
9
import java.time.Clock
10
import java.time.Duration
11
import java.time.Instant
12

13
@Component
14
class SlaEscalationJob(
15
    private val overdueApplications: LoadOverdueApplicationsPort,
16
    private val policies: List<ServicePolicy>,
17
    private val events: CertificateEventPublisherPort,
18
    private val clock: Clock,
19
) {
20

21
    @Scheduled(cron = "0 0 6 * * *")
22
    fun escalateOverdueApplications() {
23
        for (policy in policies) {
24
            val cutoff = Instant.now(clock).minus(Duration.ofDays(policy.slaDays.toLong()))
25
            for (application in overdueApplications.pendingOlderThan(policy.serviceCode, cutoff)) {
26
                events.publish(ApplicationEscalated(application))
27
            }
28
        }
29
    }
30
}

The registry adapter owns a protocol

1
package `in`.o612.eng.blogs.certificates.registry
2

3
import `in`.o612.eng.blogs.certificates.application.port.outbound.LoadCitizenProfilePort
4
import `in`.o612.eng.blogs.certificates.domain.CitizenNotFoundException
5
import `in`.o612.eng.blogs.certificates.domain.CitizenProfile
6
import org.springframework.context.annotation.Profile
7
import org.springframework.stereotype.Component
8
import org.springframework.web.reactive.function.client.WebClient
9

10
@Component
11
@Profile("!local-dev")
12
class CitizenRegistryAdapter(
13
    private val webClient: WebClient,
14
) : LoadCitizenProfilePort {
15

16
    override fun loadByCitizenId(citizenId: String): CitizenProfile {
17
        val response = webClient.get()
18
            .uri("/citizens/{id}", citizenId)
19
            .retrieve()
20
            .bodyToMono(CitizenRegistryResponse::class.java)
21
            .block() ?: throw CitizenNotFoundException(citizenId)
22

23
        return CitizenProfile(
24
            citizenId = response.citizenId,
25
            resident = response.resident,
26
            residenceYears = response.residenceYears,
27
            ageYears = response.ageYears,
28
            annualHouseholdIncome = response.annualHouseholdIncome,
29
        )
30
    }
31
}
32

33
data class CitizenRegistryResponse(
34
    val citizenId: String,
35
    val resident: Boolean,
36
    val residenceYears: Int,
37
    val ageYears: Int,
38
    val annualHouseholdIncome: Long,
39
)

The registry’s response shape is a private DTO mapped into CitizenProfile at the boundary — the upstream schema can evolve without touching the domain. The WebClient bean lives in the same module, built from a WebClient.Builder and a base URL supplied through configuration:

1
package `in`.o612.eng.blogs.certificates.registry
2

3
import org.springframework.beans.factory.annotation.Value
4
import org.springframework.context.annotation.Bean
5
import org.springframework.context.annotation.Configuration
6
import org.springframework.web.reactive.function.client.WebClient
7

8
@Configuration
9
class RegistryClientConfiguration {
10

11
    @Bean
12
    fun citizenRegistryWebClient(
13
        builder: WebClient.Builder,
14
        @Value("\${citizen-registry.base-url}") baseUrl: String,
15
    ): WebClient = builder.baseUrl(baseUrl).build()
16
}

The @Profile("!local-dev") on the adapter is half of a swap mechanism — covered in “How modules actually get swapped”.

Production note — .block() keeps the example linear, but a real adapter needs timeouts, retries with backoff, a circuit breaker, correlation IDs, and error translation that distinguishes “citizen does not exist” from “registry unreachable”. Those two outcomes must produce different results: the first can be a rejection input, the second is an operational failure that should surface as MANUAL_REVIEW or an error — never as REJECTED.

The persistence adapter keeps JPA outside the core

The storage model is a separate class on purpose. JPA annotations, table names, and column choices live on the entity; the domain data class stays clean:

1
package `in`.o612.eng.blogs.certificates.persistence
2

3
import `in`.o612.eng.blogs.certificates.domain.CertificateApplication
4
import jakarta.persistence.CollectionTable
5
import jakarta.persistence.Column
6
import jakarta.persistence.ElementCollection
7
import jakarta.persistence.Entity
8
import jakarta.persistence.FetchType
9
import jakarta.persistence.Id
10
import jakarta.persistence.JoinColumn
11
import jakarta.persistence.Table
12
import java.time.Instant
13
import java.util.UUID
14

15
@Entity
16
@Table(name = "certificate_applications")
17
class CertificateApplicationEntity(
18
    @Id
19
    var applicationId: UUID? = null,
20
    var serviceCode: String = "",
21
    var citizenId: String = "",
22
    var status: String = "",
23
    @ElementCollection(fetch = FetchType.EAGER)
24
    @CollectionTable(
25
        name = "certificate_application_reasons",
26
        joinColumns = [JoinColumn(name = "application_id")],
27
    )
28
    @Column(name = "reason")
29
    var reasons: MutableList<String> = mutableListOf(),
30
    var policyVersion: String = "",
31
    var appliedAt: Instant = Instant.now(),
32
) {
33
    companion object {
34
        fun fromDomain(application: CertificateApplication) = CertificateApplicationEntity(
35
            applicationId = application.applicationId,
36
            serviceCode = application.serviceCode.value,
37
            citizenId = application.citizenId,
38
            status = application.status.name,
39
            reasons = application.reasons.toMutableList(),
40
            policyVersion = application.policyVersion,
41
            appliedAt = application.appliedAt,
42
        )
43
    }
44
}

1
package `in`.o612.eng.blogs.certificates.persistence
2

3
import org.springframework.data.jpa.repository.JpaRepository
4
import java.time.Instant
5
import java.util.UUID
6

7
interface SpringDataCertificateApplicationRepository : JpaRepository<CertificateApplicationEntity, UUID> {
8

9
    fun existsByServiceCodeAndCitizenIdAndStatusIn(
10
        serviceCode: String,
11
        citizenId: String,
12
        statuses: Collection<String>,
13
    ): Boolean
14

15
    fun findByServiceCodeAndStatusInAndAppliedAtBefore(
16
        serviceCode: String,
17
        statuses: Collection<String>,
18
        appliedAt: Instant,
19
    ): List<CertificateApplicationEntity>
20
}

The adapter then implements all three outbound ports that persistence serves — saving applications, detecting duplicates, and finding overdue ones:

1
package `in`.o612.eng.blogs.certificates.persistence
2

3
import `in`.o612.eng.blogs.certificates.application.port.outbound.ExistsPendingApplicationPort
4
import `in`.o612.eng.blogs.certificates.application.port.outbound.LoadOverdueApplicationsPort
5
import `in`.o612.eng.blogs.certificates.application.port.outbound.SaveCertificateApplicationPort
6
import `in`.o612.eng.blogs.certificates.domain.ApplicationStatus
7
import `in`.o612.eng.blogs.certificates.domain.CertificateApplication
8
import `in`.o612.eng.blogs.certificates.domain.ServiceCode
9
import org.springframework.stereotype.Component
10
import java.time.Instant
11

12
@Component
13
class CertificateApplicationPersistenceAdapter(
14
    private val repository: SpringDataCertificateApplicationRepository,
15
) : SaveCertificateApplicationPort, ExistsPendingApplicationPort, LoadOverdueApplicationsPort {
16

17
    override fun save(application: CertificateApplication) {
18
        repository.save(CertificateApplicationEntity.fromDomain(application))
19
    }
20

21
    override fun existsPendingFor(serviceCode: ServiceCode, citizenId: String) =
22
        repository.existsByServiceCodeAndCitizenIdAndStatusIn(
23
            serviceCode.value, citizenId, PENDING_STATUSES,
24
        )
25

26
    override fun pendingOlderThan(serviceCode: ServiceCode, cutoff: Instant) =
27
        repository.findByServiceCodeAndStatusInAndAppliedAtBefore(
28
            serviceCode.value, PENDING_STATUSES, cutoff,
29
        ).map { it.toDomain() }
30

31
    companion object {
32
        private val PENDING_STATUSES =
33
            listOf(ApplicationStatus.ACCEPTED.name, ApplicationStatus.MANUAL_REVIEW.name)
34
    }
35
}
36

37
private fun CertificateApplicationEntity.toDomain() = CertificateApplication(
38
    applicationId = applicationId!!,
39
    serviceCode = ServiceCode(serviceCode),
40
    citizenId = citizenId,
41
    status = ApplicationStatus.valueOf(status),
42
    reasons = reasons.toList(),
43
    policyVersion = policyVersion,
44
    appliedAt = appliedAt,
45
)

One adapter implementing three ports is normal — ports are capabilities, and one technology can provide several. “Pending” means ACCEPTED or MANUAL_REVIEW: applications still moving toward issuance, which is exactly the set a duplicate check and an SLA scan should both see.

The events adapter announces outcomes

1
package `in`.o612.eng.blogs.certificates.events
2

3
import `in`.o612.eng.blogs.certificates.application.port.outbound.CertificateEventPublisherPort
4
import `in`.o612.eng.blogs.certificates.domain.ApplicationDecided
5
import `in`.o612.eng.blogs.certificates.domain.ApplicationEscalated
6
import `in`.o612.eng.blogs.certificates.domain.CertificateApplication
7
import `in`.o612.eng.blogs.certificates.domain.CertificateEvent
8
import org.springframework.kafka.core.KafkaTemplate
9
import org.springframework.stereotype.Component
10

11
@Component
12
class KafkaCertificateEventPublisher(
13
    private val kafka: KafkaTemplate<String, ApplicationEventMessage>,
14
) : CertificateEventPublisherPort {
15

16
    override fun publish(event: CertificateEvent) {
17
        val type = when (event) {
18
            is ApplicationDecided -> "application.decided"
19
            is ApplicationEscalated -> "application.escalated"
20
        }
21
        kafka.send(TOPIC, event.application.applicationId.toString(), ApplicationEventMessage.from(type, event.application))
22
    }
23

24
    companion object {
25
        const val TOPIC = "certificate.application-events"
26
    }
27
}
28

29
data class ApplicationEventMessage(
30
    val type: String,
31
    val applicationId: String,
32
    val serviceCode: String,
33
    val citizenId: String,
34
    val status: String,
35
    val policyVersion: String,
36
    val appliedAt: String,
37
) {
38
    companion object {
39
        fun from(type: String, application: CertificateApplication) = ApplicationEventMessage(
40
            type = type,
41
            applicationId = application.applicationId.toString(),
42
            serviceCode = application.serviceCode.value,
43
            citizenId = application.citizenId,
44
            status = application.status.name,
45
            policyVersion = application.policyVersion,
46
            appliedAt = application.appliedAt.toString(),
47
        )
48
    }
49
}

The when over the sealed CertificateEvent is exhaustive — add a third event to the domain and every when without an else fails to compile, which is the compiler doing boundary enforcement for you. ApplicationEventMessage is a data class local to this module: the event contract, like the HTTP and JPA shapes, is an adapter concern. Consumers downstream never see the domain type.

How modules actually get swapped

“Swappable” is a claim; here are the two mechanisms that make it true.

Classpath swap. The bootstrap module is the only place that knows which implementations exist, so exchanging a Gradle dependency there exchanges the adapter. In bootstrap/build.gradle.kts, swapping the registry for its stub is a one-line change — no recompilation of anything that depends on the port, because nothing outside the adapter module references it:

1
plugins {
2
    kotlin("jvm")
3
    kotlin("plugin.spring")
4
    id("org.springframework.boot")
5
}
6

7
kotlin {
8
    jvmToolchain(21)
9
}
10

11
dependencies {
12
    implementation(project(":application"))
13

14
    // Functionality modules: add or remove a certificate service by adding or removing a module.
15
    implementation(project(":policy-income-certificate"))
16

17
    // Inbound adapters.
18
    implementation(project(":adapter-in-rest"))
19
    implementation(project(":adapter-in-messaging"))
20
    implementation(project(":adapter-in-batch"))
21

22
    // Outbound adapters: swap by exchanging the module dependency.
23
    implementation(project(":adapter-out-persistence"))
24
    implementation(project(":adapter-out-events"))
25
    implementation(project(":adapter-out-registry"))
26
    // implementation(project(":adapter-out-registry-stub"))
27

28
    implementation(platform("org.springframework.boot:spring-boot-dependencies:3.5.0"))
29
    implementation("org.springframework.boot:spring-boot-starter")
30

31
    testImplementation("com.tngtech.archunit:archunit-junit5:1.4.1")
32
    testImplementation("org.junit.jupiter:junit-jupiter")
33
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
34
}
35

36
tasks.test {
37
    useJUnitPlatform()
38
}

Profile swap. When both modules stay on the classpath, Spring profiles choose at startup. The real adapter is marked @Profile("!local-dev"); the stub module — a single fun interface lambda bean — activates only under local-dev:

1
package `in`.o612.eng.blogs.certificates.registrystub
2

3
import `in`.o612.eng.blogs.certificates.application.port.outbound.LoadCitizenProfilePort
4
import `in`.o612.eng.blogs.certificates.domain.CitizenProfile
5
import org.springframework.context.annotation.Bean
6
import org.springframework.context.annotation.Configuration
7
import org.springframework.context.annotation.Profile
8

9
@Configuration
10
@Profile("local-dev")
11
class StubCitizenRegistryModule {
12

13
    @Bean
14
    fun stubCitizenRegistry() = LoadCitizenProfilePort { citizenId ->
15
        CitizenProfile(
16
            citizenId = citizenId,
17
            resident = true,
18
            residenceYears = 6,
19
            ageYears = 34,
20
            annualHouseholdIncome = 120_000,
21
        )
22
    }
23
}

With spring.profiles.active=local-dev, the engine runs without the citizen registry — useful for development, demos, and adapter tests that need the real module’s exact seam. @ConditionalOnProperty is the alternative when the choice belongs in configuration rather than profiles.

Whichever mechanism you use, three rules keep swaps safe:

The port is the only contract. Nothing outside an adapter module may import its types — not for convenience, not “just this once.” The moment another module names CitizenRegistryAdapter, the swap is broken.
Adapters never depend on each other. The persistence adapter must not call the registry adapter; shared needs go through ports or the domain.
Every port needs exactly one bean per runtime. Two active implementations of LoadCitizenProfilePort produce an ambiguous-bean failure at startup — the @Profile guards exist to make the choice explicit, and the failure is loud rather than silently wrong.

The bootstrap module is the only place Spring assembles

bootstrap is the composition root: the application class, bean wiring, security, observability, and environment-specific configuration. It is the only module that sees the core, the policies, and every adapter:

1
package `in`.o612.eng.blogs.certificates
2

3
import org.springframework.boot.autoconfigure.SpringBootApplication
4
import org.springframework.boot.runApplication
5
import org.springframework.scheduling.annotation.EnableScheduling
6

7
@SpringBootApplication
8
@EnableScheduling
9
class CertificateEngineApplication
10

11
fun main(args: Array<String>) {
12
    runApplication<CertificateEngineApplication>(*args)
13
}

1
package `in`.o612.eng.blogs.certificates
2

3
import `in`.o612.eng.blogs.certificates.application.CertificateApplicationService
4
import `in`.o612.eng.blogs.certificates.application.port.outbound.CertificateEventPublisherPort
5
import `in`.o612.eng.blogs.certificates.application.port.outbound.ExistsPendingApplicationPort
6
import `in`.o612.eng.blogs.certificates.application.port.outbound.LoadCitizenProfilePort
7
import `in`.o612.eng.blogs.certificates.application.port.outbound.SaveCertificateApplicationPort
8
import `in`.o612.eng.blogs.certificates.domain.ServicePolicy
9
import org.springframework.context.annotation.Bean
10
import org.springframework.context.annotation.Configuration
11
import java.time.Clock
12

13
@Configuration
14
class BootstrapConfiguration {
15

16
    @Bean
17
    fun certificateApplicationService(
18
        citizenProfiles: LoadCitizenProfilePort,
19
        applications: SaveCertificateApplicationPort,
20
        pendingApplications: ExistsPendingApplicationPort,
21
        events: CertificateEventPublisherPort,
22
        policies: List<ServicePolicy>,
23
    ) = CertificateApplicationService(
24
        citizenProfiles,
25
        applications,
26
        pendingApplications,
27
        events,
28
        policies,
29
        Clock.systemUTC(),
30
    )
31
}

The @Component and @Configuration adapters satisfy the port parameters by type; the List<ServicePolicy> collects every certificate module’s bean; the only bean defined by hand is the use case itself, which deliberately has no Spring annotation. Configuration keys — datasource URL, Kafka bootstrap servers, citizen-registry.base-url — arrive through application.yaml backed by environment variables, so a swapped adapter changes wiring, not code.

Following one application through the system

Every arrow crosses a boundary exactly once, and every boundary crossing goes through a port or a mapping function. If you can trace a new feature through this diagram without inventing a shortcut, the architecture is holding.

Testing each boundary at the speed it deserves

The architecture’s payoff is that each layer gets the fastest test that can falsify it:

Domain and policy tests exercise IncomeCertificatePolicy directly: residence just under the three-year minimum, a duplicate pending application, an income mismatch inside and outside the tolerance. No framework, no setup — construct ApplicationFacts and assert on the PolicyOutcome.

Use-case tests substitute lambdas for the outbound ports — the fun interface declarations are what make this a one-liner per port — and supply their own ServicePolicy, because application must not depend on a concrete certificate module. The whole orchestration is verifiable in plain JUnit:

1
package `in`.o612.eng.blogs.certificates.application
2

3
import `in`.o612.eng.blogs.certificates.application.port.inbound.SubmitCertificateApplication.SubmitApplicationCommand
4
import `in`.o612.eng.blogs.certificates.application.port.outbound.CertificateEventPublisherPort
5
import `in`.o612.eng.blogs.certificates.application.port.outbound.ExistsPendingApplicationPort
6
import `in`.o612.eng.blogs.certificates.application.port.outbound.LoadCitizenProfilePort
7
import `in`.o612.eng.blogs.certificates.application.port.outbound.SaveCertificateApplicationPort
8
import `in`.o612.eng.blogs.certificates.domain.ApplicationDecided
9
import `in`.o612.eng.blogs.certificates.domain.ApplicationFacts
10
import `in`.o612.eng.blogs.certificates.domain.ApplicationStatus
11
import `in`.o612.eng.blogs.certificates.domain.CertificateApplication
12
import `in`.o612.eng.blogs.certificates.domain.CertificateEvent
13
import `in`.o612.eng.blogs.certificates.domain.CitizenProfile
14
import `in`.o612.eng.blogs.certificates.domain.PolicyOutcome
15
import `in`.o612.eng.blogs.certificates.domain.ServiceCode
16
import `in`.o612.eng.blogs.certificates.domain.ServicePolicy
17
import org.junit.jupiter.api.Assertions.assertEquals
18
import org.junit.jupiter.api.Test
19
import java.time.Clock
20
import java.time.Instant
21
import java.time.ZoneOffset
22

23
class CertificateApplicationServiceTest {
24

25
    private val testPolicy = object : ServicePolicy {
26
        override val serviceCode = ServiceCode("income-certificate")
27
        override val policyVersion = "income-certificate/test"
28
        override val slaDays = 15
29

30
        override fun evaluate(facts: ApplicationFacts) =
31
            if (facts.citizen.resident && !facts.pendingApplicationExists) {
32
                PolicyOutcome(ApplicationStatus.ACCEPTED, emptyList())
33
            } else {
34
                PolicyOutcome(ApplicationStatus.REJECTED, listOf("test rejection"))
35
            }
36
    }
37

38
    @Test
39
    fun `saves auditable application when citizen qualifies`() {
40
        val saved = mutableListOf<CertificateApplication>()
41
        val published = mutableListOf<CertificateEvent>()
42
        val citizens = LoadCitizenProfilePort {
43
            CitizenProfile(it, resident = true, residenceYears = 6, ageYears = 34, annualHouseholdIncome = 180_000)
44
        }
45

46
        val service = CertificateApplicationService(
47
            citizens,
48
            SaveCertificateApplicationPort { saved.add(it) },
49
            ExistsPendingApplicationPort { _, _ -> false },
50
            CertificateEventPublisherPort { published.add(it) },
51
            listOf(testPolicy),
52
            Clock.fixed(Instant.parse("2026-09-24T00:00:00Z"), ZoneOffset.UTC),
53
        )
54

55
        val application = service.submit(
56
            SubmitApplicationCommand(ServiceCode("income-certificate"), "C-1001", 180_000),
57
        )
58

59
        assertEquals(ApplicationStatus.ACCEPTED, application.status)
60
        assertEquals("income-certificate/test", application.policyVersion)
61
        assertEquals(Instant.parse("2026-09-24T00:00:00Z"), application.appliedAt)
62
        assertEquals(1, saved.size)
63
        assertEquals(application, (published.single() as ApplicationDecided).application)
64
    }
65
}

This test starts no Spring context and opens no database connection — it runs at plain unit-test speed. That is not a style preference; it is what makes rule changes cheap to verify when a threshold moves the week before a deadline.

Adapter tests own their technology’s failure modes:

REST: request validation, the 404 mappings for CitizenNotFoundException and UnknownServiceException, and response field mapping via @WebMvcTest or MockMvc.
Messaging: malformed payloads, deserialization boundaries, and redelivery behavior against an embedded broker or a mock consumer test.
Persistence: entity mapping and the derived pending/overdue queries against real PostgreSQL through Testcontainers — an in-memory database will not catch dialect problems.
Registry: timeout behavior, error translation, and upstream-schema tolerance against a mock HTTP server such as WireMock or MockWebServer.
Events: topic, key, and payload shape for both CertificateEvent types, plus what a failed send does to the use case — a question KafkaCertificateEventPublisher leaves open deliberately.

Architecture tests turn the dependency rule into a build failure. ArchUnit lives in the bootstrap module, the one place whose test classpath sees every module:

1
package `in`.o612.eng.blogs.certificates
2

3
import com.tngtech.archunit.junit.AnalyzeClasses
4
import com.tngtech.archunit.junit.ArchTest
5
import com.tngtech.archunit.lang.ArchRule
6
import com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses
7

8
@AnalyzeClasses(packages = ["in.o612.eng.blogs.certificates"])
9
class ArchitectureTest {
10

11
    @ArchTest
12
    val `core is framework free`: ArchRule = noClasses()
13
        .that().resideInAnyPackage("..domain..", "..application..")
14
        .should().dependOnClassesThat()
15
        .resideInAnyPackage("org.springframework..", "jakarta.persistence..", "org.apache.kafka..")
16
}

The first time someone imports EntityManager in the domain module — under deadline, with the best intentions — this test is the code review that never sleeps. A worthwhile second rule asserts that adapter packages never depend on each other.

What a production deployment adds

The example deliberately stops at the architecture. A real certificate service owes more:

Issuance, not just acceptance. The flow shown decides whether an application proceeds; a production system adds officer approval, digital signing, secure storage, and delivery of the certificate itself.
Explainability. Persist the input facts used, not only the outcome — when an applicant disputes a rejection, “the registry recorded X on this date” is the answer they are owed.
Policy versioning. Decisions must link reproducibly to a policy version; the policyVersion field is the hook, and a versioned rules store is the next step when policy authors outnumber developers.
Privacy. Store the minimum personal data the decision requires; rejection reasons in API responses should name rules, not leak registry attributes.
Idempotency. Retried submissions — from the portal or the CSC queue — must not create duplicate applications; the pendingApplicationExists check is the seam, backed by a unique constraint on (serviceCode, citizenId) for pending statuses.
Human review. MANUAL_REVIEW is a first-class outcome for discrepancies like the income mismatch, not an exception handler — and it needs a worklist UI in front of it.
Resilience. Registry outages are operational events, distinct from ineligibility — conflating them denies citizens services and falsifies your metrics at the same time.
Rule complexity. Start with domain policy objects. Reach for a decision table or a DMN (Decision Model and Notation) engine only when policy change frequency justifies the machinery, not before.

Mistakes this design prevents — and the ones it does not

The module boundaries make some classic failures structurally impossible — a service cannot call a JPA repository it cannot see — but most hexagonal-codebase damage is self-inflicted and legal:

Naming ports after infrastructure (KafkaPublisher, JpaApplicationRepository), which smuggles the technology into the core’s vocabulary.
Making REST DTOs or JPA entities double as the domain model, which couples your business vocabulary to the first transport you happened to build.
Referencing an adapter class by name from another module, which quietly welds the “swappable” module in place.
Creating an interface for every class rather than at real boundaries — ports are for capabilities the use case consumes, not for ceremony.
Adding Spring annotations to the core “just for convenience,” which is how the dependency arrow quietly reverses.
Splitting every package into its own Gradle module; modules should protect meaningful boundaries, not multiply build files.
Treating a failed registry call as a rejection.
Persisting decisions without reasons, timestamps, or policy version — an audit trail that cannot explain itself is storage, not evidence.

When the structure earns its keep

Hexagonal architecture costs real things: an interface per capability, a mapping function per boundary, a composition root, a module count that can look like ceremony — eleven modules for one use case is a lot if nothing ever swaps — and a team that has to maintain the discipline on the hundredth change, not just the first. For a small CRUD service with one entry point and one database, a clean layered service is the honest choice.

It pays when several of these are true at once: the business rules carry weight, integrations change on someone else’s schedule, more than one entry point exists or is coming, functionality arrives as discrete units (a new certificate type, a new upstream registry), decisions must be explained later, and tests need to run without infrastructure. The certificate engine hits all six — service-delivery platforms are precisely the systems where channels, certificate types, and backend registries keep multiplying — and why the test suite, not the diagram, is the real deliverable.

Check the boundaries before calling it done

Can IncomeCertificatePolicy run without Spring Boot or PostgreSQL on the classpath?
Does CertificateApplicationService import only domain types and ports?
Can a new inbound adapter call SubmitCertificateApplication without copying a single rule?
Can the registry adapter be swapped for the stub — by dependency or by profile — without touching the core or another adapter?
Can a second certificate type ship as a new module implementing ServicePolicy, with no changes in application?
Does every persisted application carry reasons, a timestamp, and the policy version?
Does an ArchUnit rule fail the build when the dependency direction is violated?

If any answer is no, the problem is in the boundary, not the pattern.

Where to take it next

Two natural extensions exercise the seams this article built. IssueCertificate is a second inbound port: an officer approves a MANUAL_REVIEW application, the engine signs and stores the certificate, and publishes CertificateIssued. And a second service — a domicile certificate with different residence rules — is a new policy-* module that should require no changes anywhere except settings.gradle.kts and the bootstrap dependencies. If either forces you to edit the core, that is the signal the boundary needs attention.

ArchitectureSpring BootKotlin