𝗧𝗵𝗲 𝗣𝗿𝗮𝗴𝗺𝗮𝘁𝗶𝗰 𝗛𝗲𝘅𝗮𝗴𝗼𝗻: 𝗦𝗰𝗮𝗹𝗶𝗻𝗴 𝗗𝗲𝗰𝗼𝘂𝗽𝗹𝗶𝗻𝗴 𝘄𝗶𝘁𝗵𝗼𝘂𝘁 𝗖𝗼𝗺𝗽𝗹𝗲𝘅𝗶𝘁𝘆

𝗧𝗵𝗲 𝗧𝗲𝗻𝘀𝗶𝗼𝗻 𝗼𝗻 𝘁𝗵𝗲 𝗧𝗿𝗮𝗶𝗹

In a professional kitchen, there is a concept called mise en place—everything in its place. You don’t start searing the scallops until every herb is chopped and every sauce is whisked. If you skip the prep to “save time,” you end up adjusting the recipe mid-sauté, usually resulting in a frantic mess, ruined ingredients, and a dish that takes twice as long to serve.

Modern software development has a similar “popular choice”: start coding the logic immediately to show “progress.” But when we skip the architectural prep—the interfaces and boundaries—we aren’t moving fast; we are just building a kitchen we’ll have to tear down while the customers are waiting. I’ve watched engineers lose sight of the goal in the pursuit of a “perfect flow” that wasn’t grounded in discipline. If everyone says they want “clean code,” why does the system feel like it’s fighting us the moment we add a new story?

𝗦𝘆𝘀𝘁𝗲𝗺 𝗚𝗲𝗼𝗺𝗲𝘁𝗿𝘆

The environment of this experiment is a standard Kotlin and Spring Boot stack. The landscape is defined by three distinct zones designed to minimize the “weight” of dependencies. To navigate this space, we use a rigid directory structure that acts as our map:

app

├── domain      <-- THE HEART (POKOs only)
│   ├── model
│   │   └── Data.kt     <-- Pure Kotlin Data Class
│   └── ports
│       └── outgoing    <-- Interfaces defining “What” we need
│           ├── DataPersistencePort.kt    <- SQL db
│           └── DataStoragePort.kt        <- Object storage
├── usecases    <-- THE ORCHESTRATOR
│   └── StoreDataUseCase.kt    <-- Feature logic
└── adapter     <-- THE “HOW” (Infrastructure)
    ├── web         <-- Inbound Adapter
    │   ├── DataController.kt
    │   ├── dto         <-- Request/Response DTOs
    │       └── WebMapper.kt    <-- DTO <-> Domain mapping
    ├── sqldb       <-- Outbound Adapter
    │   ├── entity
    │   │   └── DataJpaEntity.kt    <-- @Entity + JPA annotation
    │   ├── DataRepository.kt        <-- Spring Data/CrudRepository
    │   ├── PersistenceMapper.kt     <-- Entity <-> Domain mapping
    │   └── PersistenceAdapter.kt    <-- Impl DataPersistencePort
    └── cloud       <-- Outbound Adapter
        └── ObjectStorageAdapter.kt

➤ The Heart (Domain): Pure Kotlin Data Classes and business logic common to all usecases.

➤ The Orchestrator (Usecases): Where feature-specific logic lives and adapters are coordinated.

➤ The Infrastructure (Adapters): The “How” of the system—web controllers, JPA entities, and cloud storage clients.

The invisible boundary here is the Port. It’s an interface that defines “what” we need without caring “how” it’s done. In theory, this geometry should be light and flexible, yet many teams find it rigid because they misunderstand the direction of the signal.

𝗘𝗺𝗽𝗶𝗿𝗶𝗰𝗮𝗹 𝗘𝘅𝗽𝗹𝗼𝗿𝗮𝘁𝗶𝗼𝗻

I moved from the “theoretical path” of perfect architecture to the “actual terrain” of daily PRs. The system showed its breaking point not in a crash, but in a silent failure of discipline: the Domain Import Leak.

➤ The Breaking Point: It usually starts when an engineer adds a domain service that directly imports an adapter: import app.adapter.NewAdapter.kt.

➤ The Silent Failure: The code still passes tests. It still “works”. But the “Pure Domain” has been poisoned by infrastructure concerns.

➤ The Result: When the time inevitably comes to move that service to a usecase, the system reacts with extreme fatigue. We end up with PRs requiring the renaming of tens of files, leading to typos, package mismatches, and a massive mental load on reviewers.

𝗠𝗮𝗻𝗮𝗴𝗶𝗻𝗴 𝘁𝗵𝗲 𝗦𝗶𝗴𝗻𝗮𝗹

The handoff between layers is where the “spaghetti” starts or ends. In my exploration, I found that the clarity of intent is often lost because teams are afraid of the “complexity” of an extra interface.

➤ Cognitive Load: Trying to refactor architecture in the middle of a feature story creates a “refactoring nightmare”.

➤ Signal-to-Noise: If you are 100% sure a logic block belongs in the domain, put it there. If not, the “cleaner” signal is to start in a Usecase and extract downward only when the need is proven.

➤ Direct Translation: To keep the signal clear, I’ve found it’s even acceptable to call a Port directly from a controller for simple cases. This avoids 1:1 “pass-through” mapping while keeping the adapter decoupled through the interface.

𝗪𝗵𝗮𝘁 𝗘𝗮𝗿𝗻𝗲𝗱 𝗧𝗿𝘂𝘀𝘁?

After the stress test of “no time to decouple,” one principle remained standing: Mandatory Ports from the Start.

➤ Stability: The “price” of an interface at the start is effectively zero. It provides an immediate boundary that prevents the “import leak” and allows the domain to remain pure. ➤ The New Baseline: My trusted navigation strategy is now TDD-driven Hexagon.

• Step 1: Define the Domain Model.

• Step 2: Build the Adapter and verify it with Testcontainers (SQL or Object Storage).

• Step 3: Finally, orchestrate it all in the Usecase or Controller using the Port interface.

𝗔𝗰𝘁𝗶𝗼𝗻𝗮𝗯𝗹𝗲 𝗜𝗻𝘀𝗶𝗴𝗵𝘁𝘀

➤ Backlog (Failed the Stress Test):

• “Refactoring-in-the-middle”: Changing architecture while delivering a story leads to mess and typos.

• Direct Adapter Imports: Any import app.adapter inside app.domain is a bug, not a feature.

➤ Merged (Trusted Toolkit):

• Ports First: Always create the interface for 3rd party services or repositories immediately.

• Adapter-First Testing: Use Testcontainers to prove your “How” works before you worry about the “What” in your orchestration.

• Minimum Layers: Only add a Usecase layer if there is actual orchestration; otherwise, call the Port from the Controller.

Final Wisdom: Clean architecture isn’t about having the most layers; it’s about having the most resilient boundaries. The “price” of an interface is nothing compared to the cost of a messy PR that no one wants to review.

---