Beginner

// Zone 1: Domain — zero framework imports allowed here
// => Package: com.example.order.domain
// => Only JDK standard library (java.util, java.math) permitted
package com.example.order.domain;
 
// Domain entity: pure Java, no @Entity, no @JsonProperty, no Spring annotations
// => Compiles and runs without Spring, JPA, or any framework on the classpath
public record Order(
    OrderId id,           // => strongly-typed identity value object
    CustomerId customerId, // => typed; cannot accidentally swap with OrderId
    Money total,          // => Money value object carries currency
    OrderStatus status     // => domain enum; no framework dependency
) {}
 
// Zone 2: Application — imports domain only
// => Package: com.example.order.application
// => May import com.example.order.domain.*; must not import adapter packages
package com.example.order.application;
 
// Zone 3: Adapter — imports application and framework
// => Package: com.example.order.adapter.in.web
// => May import org.springframework.*, com.example.order.application.*
package com.example.order.adapter.in.web;

// Zone 1: Domain package — no framework imports ever cross this boundary
// => package com.example.order.domain
// => data classes, sealed classes, pure functions only
package com.example.order.domain
 
// Domain types are plain Kotlin; no Ktor, no Spring, no Exposed annotations
// => Runs in a plain JVM test with zero framework on the classpath
data class Order(
    val id: OrderId,            // => val = immutable; no setters generated
    val customerId: CustomerId, // => typed; prevents id-kind confusion at compile time
    val total: Money,           // => domain value object; not Double
    val status: OrderStatus     // => sealed class member; exhaustive when-branch
)
 
// Zone 2: package com.example.order.application — imports domain only
// Zone 3: package com.example.order.adapter.in.web — imports application + Ktor

// Zone 1: Domain namespace — no framework using directives permitted
// => namespace Example.Order.Domain
// => Only System, System.Collections.Generic allowed
namespace Example.Order.Domain;
 
// Domain record: no [Table], no [JsonPropertyName], no EF Core attributes
// => Pure C# record; works without any NuGet package beyond the BCL
public record Order(
    OrderId Id,             // => init-only; cannot be mutated after construction
    CustomerId CustomerId,  // => distinct type; compiler catches id-kind swaps
    Money Total,            // => Money record; not decimal
    OrderStatus Status      // => domain enum; framework-free
);
 
// Zone 2: namespace Example.Order.Application — using Example.Order.Domain only
// Zone 3: namespace Example.Order.Adapter.In.Web — using Application + Microsoft.AspNetCore.*

// ANTI-PATTERN: JPA annotation in the domain layer
// => @Entity couples Order to JPA; cannot run Order without hibernate on classpath
import jakarta.persistence.Entity;  // => imports JPA into the domain — violates the rule
// => executes the statement above; continues to next line
import jakarta.persistence.Id;      // => infrastructure annotation in business class
// => executes the statement above; continues to next line
import com.fasterxml.jackson.annotation.JsonProperty; // => JSON serialisation in domain
// => executes the statement above; continues to next line
 
@Entity                             // => domain class now requires JPA at test time
// => @Entity: JPA maps this class to a database table — adapter zone only
public class Order {                // => Order class polluted with persistence concern
// => class Order: implementation — contains field declarations and methods below
    @Id                             // => @Id marks persistence primary key — not a domain concept
    // => @Id: JPA primary key mapping — persistence adapter concern
    private String id;              // => raw String; @Id annotation bleeds infrastructure
    // => id: String — injected dependency; implementation chosen at wiring time
    @JsonProperty("customer_id")    // => JSON naming in domain — adapter concern leaked in
    // => annotation marks metadata for framework or compiler
    private String customerId;      // => untyped; id-kind confusion possible at runtime
    // => customerId: String — injected dependency; implementation chosen at wiring time
}
// Problem: to test Order you must start a JPA context and Jackson on the classpath
// => coupling cost: two framework dependencies forced into every unit test

// Domain entity: zero framework imports; compiles with just the JDK
// => No @Entity, no @Id, no @JsonProperty, no Spring, no Jackson
public record Order(                       // => record Order: immutable; equals/hashCode/toString generated
// => executes the statement above; continues to next line
    OrderId id,            // => OrderId is a domain value object, not a raw String
    // => executes the statement above; continues to next line
    CustomerId customerId, // => CustomerId prevents id-kind swap at compile time
    // => executes the statement above; continues to next line
    Money total,           // => Money carries currency; BigDecimal alone does not
    // => executes the statement above; continues to next line
    OrderStatus status     // => domain enum; exhaustive switch enforced by compiler
    // => executes the statement above; continues to next line
) {
    // Domain behaviour lives here — pure function, no I/O
    public Order confirm() {                // => confirm method; no DB call
        // => Returns new Order with status changed; immutable; original unchanged
        return new Order(id, customerId, total, OrderStatus.CONFIRMED); // => new record; this unchanged
        // => returns the result to the caller — caller receives this value
    }
}
// Test: new Order(id, cid, money, PENDING) — no framework needed; instant
// => Test execution: sub-millisecond; no Spring/Hibernate on classpath

// ANTI-PATTERN: JPA + Jackson in Kotlin domain class
// => import jakarta.persistence.* leaks infrastructure into domain zone
import jakarta.persistence.Entity  // => wrong: domain imports JPA
// => executes the statement above; continues to next line
import jakarta.persistence.Id      // => wrong: JPA @Id in domain entity
// => executes the statement above; continues to next line
 
@Entity                            // => couples Kotlin class to JPA container
// => @Entity: JPA maps this class to a database table — adapter zone only
data class Order(
// => data class Order: value type; copy/equals/hashCode/toString auto-generated
    @Id val id: String,            // => raw String; @Id is adapter concern here
    // => @Id: JPA primary key mapping — persistence adapter concern
    val customerId: String         // => untyped; can swap ids accidentally
    // => executes the statement above; continues to next line
)
 
// CORRECT: plain Kotlin data class in domain package
// => No framework annotations; only Kotlin stdlib and domain types
data class Order(                                // => data class Order — equals/hashCode/copy generated
// => data class Order: value type; copy/equals/hashCode/toString auto-generated
    val id: OrderId,               // => typed identity; domain value object
    // => executes the statement above; continues to next line
    val customerId: CustomerId,    // => distinct type; compile-time safety
    // => executes the statement above; continues to next line
    val total: Money,              // => domain value object; not Double
    // => executes the statement above; continues to next line
    val status: OrderStatus        // => sealed class; exhaustive when branches
    // => sealed class type: closed hierarchy; when-expression exhaustiveness enforced
) {
    fun confirm(): Order =         // => returns a new Order; immutable pattern
    // => executes the statement above; continues to next line
        copy(status = OrderStatus.Confirmed)  // => copy() changes only status field
        // => method call: delegates to collaborator; result captured above
}

// ANTI-PATTERN: EF Core and JSON attributes in domain record
// => using Microsoft.EntityFrameworkCore; in domain namespace
using System.ComponentModel.DataAnnotations.Schema; // => wrong: EF in domain
// => executes the statement above; continues to next line
using System.Text.Json.Serialization;               // => wrong: JSON in domain
// => executes the statement above; continues to next line
 
[Table("orders")]                              // => EF Core attribute in domain — violation
// => executes the statement above; continues to next line
public record Order(
// => executes the statement above; continues to next line
    [property: JsonPropertyName("order_id")]
    // => executes the statement above; continues to next line
    string Id,                                 // => raw string + JSON annotation in domain
    // => executes the statement above; continues to next line
    string CustomerId                          // => no type safety; adapter concern in domain
    // => executes the statement above; continues to next line
);
 
// CORRECT: clean C# record in domain namespace
// => No using directives for EF, JSON, or any framework
public record Order(                             // => record Order — value semantics; init-only properties
// => executes the statement above; continues to next line
    OrderId Id,             // => typed; init-only; domain value object
    // => executes the statement above; continues to next line
    CustomerId CustomerId,  // => distinct type prevents id confusion
    // => executes the statement above; continues to next line
    Money Total,            // => Money not decimal; carries currency
    // => executes the statement above; continues to next line
    OrderStatus Status      // => domain enum; no framework dependency
    // => executes the statement above; continues to next line
)
{
    // => Domain method: pure transformation; no I/O
    public Order Confirm() =>
    // => executes the statement above; continues to next line
        this with { Status = OrderStatus.Confirmed }; // => new record; this unchanged
        // => record type: immutable value type; equals/hashCode/toString generated by compiler
}

// Package: com.example.order.application.port.in
// => Input port: interface lives in application zone, not domain, not adapter
package com.example.order.application.port.in;
 
import com.example.order.domain.UnvalidatedOrder; // => domain type; application may import domain
import com.example.order.domain.OrderPlaced;       // => domain event returned on success
import com.example.order.domain.PlacingOrderError; // => domain error sealed type
 
// PlaceOrderUseCase: single-method input port; one use case = one method
// => Interface defined here; adapters call it; service implements it
// => No HTTP, no SQL, no framework imports on this interface
public interface PlaceOrderUseCase {
    // => Result<S,E>: right-biased union type; Success carries List<OrderPlaced>; Failure carries PlacingOrderError
    // => Using a simple sealed interface Result to avoid external library dependency
    Result<java.util.List<OrderPlaced>, PlacingOrderError> placeOrder(UnvalidatedOrder order);
    // => Callers cannot ignore failure; they must pattern-match on Result
}
// Adapters: import this interface; call placeOrder(); never call PlaceOrderService directly

// Package: com.example.order.application.port.in
// => Input port defined in application layer; domain and adapter do not define this
package com.example.order.application.port.`in`
 
import com.example.order.domain.UnvalidatedOrder  // => domain type; legal import in application zone
import com.example.order.domain.OrderPlaced        // => domain event; returned on success
import com.example.order.domain.PlacingOrderError  // => domain error; returned on failure
 
// Kotlin interface: single abstract method; adapters call through this contract
// => No Ktor, no Spring, no database dependency on this interface
interface PlaceOrderUseCase {
    // => Result<List<OrderPlaced>, PlacingOrderError>: success or failure union
    // => Kotlin Result is stdlib; or use Arrow Either for right-biased semantics
    fun placeOrder(order: UnvalidatedOrder): Result<List<OrderPlaced>>
    // => Callers use .getOrElse { error -> ... } to handle both branches
}
// Adapters implement callers: webRoute calls placeOrderUseCase.placeOrder(...)

// Namespace: Example.Order.Application.Port.In
// => Input port interface: application zone only; no framework using directives
namespace Example.Order.Application.Port.In;
 
using Example.Order.Domain; // => application zone may import domain types
 
// IPlaceOrderUseCase: C# convention prefixes interfaces with I
// => Single method; one interface = one use case responsibility
// => No IActionResult, no HttpContext, no DbContext — purely domain types
public interface IPlaceOrderUseCase
{
    // => OneOf<List<OrderPlaced>, PlacingOrderError>: discriminated union via OneOf NuGet
    // => Or use custom Result<T,E> record to avoid external dependency
    OneOf<IReadOnlyList<OrderPlaced>, PlacingOrderError> PlaceOrder(UnvalidatedOrder order);
    // => Callers must handle both branches; compiler enforces via switch expression
}
// Web controller: inject IPlaceOrderUseCase; call PlaceOrder(); never new PlaceOrderService()

// Package: com.example.order.application.port.out
// => Output port: defined in application zone; implemented by adapters
package com.example.order.application.port.out;
// => executes the statement above; continues to next line
 
import com.example.order.domain.Order;   // => domain type; application may import domain
// => executes the statement above; continues to next line
import com.example.order.domain.OrderId; // => typed id; no raw String parameters
// => executes the statement above; continues to next line
 
import java.util.Optional; // => JDK stdlib; not a framework dependency
 
// OrderRepository: output port; tells application zone what it NEEDS from outside
// => No import jakarta.persistence.*; no SQL; no JDBC — purely domain and stdlib
public interface OrderRepository {         // => interface in application zone; adapters in adapter zone
// => interface OrderRepository: contract definition — no implementation details here
    Optional<Order> findById(OrderId id);  // => returns Optional; callers handle absent case
    // => executes the statement above; continues to next line
    Order save(Order order);               // => returns saved Order (may carry generated id)
    // => executes the statement above; continues to next line
    void delete(OrderId id);               // => side-effecting; no return needed
    // => executes the statement above; continues to next line
}
// JPA adapter implements this; InMemory adapter implements this; test doubles implement this
// => Application service never knows which implementation is active at runtime

// Package: com.example.order.application.port.out
// => Output port defined in application zone; no Exposed, no JDBC import here
package com.example.order.application.port.out
// => executes the statement above; continues to next line
 
import com.example.order.domain.Order    // => domain type; legal import in application zone
// => executes the statement above; continues to next line
import com.example.order.domain.OrderId  // => typed id; not raw String
 
// Kotlin interface: application zone describes what it needs; adapter provides it
// => suspend fun marks coroutine-friendly signature for async adapter implementations
interface OrderRepository {
// => interface OrderRepository: contract definition — no implementation details here
    suspend fun findById(id: OrderId): Order?   // => nullable return; Kotlin null-safety
    // => executes the statement above; continues to next line
    suspend fun save(order: Order): Order        // => returns persisted Order
    // => executes the statement above; continues to next line
    suspend fun delete(id: OrderId)              // => unit-returning side effect
    // => executes the statement above; continues to next line
}
// Exposed adapter: implements OrderRepository with Exposed SQL DSL
// InMemory adapter: implements OrderRepository with mutableMapOf()
// Application service: only knows OrderRepository interface; never the concrete class

// Namespace: Example.Order.Application.Port.Out
// => Output port interface: application zone; no EF Core, no Dapper imports
namespace Example.Order.Application.Port.Out;
// => executes the statement above; continues to next line
 
using Example.Order.Domain; // => domain types only
// => executes the statement above; continues to next line
using System.Threading.Tasks; // => BCL async support; not a framework dependency
 
// IOrderRepository: output port; C# convention uses I prefix for interfaces
// => Task<T> signals async; adapter may use async/await internally
public interface IOrderRepository
// => executes the statement above; continues to next line
{
    Task<Order?> FindByIdAsync(OrderId id);     // => nullable Task; caller handles null
    // => executes the statement above; continues to next line
    Task<Order> SaveAsync(Order order);          // => returns saved domain Order
    // => executes the statement above; continues to next line
    Task DeleteAsync(OrderId id);                // => fire-and-forget side effect
    // => executes the statement above; continues to next line
}
// EF Core adapter implements IOrderRepository with DbContext
// InMemory adapter implements IOrderRepository with Dictionary<OrderId, Order>
// PlaceOrderService receives IOrderRepository; never knows the concrete class

package com.example.order.application.service;
 
// Application zone imports: domain + own port interfaces; nothing else
import com.example.order.application.port.in.PlaceOrderUseCase;    // => input port this class implements
// => executes the statement above; continues to next line
import com.example.order.application.port.out.OrderRepository;     // => output port injected at construction
// => executes the statement above; continues to next line
import com.example.order.application.port.out.NotificationPort;    // => second output port for email/SMS
// => executes the statement above; continues to next line
import com.example.order.domain.*;                                 // => all domain types and functions
// => executes the statement above; continues to next line
 
import java.util.List;  // => JDK only; no Spring, no JPA, no HTTP imports
 
// PlaceOrderService: implements input port; depends on output ports through interfaces
// => No @Service, no @Autowired — framework annotations go in the wiring config, not here
public class PlaceOrderService implements PlaceOrderUseCase {
// => PlaceOrderService implements PlaceOrderUseCase — satisfies the port contract
    private final OrderRepository orderRepository;   // => output port; injected; immutable reference
    // => orderRepository: OrderRepository — final field; assigned once in constructor; immutable reference
    private final NotificationPort notificationPort; // => output port; injected; not an SMTP class
 
    // => Constructor injection: dependencies explicit; no reflection magic required
    public PlaceOrderService(OrderRepository orderRepository, NotificationPort notificationPort) {
    // => constructor: receives all dependencies — enables testing with any adapter implementation
        this.orderRepository = orderRepository;     // => stored; used in placeOrder
        // => this.orderRepository stored — field holds injected orderRepository for method calls below
        this.notificationPort = notificationPort;   // => stored; used to send confirmation
        // => this.notificationPort stored — field holds injected notificationPort for method calls below
    }
 
    @Override                                                          // => interface method; compiler checks signature
    // => @Override: compiler verifies this method signature matches the interface
    public Result<List<OrderPlaced>, PlacingOrderError> placeOrder(UnvalidatedOrder input) {
        // => Step 1: pure domain validation; no I/O; fast
        var validated = OrderValidator.validate(input); // => validated: Result<ValidatedOrder, PlacingOrderError>
        // => validated: holds the result of the expression on the right
        if (validated.isFailure()) return Result.failure(validated.getError()); // => early return on invalid input
 
        // => Step 2: pure domain pricing; no I/O; no database call
        var priced = OrderPricer.price(validated.getValue()); // => priced: PricedOrder with Money total set
 
        // => Step 3: persist through output port; adapter decides HOW
        var saved = orderRepository.save(priced);   // => calls output port; not JPA directly
 
        // => Step 4: notify through output port; adapter decides WHICH channel
        notificationPort.sendOrderConfirmation(saved); // => calls output port; not SMTP directly
 
        // => Step 5: return domain event list; controller maps to HTTP response
        return Result.success(List.of(new OrderPlaced(saved.id(), saved.customerId()))); // => wraps event in success Result
        // => returns the result to the caller — caller receives this value
    }
}
// No HTTP dependency: CLI adapter can call this service identically to web controller
// => PlaceOrderService has zero framework imports; swapping Spring for Quarkus leaves this file unchanged

package com.example.order.application.service
// => executes the statement above; continues to next line
 
import com.example.order.application.port.`in`.PlaceOrderUseCase // => implements this input port
// => executes the statement above; continues to next line
import com.example.order.application.port.out.OrderRepository    // => output port; injected
// => executes the statement above; continues to next line
import com.example.order.application.port.out.NotificationPort   // => second output port
// => executes the statement above; continues to next line
import com.example.order.domain.*                                // => domain functions and types
 
// PlaceOrderService: application zone; orchestrates domain + output ports
// => No @Service annotation here; wiring config handles Spring/Koin binding
class PlaceOrderService(
// => executes the statement above; continues to next line
    private val orderRepository: OrderRepository,   // => output port; constructor-injected
    // => executes the statement above; continues to next line
    private val notificationPort: NotificationPort  // => output port; not an SMTP implementation
    // => executes the statement above; continues to next line
) : PlaceOrderUseCase {                             // => implements input port interface
// => type implements input port interface — satisfies the port contract
 
    override suspend fun placeOrder(input: UnvalidatedOrder): Result<List<OrderPlaced>> {
        // => validate: pure domain function; returns Result<ValidatedOrder>
        val validated = OrderValidator.validate(input)
        // => validated: holds the result of the expression on the right
            .getOrElse { return Result.failure(it) } // => early exit on validation failure
 
        // => price: pure domain function; no network call; no database read
        val priced = OrderPricer.price(validated)    // => returns PricedOrder
 
        // => save: delegates to output port; Exposed/JPA adapter handles SQL
        val saved = orderRepository.save(priced)     // => returns persisted Order
 
        // => notify: delegates to output port; SMTP adapter handles email sending
        notificationPort.sendOrderConfirmation(saved) // => fire and forget in production
 
        // => return domain event; controller maps to HTTP 201
        return Result.success(listOf(OrderPlaced(saved.id, saved.customerId)))
        // => OrderPlaced: domain event; contains only identity and customer, not full Order
    }
}
// suspend marks coroutine-friendly; Ktor controller can call without blocking a thread

namespace Example.Order.Application.Service;
// => executes the statement above; continues to next line
 
using Example.Order.Application.Port.In;   // => implements IPlaceOrderUseCase
// => executes the statement above; continues to next line
using Example.Order.Application.Port.Out;  // => IOrderRepository and INotificationPort injected
// => executes the statement above; continues to next line
using Example.Order.Domain;                // => all domain types
 
// PlaceOrderService: no [ApiController], no DbContext, no HttpClient imports
// => Pure orchestration: validate → price → save → notify → return events
public class PlaceOrderService : IPlaceOrderUseCase  // => implements input port interface
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    private readonly IOrderRepository _orderRepository;    // => output port; readonly; injected
    // => executes the statement above; continues to next line
    private readonly INotificationPort _notificationPort;  // => output port; not an SmtpClient
 
    // => Constructor injection: ASP.NET DI resolves concrete adapters at runtime
    public PlaceOrderService(IOrderRepository orderRepository, INotificationPort notificationPort)
    // => constructor: receives all dependencies — enables testing with any adapter implementation
    {
    // => operation completes; execution continues to next statement
        _orderRepository = orderRepository;    // => stored; used in PlaceOrder
        // => executes the statement above; continues to next line
        _notificationPort = notificationPort;  // => stored; used to send confirmation
        // => executes the statement above; continues to next line
    }
    // => operation completes; execution continues to next statement
 
    public async Task<OneOf<IReadOnlyList<OrderPlaced>, PlacingOrderError>> PlaceOrder(UnvalidatedOrder input)
    // => executes the statement above; continues to next line
    {
        // => Step 1: pure domain validation; synchronous; no I/O
        var validated = OrderValidator.Validate(input);
        // => validated: holds the result of the expression on the right
        if (validated.IsT1) return validated.AsT1; // => early return on PlacingOrderError
 
        // => Step 2: pure domain pricing; synchronous; computes Money from domain rules
        var priced = OrderPricer.Price(validated.AsT0);
 
        // => Step 3: save through output port; EF Core adapter executes SQL
        var saved = await _orderRepository.SaveAsync(priced); // => async; adapter decides impl
 
        // => Step 4: notify through output port; SMTP adapter sends email
        await _notificationPort.SendOrderConfirmationAsync(saved); // => adapter decides channel
 
        // => Step 5: domain event list returned; controller maps to 201 Created
        return new List<OrderPlaced> { new(saved.Id, saved.CustomerId) };
        // => List<OrderPlaced>: one event per order; adapter converts to JSON response body
    }
    // => operation completes; execution continues to next statement
}
// => operation completes; execution continues to next statement

// ===================== LEGAL IMPORTS =====================
 
// Domain class: imports nothing from application or adapter zones
// => package com.example.order.domain
// => Only java.* or domain sibling classes
import java.math.BigDecimal; // => JDK stdlib: legal in domain
import java.util.List;       // => java.util is standard — always allowed in domain
import java.util.Optional;   // => Optional: standard null-safe type — legal in domain
// import com.example.order.application.port.in.*; // => ILLEGAL: domain importing application
// import org.springframework.*;                   // => ILLEGAL: framework in domain
 
// Domain entity: no @Entity, no @JsonProperty, no framework annotations
public record Order(String id, String customerId, BigDecimal total) {
// => record: generates equals/hashCode/toString; immutable; no JPA dependency
    public static Order create(String id, String customerId, BigDecimal total) {
// => factory method — validates and constructs; never reaches framework code
        return new Order(id, customerId, total);
// => returns immutable value; domain layer stays pure
    }
}
 
// Application class: imports domain; must not import adapter
// => package com.example.order.application.service
import com.example.order.domain.Order;  // => legal: application → domain
// import com.example.order.adapter.out.persistence.JpaOrderRepository; // => ILLEGAL
 
// Adapter class: imports application and framework — both legal
// => package com.example.order.adapter.in.web
import com.example.order.application.port.in.PlaceOrderUseCase; // => legal: adapter → application
import org.springframework.web.bind.annotation.RestController;  // => legal: adapter → framework
 
// ===================== COMPILE-ERROR EXAMPLE =====================
// Domain entity accidentally imports an adapter class:
// package com.example.order.domain;
// import com.example.order.adapter.out.persistence.OrderJpaEntity; // => COMPILE ERROR
// => Domain module has no classpath dependency on adapter module
// => Gradle/Maven module boundaries enforce this at build time

package com.example.order.adapter.out.persistence;
// => executes the statement above; continues to next line
 
import com.example.order.application.port.out.OrderRepository; // => implements this output port
// => executes the statement above; continues to next line
import com.example.order.domain.Order;                         // => domain type; not JPA entity
// => executes the statement above; continues to next line
import com.example.order.domain.OrderId;                       // => typed key; not raw String
// => executes the statement above; continues to next line
 
import java.util.HashMap;   // => JDK only; no JPA, no Spring Data, no JDBC
// => executes the statement above; continues to next line
import java.util.Map;       // => Map interface: used for store field type
// => executes the statement above; continues to next line
import java.util.Optional;  // => Optional: avoids returning null for missing entities
 
// InMemoryOrderRepository: adapter/out/persistence; implements output port with HashMap
// => Used in tests and local development; swapped for JPA adapter in production via DI config
public class InMemoryOrderRepository implements OrderRepository {
    // => implements: Java keyword; compiler verifies all port methods are present
    // => HashMap: mutable; thread-unsafe; sufficient for single-threaded tests
    private final Map<OrderId, Order> store = new HashMap<>();
    // => Map<OrderId, Order>: typed key prevents passing wrong ID kind at compile time
 
    @Override                                                       // => compiler enforces signature match with port interface
    // => @Override: compiler verifies this method signature matches the interface
    public Optional<Order> findById(OrderId id) {
        // => @Override: ensures method signature matches the interface contract exactly
        return Optional.ofNullable(store.get(id)); // => wraps null in Optional; safe caller API
        // => Optional.empty() returned when id is absent; consistent with JPA findById
    }
 
    @Override                                                       // => compiler error if port interface changes signature
    // => @Override: compiler verifies this method signature matches the interface
    public Order save(Order order) {
        // => @Override: compiler error if interface changes the signature
        store.put(order.id(), order); // => stores by typed OrderId key
        // => put: upsert semantics — inserts or replaces
        return order;                 // => returns same order; real adapter may enrich it
        // => returns the result to the caller — caller receives this value
    }
 
    @Override                                                       // => three @Override methods implement all port methods
    // => @Override: compiler verifies this method signature matches the interface
    public void delete(OrderId id) {
    // => delete: method entry point — see implementation below
        store.remove(id); // => removes entry; no-op if absent; consistent with DB behaviour
        // => returns null if key absent; void return matches interface
    }
}
// Test: new InMemoryOrderRepository() — zero setup; runs in microseconds
// => no application context, no Docker, no migration needed

package com.example.order.adapter.out.persistence
// => executes the statement above; continues to next line
 
import com.example.order.application.port.out.OrderRepository // => implements output port contract
// => executes the statement above; continues to next line
import com.example.order.domain.Order                         // => domain entity; not DB entity
// => executes the statement above; continues to next line
import com.example.order.domain.OrderId                       // => typed key
 
// InMemoryOrderRepository: Kotlin class implementing output port with mutableMapOf()
// => : OrderRepository confirms this class satisfies the output port contract at compile time
class InMemoryOrderRepository : OrderRepository {  // => implements output port
// => InMemoryOrderRepository implements output port — satisfies the port contract
    private val store = mutableMapOf<OrderId, Order>() // => mutableMapOf: backed by LinkedHashMap
    // => store : MutableMap<OrderId, Order> — keyed by typed identity
 
    override suspend fun findById(id: OrderId): Order? =
    // => executes the statement above; continues to next line
        store[id]  // => Kotlin map returns null for missing keys; suspend allows async swap later
    // => Order? : nullable; null means not found; consistent with Optional.empty() pattern
 
    override suspend fun save(order: Order): Order {
    // => save: method entry point — see implementation below
        store[order.id] = order // => indexed assignment; replaces existing entry if present
        // => upsert semantics: insert if new, replace if duplicate key
        return order            // => returns same order; interface contract fulfilled
        // => returns the result to the caller — caller receives this value
    }
 
    override suspend fun delete(id: OrderId) {
    // => delete: method entry point — see implementation below
        store.remove(id) // => returns removed value but we discard; unit return matches interface
        // => no-op if key absent; consistent with DELETE WHERE NOT EXISTS = no error
    }
}
// Test: InMemoryOrderRepository() — no coroutine dispatcher needed for pure map ops
// => instantiation is zero-cost; each test gets its own fresh instance

namespace Example.Order.Adapter.Out.Persistence;
// => executes the statement above; continues to next line
 
using Example.Order.Application.Port.Out; // => implements IOrderRepository
// => executes the statement above; continues to next line
using Example.Order.Domain;               // => domain types; not EF entities
// => executes the statement above; continues to next line
using System.Collections.Generic;
// => executes the statement above; continues to next line
using System.Threading.Tasks;
 
// InMemoryOrderRepository: adapter; implements IOrderRepository with Dictionary
// => No DbContext, no SqlConnection — purely in-process Dictionary
public class InMemoryOrderRepository : IOrderRepository  // => satisfies output port contract
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    private readonly Dictionary<OrderId, Order> _store = new(); // => in-process; no I/O
    // => _store : Dictionary<OrderId, Order> — keyed by typed identity; no table schema needed
 
    public Task<Order?> FindByIdAsync(OrderId id)
    // => executes the statement above; continues to next line
    {
    // => operation completes; execution continues to next statement
        _store.TryGetValue(id, out var order);       // => returns false+null if absent
        // => order : Order? — null when id not in dictionary
        return Task.FromResult(order);               // => Task.FromResult wraps synchronous result
        // => Task.FromResult: no async overhead; completed task returned immediately
    }
    // => operation completes; execution continues to next statement
 
    public Task<Order> SaveAsync(Order order)
    // => executes the statement above; continues to next line
    {
    // => operation completes; execution continues to next statement
        _store[order.Id] = order;                    // => indexed set; upsert semantics
        // => replaces existing entry if order.Id already present
        return Task.FromResult(order);               // => async interface; synchronous impl fine here
        // => returns the result to the caller — caller receives this value
    }
    // => operation completes; execution continues to next statement
 
    public Task DeleteAsync(OrderId id)
    // => executes the statement above; continues to next line
    {
    // => operation completes; execution continues to next statement
        _store.Remove(id);                           // => removes if present; no-op otherwise
        // => Dictionary.Remove: returns bool indicating whether key was found; ignored here
        return Task.CompletedTask;                   // => returns completed task for async interface
        // => returns the result to the caller — caller receives this value
    }
}
// Test: new InMemoryOrderRepository() — instantiate with no configuration; runs instantly
// => each test gets its own isolated instance; no shared state between tests

package com.example.order.adapter.out.persistence;             // => adapter zone: JPA allowed here
// => executes the statement above; continues to next line
 
import com.example.order.application.port.out.OrderRepository; // => implements output port
// => executes the statement above; continues to next line
import com.example.order.domain.Order;                         // => domain entity; no ORM annotations
// => executes the statement above; continues to next line
import com.example.order.domain.OrderId;                       // => typed id
// => executes the statement above; continues to next line
 
import jakarta.persistence.*;                                   // => JPA annotations: adapter zone only
// => executes the statement above; continues to next line
import org.springframework.stereotype.Repository;              // => Spring: adapter zone only
// => executes the statement above; continues to next line
import org.springframework.data.jpa.repository.JpaRepository;  // => Spring Data: adapter zone only
// => executes the statement above; continues to next line
import java.util.Optional;                                      // => Optional: no-null contract for findById
 
// JPA entity lives in adapter zone — NOT in domain zone
// => @Entity here is legitimate; domain.Order never has @Entity
@Entity @Table(name = "orders")                                 // => @Entity: marks persistence class; @Table maps to SQL table
// => @Entity: JPA maps this class to a database table — adapter zone only
class OrderJpaEntity {                                          // => private to adapter package; application zone never sees this
// => class OrderJpaEntity: implementation — contains field declarations and methods below
    @Id String id;               // => raw String for JPA; domain uses OrderId value object
    // => @Id: JPA primary key mapping — persistence adapter concern
    String customerId;           // => flat column; domain uses CustomerId value object
    // => executes the statement above; continues to next line
    java.math.BigDecimal total;  // => raw decimal; domain uses Money with currency
    // => executes the statement above; continues to next line
    String currency;             // => separate column; combined into Money in domain
    // => executes the statement above; continues to next line
    String status;               // => String; mapped to OrderStatus enum in domain
    // => executes the statement above; continues to next line
}                                                               // => five flat fields mirror five domain record components
 
// Spring Data repository: adapter implementation detail; not visible to application zone
// => extends JpaRepository<OrderJpaEntity, String>: Spring generates all CRUD methods at startup
interface OrderJpaEntityRepository extends JpaRepository<OrderJpaEntity, String> {}
// => OrderJpaEntityRepository extends JpaRepository<OrderJpaEntity — inherits base behaviour
 
@Repository                                                     // => Spring registers this bean; not visible beyond adapter zone
// => @Repository: Spring persistence component; exception translation applied
public class JpaOrderRepository implements OrderRepository {    // => implements application port; satisfies DI contract
// => JpaOrderRepository implements OrderRepository — satisfies the port contract
    private final OrderJpaEntityRepository jpa; // => Spring Data repository; adapter detail
    // => jpa: OrderJpaEntityRepository — final field; assigned once in constructor; immutable reference
 
    public JpaOrderRepository(OrderJpaEntityRepository jpa) {   // => constructor injection; no @Autowired field
    // => constructor: receives all dependencies — enables testing with any adapter implementation
        this.jpa = jpa;                                         // => stored; used in all three port methods
        // => this.jpa stored — field holds injected jpa for method calls below
    }
    // => operation completes; execution continues to next statement
 
    @Override                                                   // => implements OrderRepository.findById(OrderId)
    // => @Override: compiler verifies this method signature matches the interface
    public Optional<Order> findById(OrderId id) {
    // => executes the statement above; continues to next line
        return jpa.findById(id.value())         // => query by raw String id
        // => returns the result to the caller — caller receives this value
                  .map(this::toDomain);         // => map JPA entity → domain Order
                  // => method call: delegates to collaborator; result captured above
    }                                           // => returns Optional.empty() when not found
    // => method call: delegates to collaborator; result captured above
 
    @Override                                                   // => implements OrderRepository.save(Order)
    // => @Override: compiler verifies this method signature matches the interface
    public Order save(Order order) {
    // => save: method entry point — see implementation below
        var entity = toJpaEntity(order);        // => map domain Order → JPA entity
        // => entity: holds the result of the expression on the right
        var saved  = jpa.save(entity);          // => JPA persists; may generate id
        // => saved: holds the result of the expression on the right
        return toDomain(saved);                 // => map back to domain; return clean domain type
        // => returns the result to the caller — caller receives this value
    }
    // => operation completes; execution continues to next statement
 
    @Override                                                   // => implements OrderRepository.delete(OrderId)
    // => @Override: compiler verifies this method signature matches the interface
    public void delete(OrderId id) { jpa.deleteById(id.value()); } // => delegate to JPA; no-op if absent
 
    // Mapper: adapter-private; domain knows nothing about OrderJpaEntity
    // => two private methods: toDomain (JPA→domain) and toJpaEntity (domain→JPA)
    private Order toDomain(OrderJpaEntity e) {  // => reconstructs domain record from flat JPA fields
    // => record from: immutable value type; equals/hashCode/toString generated by compiler
        return new Order(
        // => returns the result to the caller — caller receives this value
            new OrderId(e.id),           // => wrap raw String in typed value object
            // => method call: delegates to collaborator; result captured above
            new CustomerId(e.customerId), // => wrap raw String in typed value object
            // => method call: delegates to collaborator; result captured above
            new Money(e.total, e.currency), // => combine two columns into Money
            // => method call: delegates to collaborator; result captured above
            OrderStatus.valueOf(e.status)   // => parse String to domain enum
            // => method call: delegates to collaborator; result captured above
        );
        // => operation completes; execution continues to next statement
    }
    private OrderJpaEntity toJpaEntity(Order o) { // => flattens domain record into five JPA columns
    // => record into: immutable value type; equals/hashCode/toString generated by compiler
        var e = new OrderJpaEntity();           // => creates empty JPA entity; fields set below
        // => e: holds the result of the expression on the right
        e.id = o.id().value();             // => unwrap typed id to raw String for JPA
        // => method call: delegates to collaborator; result captured above
        e.customerId = o.customerId().value(); // => unwrap typed id
        // => method call: delegates to collaborator; result captured above
        e.total = o.total().getAmount();   // => extract BigDecimal from Money
        // => method call: delegates to collaborator; result captured above
        e.currency = o.total().getCurrency(); // => extract currency String from Money
        // => method call: delegates to collaborator; result captured above
        e.status = o.status().name();      // => enum to String for database column
        // => method call: delegates to collaborator; result captured above
        return e;                          // => populated entity ready for JPA save
        // => returns the result to the caller — caller receives this value
    }
}
// => JpaOrderRepository is the ONLY class with JPA awareness; all other classes stay clean

package com.example.order.adapter.out.persistence
// => executes the statement above; continues to next line
// => above statement is part of the implementation flow
 
import com.example.order.application.port.out.OrderRepository // => implements output port
// => executes the statement above; continues to next line
import com.example.order.domain.*                             // => domain types
// => executes the statement above; continues to next line
import org.jetbrains.exposed.sql.*                            // => Exposed: adapter zone only
// => executes the statement above; continues to next line
import org.jetbrains.exposed.sql.transactions.transaction    // => Exposed transaction: adapter only
 
// Exposed table definition: adapter zone; domain.Order never references this object
object OrdersTable : Table("orders") {
    // => Table("orders"): maps this object to the 'orders' database table
    val id         = varchar("id", 50).primaryKey()  // => raw String column; maps to OrderId
    // => primaryKey(): marks id as the primary key constraint
    val customerId = varchar("customer_id", 50)      // => raw String; maps to CustomerId
    // => snake_case column name; Exposed maps to Kotlin property
    val total      = decimal("total", 15, 2)         // => raw BigDecimal; maps to Money.amount
    // => precision 15, scale 2; sufficient for most monetary values
    val currency   = varchar("currency", 3)          // => companion to total; maps to Money.currency
    // => ISO 4217 currency code; 3 chars (USD, EUR, etc.)
    val status     = varchar("status", 20)           // => String; maps to OrderStatus enum
    // => enum stored as String; adapter parses to domain OrderStatus
}
 
// ExposedOrderRepository: implements output port with Exposed SQL DSL
class ExposedOrderRepository : OrderRepository {  // => satisfies output port contract
// => class ExposedOrderRepository: implementation — contains field declarations and methods below
    override suspend fun findById(id: OrderId): Order? = transaction { // => transaction wraps SQL
        // => transaction: Exposed DSL; wraps query in a DB transaction
        OrdersTable.select { OrdersTable.id eq id.value }  // => DSL query; no SQL string
        // => id.value: unwrap typed OrderId to raw String for comparison
            .singleOrNull()?.let { toDomain(it) }          // => map ResultRow → domain Order
        // => singleOrNull: null if no row found; exception if multiple rows (bug)
    }
    // => operation completes; execution continues to next statement
 
    override suspend fun save(order: Order): Order = transaction {
        // => transaction: wraps upsert in a DB transaction for atomicity
        OrdersTable.upsert { row ->              // => INSERT OR UPDATE; adapter decides strategy
            // => upsert: handles both new and existing orders with one DSL call
            row[id]         = order.id.value     // => unwrap typed id to raw String
            // => executes the statement above; continues to next line
            row[customerId] = order.customerId.value // => unwrap typed id
            // => executes the statement above; continues to next line
            row[total]      = order.total.amount     // => extract BigDecimal from Money
            // => executes the statement above; continues to next line
            row[currency]   = order.total.currency   // => extract currency from Money
            // => executes the statement above; continues to next line
            row[status]     = order.status.name      // => enum to String
            // => executes the statement above; continues to next line
        }
        // => operation completes; execution continues to next statement
        order // => return domain Order; table holds the canonical state
        // => same domain Order returned; mapper round-trip only if needed
    }
    // => operation completes; execution continues to next statement
 
    override suspend fun delete(id: OrderId) = transaction {
        // => transaction: wraps delete in a DB transaction
        OrdersTable.deleteWhere { OrdersTable.id eq id.value } // => Exposed DSL delete
        // => deleteWhere: generates DELETE WHERE id = ? with parameterized value
        Unit // => explicit Unit return satisfies suspend fun signature
        // => executes the statement above; continues to next line
    }
    // => operation completes; execution continues to next statement
 
    private fun toDomain(row: ResultRow) = Order(
        // => pure mapping: ResultRow → domain Order; no I/O inside this function
        id         = OrderId(row[OrdersTable.id]),          // => wrap raw String in value object
        // => method call: delegates to collaborator; result captured above
        customerId = CustomerId(row[OrdersTable.customerId]), // => typed id
        // => method call: delegates to collaborator; result captured above
        total      = Money(row[OrdersTable.total], row[OrdersTable.currency]), // => reconstruct Money
        // => combines two columns back into the domain Money value object
        status     = OrderStatus.valueOf(row[OrdersTable.status]) // => parse enum from String column
        // => valueOf: throws if String not in enum; adapter should validate at write time
    )
    // => operation completes; execution continues to next statement
}
// => operation completes; execution continues to next statement

namespace Example.Order.Adapter.Out.Persistence;
// => executes the statement above; continues to next line
 
using Example.Order.Application.Port.Out; // => implements IOrderRepository
// => executes the statement above; continues to next line
using Example.Order.Domain;               // => domain types
// => executes the statement above; continues to next line
using Microsoft.EntityFrameworkCore;      // => EF Core: adapter zone only
// => executes the statement above; continues to next line
using System.Threading.Tasks;
 
// EF Core entity: adapter zone; domain.Order never has [Table] or [Column]
public class OrderDbEntity  // => POCO: plain class; EF Core maps it via fluent config
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    public string Id         { get; set; } = ""; // => raw String; maps to OrderId in domain
    // => executes the statement above; continues to next line
    public string CustomerId { get; set; } = ""; // => raw String; maps to CustomerId
    // => executes the statement above; continues to next line
    public decimal Total     { get; set; }        // => raw decimal; maps to Money.Amount
    // => executes the statement above; continues to next line
    public string Currency   { get; set; } = ""; // => companion to Total; maps to Money.Currency
    // => executes the statement above; continues to next line
    public string Status     { get; set; } = ""; // => String column; maps to OrderStatus enum
    // => enum type: closed set of domain values; exhaustive switch/when enforced
}
// => OrderDbEntity: has no knowledge of domain types; both sides have their own shape
 
// DbContext: adapter detail; application zone never references OrderDbContext
public class OrderDbContext : DbContext  // => EF Core context; adapter-private
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    public DbSet<OrderDbEntity> Orders => Set<OrderDbEntity>(); // => EF Core table mapping
    // => executes the statement above; continues to next line
    public OrderDbContext(DbContextOptions<OrderDbContext> opts) : base(opts) {} // => injected options
    // => constructor: receives all dependencies — enables testing with any adapter implementation
    protected override void OnModelCreating(ModelBuilder mb) =>
    // => executes the statement above; continues to next line
        mb.Entity<OrderDbEntity>().ToTable("orders").HasKey(e => e.Id); // => fluent config
    // => HasKey: sets primary key; no [Key] attribute needed on the entity class
}
 
// EfOrderRepository: implements IOrderRepository; never visible to application zone
public class EfOrderRepository : IOrderRepository  // => satisfies output port contract
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    private readonly OrderDbContext _ctx; // => EF context; injected; adapter-private
    // => _ctx: wraps connection pool and change tracker; one context per request (Scoped)
    public EfOrderRepository(OrderDbContext ctx) { _ctx = ctx; } // => constructor injection
    // => constructor: receives all dependencies — enables testing with any adapter implementation
 
    public async Task<Order?> FindByIdAsync(OrderId id)
    // => executes the statement above; continues to next line
    {
    // => operation completes; execution continues to next statement
        var entity = await _ctx.Orders.FindAsync(id.Value); // => EF async query by PK
        // => FindAsync: checks EF change tracker first (cache hit), then executes SQL
        return entity is null ? null : ToDomain(entity);    // => null-check then map to domain
        // => ToDomain: pure static mapper; no I/O inside
    }
    // => operation completes; execution continues to next statement
 
    public async Task<Order> SaveAsync(Order order)
    // => executes the statement above; continues to next line
    {
    // => operation completes; execution continues to next statement
        var entity = ToDbEntity(order);           // => map domain → EF entity
        // => entity : OrderDbEntity — EF-tracked object with raw columns
        _ctx.Orders.Update(entity);               // => EF tracks; insert or update
        // => Update: adds to change tracker as Modified; SQL issued at SaveChanges
        await _ctx.SaveChangesAsync();            // => flush to database
        // => SaveChangesAsync: executes all pending SQL in a transaction
        return order;                             // => return original domain order
        // => returns the result to the caller — caller receives this value
    }
    // => operation completes; execution continues to next statement
 
    public async Task DeleteAsync(OrderId id)
    // => executes the statement above; continues to next line
    {
    // => operation completes; execution continues to next statement
        var entity = await _ctx.Orders.FindAsync(id.Value); // => find before delete
        // => entity: holds the result of the expression on the right
        if (entity is not null) _ctx.Orders.Remove(entity); // => mark for deletion
        // => Remove: adds to change tracker as Deleted; SQL at SaveChanges
        await _ctx.SaveChangesAsync();                       // => flush deletion to DB
        // => method call: delegates to collaborator; result captured above
    }
    // => operation completes; execution continues to next statement
 
    private static Order ToDomain(OrderDbEntity e) => new(  // => static mapper: no I/O
    // => executes the statement above; continues to next line
        new OrderId(e.Id),
        // => wrap raw String in typed value object
        new CustomerId(e.CustomerId),
        // => executes the statement above; continues to next line
        new Money(e.Total, e.Currency),            // => reconstruct Money from two columns
        // => two DB columns → one domain value object
        Enum.Parse<OrderStatus>(e.Status));        // => parse enum from String column
    // => Enum.Parse: throws if String invalid; adapter validates at write time
 
    private static OrderDbEntity ToDbEntity(Order o) => new() // => static mapper: no I/O
    // => executes the statement above; continues to next line
    {
    // => operation completes; execution continues to next statement
        Id         = o.Id.Value,
        // => unwrap typed OrderId to raw String for EF column
        CustomerId = o.CustomerId.Value,
        // => executes the statement above; continues to next line
        Total      = o.Total.Amount,               // => unwrap Money to raw decimal
        // => executes the statement above; continues to next line
        Currency   = o.Total.Currency,             // => unwrap Money to currency String
        // => executes the statement above; continues to next line
        Status     = o.Status.ToString()           // => enum to String for DB column
        // => ToString(): produces enum member name (e.g., "CONFIRMED")
    };
    // => operation completes; execution continues to next statement
}
// => operation completes; execution continues to next statement

package com.example.order.adapter.in.web;
// => executes the statement above; continues to next line
 
import com.example.order.application.port.in.PlaceOrderUseCase; // => input port; injected
// => executes the statement above; continues to next line
import com.example.order.domain.UnvalidatedOrder;                // => domain input type
// => executes the statement above; continues to next line
import com.example.order.domain.PlacingOrderError;               // => domain error type
// => executes the statement above; continues to next line
 
import org.springframework.http.ResponseEntity;          // => HTTP concern: adapter zone only
// => executes the statement above; continues to next line
import org.springframework.web.bind.annotation.*;        // => Spring annotations: adapter only
// => executes the statement above; continues to next line
import java.util.List;
// => executes the statement above; continues to next line
 
@RestController                                          // => Spring adapter annotation
// => @RestController: HTTP adapter; maps requests to use-case calls
@RequestMapping("/orders")                               // => HTTP routing: adapter concern
// => HTTP mapping annotation: routes incoming request to this handler method
public class OrderController {
// => class OrderController: implementation — contains field declarations and methods below
    private final PlaceOrderUseCase placeOrderUseCase;   // => input port; not PlaceOrderService
 
    // => Constructor injection; Spring resolves PlaceOrderUseCase to PlaceOrderService
    public OrderController(PlaceOrderUseCase placeOrderUseCase) {
    // => constructor: receives all dependencies — enables testing with any adapter implementation
        this.placeOrderUseCase = placeOrderUseCase; // => stores interface reference; not impl class
        // => this.placeOrderUseCase stored — field holds injected placeOrderUseCase for method calls below
    }
    // => operation completes; execution continues to next statement
 
    @PostMapping                                         // => HTTP POST /orders
    // => HTTP mapping annotation: routes incoming request to this handler method
    public ResponseEntity<?> placeOrder(@RequestBody OrderRequestDto dto) {
        // => Step 1: map DTO → domain input; no logic; just field mapping
        var input = OrderRequestMapper.toDomain(dto);    // => adapter mapper: DTO → UnvalidatedOrder
 
        // => Step 2: delegate to use case; all logic lives in application + domain layers
        var result = placeOrderUseCase.placeOrder(input); // => calls input port interface
 
        // => Step 3: map result → HTTP response; no domain logic here
        return result.isSuccess()
        // => returns the result to the caller — caller receives this value
            ? ResponseEntity.status(201).body(OrderResponseMapper.toDto(result.getValue())) // => 201 Created
            // => method call: delegates to collaborator; result captured above
            : ResponseEntity.status(422).body(result.getError().getMessage());              // => 422 Unprocessable
            // => method call: delegates to collaborator; result captured above
    }
    // => operation completes; execution continues to next statement
}
// Controller: HTTP in → domain type → use case → domain result → HTTP out
// No Order, Money, or OrderStatus logic lives in this class

package com.example.order.adapter.`in`.web
// => executes the statement above; continues to next line
 
import com.example.order.application.port.`in`.PlaceOrderUseCase // => input port injected into route
// => executes the statement above; continues to next line
import io.ktor.server.application.*                               // => Ktor: adapter zone only
// => executes the statement above; continues to next line
import io.ktor.server.request.*                                   // => HTTP request: adapter concern
// => executes the statement above; continues to next line
import io.ktor.server.response.*                                  // => HTTP response: adapter concern
// => executes the statement above; continues to next line
import io.ktor.server.routing.*                                   // => routing DSL: adapter concern
// => executes the statement above; continues to next line
import io.ktor.http.*                                             // => HTTP status codes
 
// Ktor extension function: adds POST /orders route to Ktor routing
// => placeOrderUseCase injected at call site from DI container
fun Route.orderRoutes(placeOrderUseCase: PlaceOrderUseCase) {
    // => extension function on Route: follows Ktor routing DSL conventions
    post("/orders") {                                // => HTTP POST /orders; Ktor DSL
    // => executes the statement above; continues to next line
        val dto = call.receive<OrderRequestDto>()    // => deserialise JSON body to DTO
        // => dto : OrderRequestDto — framework-specific shape; carries raw JSON fields
        val input = OrderRequestMapper.toDomain(dto) // => map DTO → domain UnvalidatedOrder
        // => input : UnvalidatedOrder — domain type; all framework types stripped
 
        // => Delegate: all business rules in application + domain; route stays thin
        val result = placeOrderUseCase.placeOrder(input) // => calls input port; suspend-safe
        // => result : Result<List<OrderPlaced>> — domain result from application layer
 
        result.fold(
        // => executes the statement above; continues to next line
            onSuccess = { events ->                  // => success: map domain events to DTO list
                // => events : List<OrderPlaced> — domain events to serialize
                call.respond(HttpStatusCode.Created, events.map(OrderResponseMapper::toDto))
                // => HTTP 201 Created with response DTOs
            },
            // => operation completes; execution continues to next statement
            onFailure = { error ->                   // => failure: map domain error to HTTP 422
            // => executes the statement above; continues to next line
                call.respond(HttpStatusCode.UnprocessableEntity, error.message ?: "Order failed")
                // => HTTP 422 with error message; domain types not exposed
            }
            // => operation completes; execution continues to next statement
        )
        // => operation completes; execution continues to next statement
    }
}
// Route: Ktor-specific wiring; application service is framework-agnostic

namespace Example.Order.Adapter.In.Web;
// => executes the statement above; continues to next line
 
using Example.Order.Application.Port.In;  // => input port injected
// => executes the statement above; continues to next line
using Example.Order.Domain;               // => domain types for mapping
// => executes the statement above; continues to next line
using Microsoft.AspNetCore.Mvc;           // => ASP.NET: adapter zone only
// => executes the statement above; continues to next line
 
[ApiController]                           // => ASP.NET attribute: adapter zone
// => executes the statement above; continues to next line
[Route("orders")]                         // => HTTP routing: adapter concern
// => executes the statement above; continues to next line
public class OrderController : ControllerBase  // => inherits ASP.NET controller helpers
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    private readonly IPlaceOrderUseCase _placeOrderUseCase; // => input port; not concrete class
    // => IPlaceOrderUseCase: interface type; DI resolves to PlaceOrderService at runtime
 
    // => ASP.NET DI injects PlaceOrderService as IPlaceOrderUseCase at startup
    public OrderController(IPlaceOrderUseCase placeOrderUseCase)
    // => constructor: receives all dependencies — enables testing with any adapter implementation
    {
    // => operation completes; execution continues to next statement
        _placeOrderUseCase = placeOrderUseCase; // => interface reference stored; not impl type
        // => executes the statement above; continues to next line
    }
    // => operation completes; execution continues to next statement
 
    [HttpPost]                            // => HTTP POST /orders
    // => executes the statement above; continues to next line
    public async Task<IActionResult> PlaceOrder([FromBody] OrderRequestDto dto)
    // => executes the statement above; continues to next line
    {
        // => Step 1: map DTO → domain input; adapter mapper; no business logic here
        var input = OrderRequestMapper.ToDomain(dto); // => DTO → UnvalidatedOrder
        // => input : UnvalidatedOrder — domain type; no HTTP concern
 
        // => Step 2: delegate all logic to use case; controller stays thin
        var result = await _placeOrderUseCase.PlaceOrder(input); // => input port call
        // => result : OneOf<IReadOnlyList<OrderPlaced>, PlacingOrderError>
 
        // => Step 3: map result → IActionResult; domain types never appear in response body
        return result.Match(
        // => returns the result to the caller — caller receives this value
            events => CreatedAtAction(nameof(PlaceOrder), OrderResponseMapper.ToDto(events)), // => 201
            // => 201 Created with response DTO; domain OrderPlaced mapped to JSON shape
            error  => UnprocessableEntity(error.Message)  // => 422 with error message
            // => 422 Unprocessable; domain error message surfaced; no stack trace
        );
    }
}
// Controller: HTTP concern only; PlaceOrder logic lives in PlaceOrderService + domain

// ========================================================
// HEXAGONAL ARCHITECTURE NAMING CONVENTIONS — JAVA
// ========================================================
 
// INPUT PORTS (application/port/in/)
// => Interface names end with "UseCase"
// => One interface = one use case = one public method
interface PlaceOrderUseCase  { /* ... */ }  // => input port: use case contract
interface CancelOrderUseCase { /* ... */ }  // => input port: separate use case
 
// OUTPUT PORTS (application/port/out/)
// => Repository interfaces end with "Repository"
// => Non-CRUD output ports end with "Port"
interface OrderRepository    { /* ... */ }  // => output port: persistence contract
interface NotificationPort   { /* ... */ }  // => output port: notification contract
interface PaymentGatewayPort { /* ... */ }  // => output port: external payment contract
 
// APPLICATION SERVICE (application/service/)
// => Implements an input port; name ends with "Service"
class PlaceOrderService implements PlaceOrderUseCase { /* ... */ }  // => application service
 
// INPUT ADAPTERS (adapter/in/)
// => Web adapters end with "Controller" (REST) or "Consumer" (messaging)
class OrderController  { /* ... */ }  // => adapter/in/web: HTTP input adapter
class OrderConsumer    { /* ... */ }  // => adapter/in/messaging: Kafka/RabbitMQ input adapter
class OrderCliAdapter  { /* ... */ }  // => adapter/in/cli: command-line input adapter
 
// OUTPUT ADAPTERS (adapter/out/)
// => Persistence adapters end with "Repository" (concrete class, implements port)
// => Non-persistence adapters end with "Adapter"
class JpaOrderRepository      implements OrderRepository  { /* ... */ } // => persistence adapter
class SmtpNotificationAdapter implements NotificationPort { /* ... */ } // => notification adapter
class StripePaymentAdapter    implements PaymentGatewayPort { /* ... */ } // => payment adapter

// ========================================================
// HEXAGONAL ARCHITECTURE NAMING CONVENTIONS — KOTLIN
// ========================================================
 
// INPUT PORTS — application/port/in/ — same names as Java
interface PlaceOrderUseCase  // => Kotlin interface; no "I" prefix convention
// => executes the statement above; continues to next line
interface CancelOrderUseCase // => separate interface per use case
 
// OUTPUT PORTS — application/port/out/ — same names as Java
interface OrderRepository    // => output port; may use suspend fun for coroutines
// => executes the statement above; continues to next line
interface NotificationPort   // => output port; implemented by SMTP/SNS adapters
 
// APPLICATION SERVICE — application/service/
// => Kotlin: "class X : InterfaceName" syntax
class PlaceOrderService(                             // => primary constructor = injection
// => constructor: receives all dependencies — enables testing with any adapter implementation
    private val orderRepository: OrderRepository,   // => output port injected
    // => executes the statement above; continues to next line
    private val notificationPort: NotificationPort  // => output port injected
    // => executes the statement above; continues to next line
) : PlaceOrderUseCase { /* ... */ }                 // => colon syntax; implements input port
 
// INPUT ADAPTERS — adapter/in/
// => Ktor: route extension function, not a class; name ends with "Routes"
fun Route.orderRoutes(uc: PlaceOrderUseCase) { /* ... */ } // => Ktor convention
// => method call: delegates to collaborator; result captured above
class OrderConsumer(uc: PlaceOrderUseCase) { /* ... */ }   // => Kafka consumer adapter
 
// OUTPUT ADAPTERS — adapter/out/
class ExposedOrderRepository : OrderRepository { /* ... */ } // => Exposed adapter
// => class ExposedOrderRepository: implementation — contains field declarations and methods below
class SesNotificationAdapter : NotificationPort { /* ... */ } // => AWS SES adapter
// => class SesNotificationAdapter: implementation — contains field declarations and methods below

// ========================================================
// HEXAGONAL ARCHITECTURE NAMING CONVENTIONS — C#
// ========================================================
 
// INPUT PORTS — Application/Port/In/ — C# prefixes interfaces with "I"
interface IPlaceOrderUseCase  { }  // => input port; I prefix; one method
// => interface IPlaceOrderUseCase: contract definition — no implementation details here
interface ICancelOrderUseCase { }  // => separate interface per use case
 
// OUTPUT PORTS — Application/Port/Out/
interface IOrderRepository    { }  // => output port: persistence contract
// => interface IOrderRepository: contract definition — no implementation details here
interface INotificationPort   { }  // => output port: notification contract
// => interface INotificationPort: contract definition — no implementation details here
interface IPaymentGatewayPort { }  // => output port: payment gateway contract
 
// APPLICATION SERVICE — Application/Service/
// => Implements input port interface; no ASP.NET attributes
class PlaceOrderService : IPlaceOrderUseCase    // => service implements input port
// => executes the statement above; continues to next line
{
    public PlaceOrderService(IOrderRepository repo, INotificationPort notif) { } // => ctor injection
    // => constructor: receives all dependencies — enables testing with any adapter implementation
}
 
// INPUT ADAPTERS — Adapter/In/
[ApiController] class OrderController : ControllerBase { } // => ASP.NET controller: input adapter
// => class OrderController: implementation — contains field declarations and methods below
class OrderConsumer { }   // => MassTransit/RabbitMQ consumer: input adapter
// => class OrderConsumer: implementation — contains field declarations and methods below
class OrderCliAdapter { } // => CLI input adapter using System.CommandLine
 
// OUTPUT ADAPTERS — Adapter/Out/
class EfOrderRepository   : IOrderRepository    { } // => EF Core persistence adapter
// => class EfOrderRepository: implementation — contains field declarations and methods below
class SmtpNotificationAdapter : INotificationPort { } // => SMTP notification adapter
// => class SmtpNotificationAdapter: implementation — contains field declarations and methods below
class StripePaymentAdapter : IPaymentGatewayPort  { } // => Stripe payment adapter
// => class StripePaymentAdapter: implementation — contains field declarations and methods below

// ─── domain/ ────────────────────────────────────────────────────────────────
// com.example.order.domain.Order — entity; zero framework imports
package com.example.order.domain;
// com.example.order.domain.OrderId — value object; wraps String
public record OrderId(String value) {}
// com.example.order.domain.Money — value object; amount + currency
public record Money(java.math.BigDecimal amount, String currency) {}
// com.example.order.domain.PlacingOrderError — sealed error hierarchy
// com.example.order.domain.Order — aggregate; holds id + money
public record Order(OrderId id, Money total) {}
 
// ─── application/port/in/ ────────────────────────────────────────────────────
// com.example.order.application.port.in.PlaceOrderUseCase — input port interface
package com.example.order.application.port.in;
// => input port: HTTP adapter calls this; domain types only in signature
interface PlaceOrderUseCase { OrderId placeOrder(String customerId, Money total); }
 
// ─── application/port/out/ ───────────────────────────────────────────────────
// com.example.order.application.port.out.OrderRepository — output port interface
package com.example.order.application.port.out;
interface OrderRepository { void save(Order order); }
// com.example.order.application.port.out.NotificationPort — output port interface
interface NotificationPort { void sendConfirmation(OrderId id, String email); }
 
// ─── application/service/ ────────────────────────────────────────────────────
// com.example.order.application.service.PlaceOrderService — implements PlaceOrderUseCase
package com.example.order.application.service;
// => PlaceOrderService: application zone; imports domain + port/in + port/out only
class PlaceOrderService implements PlaceOrderUseCase {
// => implements PlaceOrderUseCase — satisfies the input port contract
    public OrderId placeOrder(String customerId, Money total) { return new OrderId(customerId); }
// => adapter zone never imported here; PlaceOrderService is unaware of JPA or Spring
}
 
// ─── adapter/in/web/ ─────────────────────────────────────────────────────────
// com.example.order.adapter.in.web.OrderController — Spring @RestController
package com.example.order.adapter.in.web;
// com.example.order.adapter.in.web.OrderRequestDto — JSON-deserializable input DTO
public record OrderRequestDto(String customerId, java.math.BigDecimal amount) {}
// com.example.order.adapter.in.web.OrderRequestMapper — DTO → UnvalidatedOrder
// com.example.order.adapter.in.web.OrderResponseDto — JSON-serializable response DTO
public record OrderResponseDto(String orderId) {}
// com.example.order.adapter.in.web.OrderResponseMapper — OrderPlaced → OrderResponseDto
 
// ─── adapter/out/persistence/ ────────────────────────────────────────────────
// com.example.order.adapter.out.persistence.JpaOrderRepository — implements OrderRepository
package com.example.order.adapter.out.persistence;
// com.example.order.adapter.out.persistence.OrderJpaEntity — @Entity class; JPA mapping
// com.example.order.adapter.out.persistence.InMemoryOrderRepository — test adapter
class InMemoryOrderRepository implements OrderRepository {
// => test adapter: HashMap-backed; no JPA; swapped for JpaOrderRepository in production
    private final java.util.Map<String, Order> store = new java.util.HashMap<>();
    public void save(Order order) { store.put(order.id().value(), order); }
// => save delegates to HashMap.put — no network, no transaction manager
}
 
// Rule: any import that crosses a zone boundary inward → compile error
// => domain/* never imports application/* or adapter/*
// => application/* never imports adapter/*

package com.example.order.adapter.in.web;
// => executes the statement above; continues to next line
 
import com.fasterxml.jackson.annotation.JsonProperty; // => Jackson: adapter zone only
// => executes the statement above; continues to next line
import com.example.order.domain.UnvalidatedOrder;     // => domain input type
// => executes the statement above; continues to next line
import com.example.order.domain.OrderLineInput;        // => domain input for a line item
// => executes the statement above; continues to next line
import java.util.List;
 
// OrderRequestDto: adapter zone; carries raw JSON fields; all primitives/Strings
// => @JsonProperty maps snake_case JSON to camelCase Java fields
public record OrderRequestDto(
// => executes the statement above; continues to next line
    @JsonProperty("customer_id") String customerId, // => raw String; not CustomerId value object
    // => annotation marks metadata for framework or compiler
    @JsonProperty("line_items")  List<LineItemDto> lineItems // => list of nested DTOs
    // => annotation marks metadata for framework or compiler
) {}
 
public record LineItemDto(
// => executes the statement above; continues to next line
    @JsonProperty("product_id") String productId,   // => raw String; not ProductId
    // => annotation marks metadata for framework or compiler
    int quantity                                    // => raw int; not Quantity value object
    // => executes the statement above; continues to next line
) {}
 
// Mapper: adapter-private; translates DTO → domain input type
// => Lives in adapter zone; domain UnvalidatedOrder never imports this mapper
class OrderRequestMapper {
// => class OrderRequestMapper: implementation — contains field declarations and methods below
    static UnvalidatedOrder toDomain(OrderRequestDto dto) {
        // => Map each raw field to its corresponding domain type
        var lines = dto.lineItems().stream()
        // => lines: holds the result of the expression on the right
            .map(item -> new OrderLineInput(
            // => executes the statement above; continues to next line
                new ProductId(item.productId()), // => wrap raw String in typed value object
                // => method call: delegates to collaborator; result captured above
                new Quantity(item.quantity())    // => wrap raw int in validated domain type
                // => method call: delegates to collaborator; result captured above
            ))
            .toList();
        // => CustomerId wraps raw String; domain validates further downstream
        return new UnvalidatedOrder(new CustomerId(dto.customerId()), lines);
        // => returns the result to the caller — caller receives this value
    }
}
// Rule: UnvalidatedOrder has no @JsonProperty; Jackson cannot deserialise it directly
// => DTO is the Jackson target; mapper bridges to domain type

package com.example.order.adapter.`in`.web
// => executes the statement above; continues to next line
 
import kotlinx.serialization.SerialName    // => kotlinx.serialization: adapter zone only
// => executes the statement above; continues to next line
import kotlinx.serialization.Serializable  // => framework annotation: adapter zone only
// => executes the statement above; continues to next line
import com.example.order.domain.*          // => domain input types for mapper output
 
// OrderRequestDto: adapter DTO; @Serializable drives Ktor content negotiation
// => @SerialName maps JSON snake_case to Kotlin camelCase field names
@Serializable                         // => framework annotation: adapter zone only
// => annotation marks metadata for framework or compiler
data class OrderRequestDto(
// => data class OrderRequestDto: value type; copy/equals/hashCode/toString auto-generated
    @SerialName("customer_id") val customerId: String,      // => raw String; not CustomerId
    // => String: JSON primitive; domain wraps it in CustomerId value object
    @SerialName("line_items")  val lineItems: List<LineItemDto> // => list of nested DTOs
    // => List<LineItemDto>: adapter type; domain receives List<OrderLineInput>
)
// => operation completes; execution continues to next statement
 
@Serializable                         // => each nested DTO also needs @Serializable
// => annotation marks metadata for framework or compiler
data class LineItemDto(
// => data class LineItemDto: value type; copy/equals/hashCode/toString auto-generated
    @SerialName("product_id") val productId: String,  // => raw String field from JSON
    // => productId: domain wraps in ProductId value object in mapper
    val quantity: Int                                  // => raw Int; not Quantity value object
    // => Int: JSON number; domain validates via Quantity constructor
)
 
// Mapper: adapter-private object; translates DTO → domain UnvalidatedOrder
object OrderRequestMapper {
    // => companion object pattern; no instantiation needed
    fun toDomain(dto: OrderRequestDto): UnvalidatedOrder {
    // => toDomain: method entry point — see implementation below
        val lines = dto.lineItems.map { item ->
            // => map: transforms each LineItemDto to OrderLineInput domain type
            OrderLineInput(
            // => executes the statement above; continues to next line
                productId = ProductId(item.productId), // => wrap raw String in domain type
                // => method call: delegates to collaborator; result captured above
                quantity  = Quantity(item.quantity)    // => wrap raw Int in validated type
                // => method call: delegates to collaborator; result captured above
            )
            // => operation completes; execution continues to next statement
        }
        // => lines : List<OrderLineInput> — typed domain inputs; raw values wrapped
        return UnvalidatedOrder(
        // => returns the result to the caller — caller receives this value
            customerId = CustomerId(dto.customerId),   // => wrap raw String in domain type
            // => method call: delegates to collaborator; result captured above
            lines      = lines
            // => domain type carries typed value objects; adapter concern stripped
        )
        // => operation completes; execution continues to next statement
    }
}
// Kotlin note: @Serializable on data class is adapter concern; domain types never have it
// => domain UnvalidatedOrder has no @Serializable; cannot be deserialized by Ktor directly

namespace Example.Order.Adapter.In.Web;
// => executes the statement above; continues to next line
 
using System.Text.Json.Serialization; // => JSON attribute: adapter zone only
// => executes the statement above; continues to next line
using Example.Order.Domain;           // => domain input types for mapper output
 
// OrderRequestDto: JSON-deserialisable DTO; [JsonPropertyName] handles snake_case
// => record type: immutable; init-only; clean construction
public record OrderRequestDto(
// => executes the statement above; continues to next line
    [property: JsonPropertyName("customer_id")] string CustomerId, // => raw String; not CustomerId VO
    // => [property: ...]: C# target specification for record primary constructor parameters
    [property: JsonPropertyName("line_items")]  IReadOnlyList<LineItemDto> LineItems // => nested DTOs
    // => IReadOnlyList: JSON array deserializes to this; prevents mutation after construction
);
 
public record LineItemDto(
// => executes the statement above; continues to next line
    [property: JsonPropertyName("product_id")] string ProductId, // => raw String from JSON
    // => ProductId: raw string; domain wraps in ProductId value object in mapper
    int Quantity                                                  // => raw int; not Quantity VO
    // => int: JSON number; domain validates via Quantity constructor
);
 
// Static mapper: adapter layer; translates DTO → UnvalidatedOrder domain input
public static class OrderRequestMapper
// => executes the statement above; continues to next line
{
    // => static class: no instantiation; all methods are utility functions
    public static UnvalidatedOrder ToDomain(OrderRequestDto dto)
    // => executes the statement above; continues to next line
    {
        var lines = dto.LineItems.Select(item => new OrderLineInput(
        // => lines: holds the result of the expression on the right
            new ProductId(item.ProductId), // => wrap raw String in typed ProductId
            // => method call: delegates to collaborator; result captured above
            new Quantity(item.Quantity)    // => wrap raw int in validated Quantity
            // => method call: delegates to collaborator; result captured above
        )).ToList();
        // => lines : List<OrderLineInput> — domain types; raw values wrapped and validated
        // => UnvalidatedOrder receives typed domain value objects; not raw strings
        return new UnvalidatedOrder(new CustomerId(dto.CustomerId), lines);
        // => UnvalidatedOrder: domain input type; no JSON annotation; domain is clean
    }
}
// C# note: [JsonPropertyName] on record properties requires property: target prefix
// => Domain UnvalidatedOrder has no JSON attributes; cannot be deserialised by ASP.NET directly

package com.example.order.adapter.in.web;
// => executes the statement above; continues to next line
 
import com.fasterxml.jackson.annotation.JsonProperty; // => Jackson: adapter zone; domain never imports this
// => executes the statement above; continues to next line
import com.example.order.domain.OrderPlaced;          // => domain event; no JSON annotation on it
// => executes the statement above; continues to next line
 
import java.util.List;
 
// OrderResponseDto: adapter zone; JSON-serialisable representation of OrderPlaced domain event
// => All fields are primitives or Strings; no domain value objects in the response body
public record OrderResponseDto(
// => executes the statement above; continues to next line
    @JsonProperty("order_id")    String orderId,    // => unwrapped from OrderId value object
    // => annotation marks metadata for framework or compiler
    @JsonProperty("customer_id") String customerId, // => unwrapped from CustomerId value object
    // => annotation marks metadata for framework or compiler
    @JsonProperty("status")      String status      // => String representation of OrderStatus
    // => annotation marks metadata for framework or compiler
) {}
 
// Mapper: adapter-private; translates domain event → HTTP response DTO
// => OrderPlaced has no DTO import; this mapper is the only coupling between them
class OrderResponseMapper {
    // => Accepts domain event list; returns DTO list for JSON serialisation
    static List<OrderResponseDto> toDto(List<OrderPlaced> events) {
    // => executes the statement above; continues to next line
        return events.stream()
        // => returns the result to the caller — caller receives this value
            .map(event -> new OrderResponseDto(
            // => executes the statement above; continues to next line
                event.orderId().value(),      // => unwrap typed OrderId to raw String
                // => method call: delegates to collaborator; result captured above
                event.customerId().value(),    // => unwrap typed CustomerId to raw String
                // => method call: delegates to collaborator; result captured above
                event.status().name()          // => enum.name() → "PLACED" String
                // => method call: delegates to collaborator; result captured above
            ))
            .toList();
            // => method call: delegates to collaborator; result captured above
    }
}
// Domain OrderPlaced: no toJson(), no @JsonProperty, no Jackson dependency
// => Adding a new JSON field requires only changing OrderResponseDto + mapper, not domain

package com.example.order.adapter.`in`.web
// => executes the statement above; continues to next line
 
import kotlinx.serialization.SerialName    // => kotlinx.serialization: adapter zone only
// => executes the statement above; continues to next line
import kotlinx.serialization.Serializable  // => serialisation annotation: adapter zone
// => executes the statement above; continues to next line
import com.example.order.domain.OrderPlaced // => domain event; no @Serializable on it
 
// OrderResponseDto: @Serializable drives Ktor JSON serialisation; adapter zone only
@Serializable                          // => @Serializable: framework annotation; adapter zone only
// => annotation marks metadata for framework or compiler
data class OrderResponseDto(
// => data class OrderResponseDto: value type; copy/equals/hashCode/toString auto-generated
    @SerialName("order_id")    val orderId: String,    // => unwrapped from OrderId
    // => String: JSON string; domain OrderId value object unwrapped by mapper
    @SerialName("customer_id") val customerId: String, // => unwrapped from CustomerId
    // => String: JSON string; domain CustomerId value object unwrapped by mapper
    @SerialName("status")      val status: String      // => enum.name from OrderStatus
    // => String: domain enum name; e.g. "PLACED"; adapter formats for JSON
)
 
// Mapper object: adapter zone; domain OrderPlaced has no reference to OrderResponseDto
object OrderResponseMapper {
    // => singleton object: no instantiation; pure adapter logic
    fun toDto(events: List<OrderPlaced>): List<OrderResponseDto> =
        // => List<OrderPlaced> → List<OrderResponseDto>: domain → adapter format
        events.map { event ->
            // => map: transforms each domain event to a response DTO
            OrderResponseDto(
            // => executes the statement above; continues to next line
                orderId    = event.orderId.value,     // => unwrap typed id to raw String
                // => .value: exposes the raw String inside the OrderId value object
                customerId = event.customerId.value,  // => unwrap typed id to raw String
                // => executes the statement above; continues to next line
                status     = event.status.name        // => Kotlin enum.name property
                // => .name: returns "PLACED" for OrderStatus.PLACED enum value
            )
            // => operation completes; execution continues to next statement
        }
        // => operation completes; execution continues to next statement
}
// Kotlin note: domain data class OrderPlaced uses val properties; mapper accesses them directly
// => No Jackson required; kotlinx.serialization handles DTO; domain is framework-free

namespace Example.Order.Adapter.In.Web;
// => executes the statement above; continues to next line
 
using System.Text.Json.Serialization; // => JSON attribute: adapter zone only
// => executes the statement above; continues to next line
using System.Collections.Generic;
// => executes the statement above; continues to next line
using Example.Order.Domain;           // => domain event type; no reverse import
 
// OrderResponseDto: JSON-serialisable; [JsonPropertyName] handles snake_case
public record OrderResponseDto(
// => executes the statement above; continues to next line
    [property: JsonPropertyName("order_id")]    string OrderId,    // => unwrapped from OrderId VO
    // => string: raw JSON type; domain value object unwrapped by mapper
    [property: JsonPropertyName("customer_id")] string CustomerId, // => unwrapped from CustomerId VO
    // => string: raw JSON type; domain value object unwrapped by mapper
    [property: JsonPropertyName("status")]      string Status      // => enum.ToString() result
    // => string: e.g. "Placed"; domain enum serialised by mapper
);
// => OrderResponseDto: no domain import needed on the record itself; mapper bridges
 
// Static mapper: adapter-private; maps domain events to response DTOs
// => OrderPlaced record never imports OrderResponseDto; direction is adapter → domain only
public static class OrderResponseMapper
// => executes the statement above; continues to next line
{
    // => static class: all methods are utility functions; no state
    public static IReadOnlyList<OrderResponseDto> ToDto(IReadOnlyList<OrderPlaced> events) =>
        // => IReadOnlyList<OrderPlaced> → IReadOnlyList<OrderResponseDto>
        events.Select(e => new OrderResponseDto(
        // => method call: delegates to collaborator; result captured above
            OrderId:    e.OrderId.Value,     // => unwrap typed OrderId to raw String
            // => .Value: exposes the raw string inside the OrderId record
            CustomerId: e.CustomerId.Value,  // => unwrap typed CustomerId to raw String
            // => executes the statement above; continues to next line
            Status:     e.Status.ToString()  // => C# enum.ToString() → "Placed"
            // => ToString(): produces enum member name; consistent for any status value
        )).ToList();
    // => .ToList(): materialises the LINQ query; returns read-only list to caller
}
// C# note: record positional parameters with [property:] target for JSON attributes
// => Domain OrderPlaced record remains free of System.Text.Json dependency

package com.example.order.adapter.config; // => config lives in adapter zone; knows all layers
// => executes the statement above; continues to next line
 
import com.example.order.application.port.in.PlaceOrderUseCase;   // => input port interface
// => executes the statement above; continues to next line
import com.example.order.application.port.out.OrderRepository;    // => output port interface
// => executes the statement above; continues to next line
import com.example.order.application.port.out.NotificationPort;   // => output port interface
// => executes the statement above; continues to next line
import com.example.order.application.service.PlaceOrderService;   // => application service (impl)
// => method call: delegates to collaborator; result captured above
import com.example.order.adapter.out.persistence.JpaOrderRepository;    // => concrete adapter
// => executes the statement above; continues to next line
import com.example.order.adapter.out.notification.SmtpNotificationAdapter; // => concrete adapter
// => executes the statement above; continues to next line
 
import org.springframework.context.annotation.Bean;          // => Spring DI: config zone only
// => executes the statement above; continues to next line
import org.springframework.context.annotation.Configuration; // => Spring config annotation
// => executes the statement above; continues to next line
 
@Configuration // => tells Spring this class provides @Bean definitions
// => @Configuration: Spring meta-annotation — marks this as configuration entry point
public class OrderBeanConfig {
 
    // => @Bean: Spring registers PlaceOrderService under PlaceOrderUseCase type
    // => Controllers and other consumers receive PlaceOrderUseCase; never PlaceOrderService
    @Bean
    // => @Bean: Spring manages lifecycle; returned instance is injected wherever type is requested
    public PlaceOrderUseCase placeOrderUseCase(
    // => executes the statement above; continues to next line
        OrderRepository orderRepository,       // => Spring injects JpaOrderRepository here
        // => executes the statement above; continues to next line
        NotificationPort notificationPort      // => Spring injects SmtpNotificationAdapter here
        // => executes the statement above; continues to next line
    ) {
    // => code line executes; see surrounding context for purpose
        return new PlaceOrderService(orderRepository, notificationPort); // => wires service
        // => returns the result to the caller — caller receives this value
    }
 
    // => Concrete adapters declared here; application service never knows these names
    @Bean public OrderRepository orderRepository(/* JPA deps */) {
    // => @Bean: Spring manages lifecycle; returned instance is injected wherever type is requested
        return new JpaOrderRepository(/* ... */); // => concrete adapter; only config knows it
        // => returns the result to the caller — caller receives this value
    }
    @Bean public NotificationPort notificationPort() {
    // => @Bean: Spring manages lifecycle; returned instance is injected wherever type is requested
        return new SmtpNotificationAdapter(/* ... */); // => concrete adapter; only config knows it
        // => returns the result to the caller — caller receives this value
    }
}
// To swap persistence: replace JpaOrderRepository with another impl in this config only
// => Zero changes in PlaceOrderService, OrderController, or domain classes

package com.example.order.adapter.config
// => executes the statement above; continues to next line
 
import com.example.order.application.port.`in`.PlaceOrderUseCase  // => input port
// => executes the statement above; continues to next line
import com.example.order.application.port.out.OrderRepository     // => output port
// => executes the statement above; continues to next line
import com.example.order.application.port.out.NotificationPort    // => output port
// => executes the statement above; continues to next line
import com.example.order.application.service.PlaceOrderService    // => service implementation
// => executes the statement above; continues to next line
import com.example.order.adapter.out.persistence.ExposedOrderRepository    // => concrete adapter
// => executes the statement above; continues to next line
import com.example.order.adapter.out.notification.SesNotificationAdapter   // => concrete adapter
// => executes the statement above; continues to next line
 
import org.koin.dsl.module // => Koin DI: adapter/config zone only
 
// Koin module: assembles hexagon; concrete classes only appear here
val orderModule = module {
    // => single<Interface> { ConcreteClass(...) } registers singleton by interface type
    single<OrderRepository>  { ExposedOrderRepository() }        // => output port → concrete adapter
    // => executes the statement above; continues to next line
    single<NotificationPort> { SesNotificationAdapter(get()) }   // => get() resolves dependency
 
    // => PlaceOrderService receives interfaces; Koin resolves them from above declarations
    single<PlaceOrderUseCase> { PlaceOrderService(get(), get()) } // => get() = OrderRepository + NotificationPort
    // => executes the statement above; continues to next line
}
// Swap test adapters: use koin-test module { single<OrderRepository> { InMemoryOrderRepository() } }
// => Application service code unchanged; only this module changes

// Program.cs: composition root; concrete adapters registered against interface types
// => This file is the only place in the codebase where concrete adapter class names appear
 
using Example.Order.Application.Port.In;   // => IPlaceOrderUseCase interface
// => executes the statement above; continues to next line
using Example.Order.Application.Port.Out;  // => IOrderRepository, INotificationPort interfaces
// => executes the statement above; continues to next line
using Example.Order.Application.Service;   // => PlaceOrderService concrete class
// => executes the statement above; continues to next line
using Example.Order.Adapter.Out.Persistence;  // => EfOrderRepository concrete class
// => executes the statement above; continues to next line
using Example.Order.Adapter.Out.Notification; // => SmtpNotificationAdapter concrete class
// => executes the statement above; continues to next line
 
var builder = WebApplication.CreateBuilder(args);
 
// => Register output port adapters: resolve IOrderRepository → EfOrderRepository at runtime
builder.Services.AddScoped<IOrderRepository,   EfOrderRepository>();    // => persistence adapter
// => method call: delegates to collaborator; result captured above
builder.Services.AddScoped<INotificationPort,  SmtpNotificationAdapter>(); // => notification adapter
 
// => Register application service: resolves input port → service which receives output ports
builder.Services.AddScoped<IPlaceOrderUseCase, PlaceOrderService>();    // => DI injects adapters above
// => method call: delegates to collaborator; result captured above
 
builder.Services.AddControllers(); // => registers OrderController; receives IPlaceOrderUseCase
// => method call: delegates to collaborator; result captured above
 
var app = builder.Build();
// => app : WebApplication — resolved with all registered services
app.MapControllers();
// => method call: delegates to collaborator; result captured above
app.Run();
 
// Swap for tests: builder.Services.AddScoped<IOrderRepository, InMemoryOrderRepository>()
// => No changes anywhere except Program.cs; all other files untouched

// ANTI-PATTERN: domain.Order imports jakarta.persistence.*
// => package com.example.order.domain — this import is the violation
import jakarta.persistence.Entity;            // => JPA in domain: VIOLATION
// => executes the statement above; continues to next line
import jakarta.persistence.Id;               // => JPA in domain: VIOLATION
// => executes the statement above; continues to next line
import jakarta.persistence.Table;            // => JPA in domain: VIOLATION
// => executes the statement above; continues to next line
import jakarta.persistence.Column;           // => JPA in domain: VIOLATION
 
// Domain entity now depends on JPA jar; cannot run without it
@Entity                                      // => JPA annotation on domain class: VIOLATION
// => @Entity: JPA maps this class to a database table — adapter zone only
@Table(name = "orders")                      // => database table name in domain: VIOLATION
// => persistence mapping annotation: adapter zone concern; domain is unaware
public class Order {
// => class Order: implementation — contains field declarations and methods below
    @Id
    // => @Id: JPA primary key mapping — persistence adapter concern
    @Column(name = "order_id")              // => column name in domain: VIOLATION
    // => persistence mapping annotation: adapter zone concern; domain is unaware
    private String id;                       // => raw String; typed OrderId discarded
    // => id: String — injected dependency; implementation chosen at wiring time
 
    @Column(name = "customer_id")           // => adapter concern in domain: VIOLATION
    // => persistence mapping annotation: adapter zone concern; domain is unaware
    private String customerId;              // => raw String; typed CustomerId discarded
 
    // Problem 1: cannot test Order without JPA context — 10x slower tests
    // Problem 2: renaming DB column requires editing domain class
    // Problem 3: domain tied to JPA forever; cannot swap to Exposed or JDBC without domain change
}

// ─── domain.Order: zero framework imports ────────────────────────────────────
// => package com.example.order.domain
// => Compiles with JDK only; tests run without JPA on classpath
public record Order(
// => executes the statement above; continues to next line
    OrderId id,            // => typed value object; no JPA awareness
    // => executes the statement above; continues to next line
    CustomerId customerId, // => typed value object; no JPA awareness
    // => executes the statement above; continues to next line
    Money total,           // => domain value object; no column annotations
    // => executes the statement above; continues to next line
    OrderStatus status     // => domain enum; no framework dependency
    // => executes the statement above; continues to next line
) {}
 
// ─── adapter.out.persistence.OrderJpaEntity: JPA annotations here only ───────
// => package com.example.order.adapter.out.persistence
// => Domain never imports this class; adapter imports domain via mapper
import jakarta.persistence.*; // => JPA: legitimately in adapter zone
// => executes the statement above; continues to next line
 
@Entity @Table(name = "orders")
// => @Entity: JPA maps this class to a database table — adapter zone only
class OrderJpaEntity {
// => class OrderJpaEntity: implementation — contains field declarations and methods below
    @Id @Column(name = "order_id")     String id;         // => raw String; JPA requirement
    // => @Id: JPA primary key mapping — persistence adapter concern
    @Column(name = "customer_id")      String customerId; // => raw String; JPA column
    // => persistence mapping annotation: adapter zone concern; domain is unaware
    @Column(name = "total_amount")     java.math.BigDecimal total; // => flat column
    // => persistence mapping annotation: adapter zone concern; domain is unaware
    @Column(name = "currency")         String currency;   // => companion to total
    // => persistence mapping annotation: adapter zone concern; domain is unaware
    @Column(name = "status")           String status;     // => String enum value
    // => persistence mapping annotation: adapter zone concern; domain is unaware
}
// Mapper between Order ↔ OrderJpaEntity lives in JpaOrderRepository (see Example 8)
// Benefit: renaming DB column edits only OrderJpaEntity; domain.Order untouched

// ANTI-PATTERN: domain.Order with JPA annotations
// => package com.example.order.domain
import jakarta.persistence.Entity // => VIOLATION: JPA in domain package
// => executes the statement above; continues to next line
 
@Entity                           // => VIOLATION: ORM annotation on domain class
// => @Entity: JPA maps this class to a database table — adapter zone only
data class Order(
// => data class Order: value type; copy/equals/hashCode/toString auto-generated
    @jakarta.persistence.Id       // => VIOLATION: JPA @Id on domain field
    // => @Id: JPA primary key mapping — persistence adapter concern
    val id: String,               // => raw String; typed OrderId lost
    // => executes the statement above; continues to next line
    val customerId: String        // => raw String; no type safety
    // => executes the statement above; continues to next line
)
 
// CORRECT: domain.Order is plain data class; JPA entity is separate class in adapter
// => package com.example.order.domain
data class Order(
// => data class Order: value type; copy/equals/hashCode/toString auto-generated
    val id: OrderId,              // => typed; framework-free
    // => executes the statement above; continues to next line
    val customerId: CustomerId,   // => typed; compile-time id safety
    // => executes the statement above; continues to next line
    val total: Money,             // => domain value object
    // => executes the statement above; continues to next line
    val status: OrderStatus       // => sealed class member
    // => sealed class member: closed hierarchy; when-expression exhaustiveness enforced
)
 
// => package com.example.order.adapter.out.persistence
import jakarta.persistence.* // => JPA legitimately in adapter zone
// => executes the statement above; continues to next line
@Entity @Table(name = "orders")
// => @Entity: JPA maps this class to a database table — adapter zone only
class OrderJpaEntity(
// => executes the statement above; continues to next line
    @Id @Column(name = "order_id") var id: String = "",         // => JPA requires mutable var
    // => @Id: JPA primary key mapping — persistence adapter concern
    @Column(name = "customer_id")  var customerId: String = "", // => var: JPA reflective access
    // => persistence mapping annotation: adapter zone concern; domain is unaware
    @Column(name = "total_amount") var total: java.math.BigDecimal = java.math.BigDecimal.ZERO,
    // => persistence mapping annotation: adapter zone concern; domain is unaware
    @Column(name = "currency")     var currency: String = "",
    // => persistence mapping annotation: adapter zone concern; domain is unaware
    @Column(name = "status")       var status: String = ""
    // => persistence mapping annotation: adapter zone concern; domain is unaware
)
// Kotlin note: JPA requires no-arg constructor and mutable properties; data class incompatible
// => OrderJpaEntity is a regular class with var properties; domain.Order is immutable data class

// ANTI-PATTERN: domain Order record with EF Core attribute
// => namespace Example.Order.Domain
using System.ComponentModel.DataAnnotations.Schema; // => VIOLATION: EF in domain namespace
// => executes the statement above; continues to next line
 
[Table("orders")]                     // => VIOLATION: EF Core attribute on domain type
// => executes the statement above; continues to next line
public record Order(
// => executes the statement above; continues to next line
    [property: Column("order_id")] string Id,         // => VIOLATION: EF column in domain
    // => executes the statement above; continues to next line
    string CustomerId                                  // => raw String; typed CustomerId lost
    // => executes the statement above; continues to next line
);
 
// CORRECT: domain Order has no EF attributes; separate DB entity class in adapter
// => namespace Example.Order.Domain
public record Order(
// => executes the statement above; continues to next line
    OrderId Id,             // => typed; no EF attribute; framework-free
    // => executes the statement above; continues to next line
    CustomerId CustomerId,  // => typed; init-only
    // => executes the statement above; continues to next line
    Money Total,            // => value object; no EF column annotation
    // => executes the statement above; continues to next line
    OrderStatus Status      // => domain enum; no EF dependency
    // => executes the statement above; continues to next line
);
 
// => namespace Example.Order.Adapter.Out.Persistence
using Microsoft.EntityFrameworkCore; // => EF: legitimately in adapter namespace
// => executes the statement above; continues to next line
public class OrderDbEntity           // => plain class; not a record (EF needs mutable props)
// => executes the statement above; continues to next line
{
    public string  Id         { get; set; } = ""; // => EF requires settable properties
    // => executes the statement above; continues to next line
    public string  CustomerId { get; set; } = ""; // => raw String column
    // => executes the statement above; continues to next line
    public decimal Total      { get; set; }        // => raw decimal; not Money
    // => executes the statement above; continues to next line
    public string  Currency   { get; set; } = ""; // => companion column to Total
    // => executes the statement above; continues to next line
    public string  Status     { get; set; } = ""; // => String enum value
    // => enum value: closed set of domain values; exhaustive switch/when enforced
}
// Mapper in EfOrderRepository translates between Order ↔ OrderDbEntity (see Example 8)

// HTTP adapter: already shown in Example 9; receives JSON, calls input port
// => com.example.order.adapter.in.web.OrderController
// => Uses PlaceOrderUseCase; maps HTTP ↔ domain types
 
// CLI adapter: reads from args/stdin; calls SAME PlaceOrderUseCase
// => com.example.order.adapter.in.cli.OrderCliAdapter
package com.example.order.adapter.in.cli;              // => adapter zone: framework and I/O allowed
// => executes the statement above; continues to next line
 
import com.example.order.application.port.in.PlaceOrderUseCase; // => same interface as HTTP adapter
// => executes the statement above; continues to next line
import com.example.order.domain.*;                              // => domain types for building input
// => executes the statement above; continues to next line
import java.util.Scanner;                                       // => JDK I/O: adapter-zone only
// => executes the statement above; continues to next line
import java.util.List;                                          // => JDK collection for order lines
 
// OrderCliAdapter: command-line input adapter; implements no interface itself
// => Receives PlaceOrderUseCase through constructor; calls placeOrder() identically to HTTP controller
public class OrderCliAdapter {                                  // => input adapter class; no interface required for CLI
// => interface OrderCliAdapter: contract definition — no implementation details here
    private final PlaceOrderUseCase placeOrderUseCase; // => same interface reference as controller
    // => placeOrderUseCase: PlaceOrderUseCase — final field; assigned once in constructor; immutable reference
 
    public OrderCliAdapter(PlaceOrderUseCase placeOrderUseCase) { // => constructor injection; no reflection
    // => constructor: receives all dependencies — enables testing with any adapter implementation
        this.placeOrderUseCase = placeOrderUseCase; // => injected; not created here
        // => this.placeOrderUseCase stored — field holds injected placeOrderUseCase for method calls below
    }
 
    // => Entry point for CLI invocation; reads args, builds domain input, delegates to use case
    public void run(String[] args) {               // => run: called from main(); receives raw CLI args
        // => Parse CLI args into raw domain input — adapter-specific parsing
        var customerId = args[0];               // => first arg: customer id string
        // => customerId: holds the result of the expression on the right
        var productId  = args[1];               // => second arg: product id string
        // => productId: holds the result of the expression on the right
        var quantity   = Integer.parseInt(args[2]); // => third arg: quantity parsed to int
 
        // => Map raw args to domain input type — same step HTTP adapter does with JSON
        var input = new UnvalidatedOrder(          // => UnvalidatedOrder: domain input type; adapter builds it
        // => input: holds the result of the expression on the right
            new CustomerId(customerId),            // => wrap raw String in typed domain value object
            // => executes the statement above; continues to next line
            List.of(new OrderLineInput(new ProductId(productId), new Quantity(quantity))) // => typed line
            // => method call: delegates to collaborator; result captured above
        );
 
        // => Delegate to use case — IDENTICAL call to what HTTP controller makes
        var result = placeOrderUseCase.placeOrder(input); // => result: Result<List<OrderPlaced>, PlacingOrderError>
 
        // => Map result to CLI output — adapter-specific rendering
        if (result.isSuccess()) {                  // => success branch: print order id to stdout
        // => conditional branch: execution path depends on condition above
            System.out.println("Order placed: " + result.getValue().get(0).orderId().value()); // => stdout
            // => output: verification line — shows result in console
        } else {                                   // => failure branch: print error to stderr
        // => conditional branch: execution path depends on condition above
            System.err.println("Failed: " + result.getError().getMessage()); // => stderr; non-zero exit expected
            // => output: verification line — shows result in console
        }
    }
}
// PlaceOrderService.placeOrder() runs once; HTTP and CLI share it through the interface
// => zero code duplication; business rules live in one place regardless of delivery mechanism

package com.example.order.adapter.`in`.cli
// => executes the statement above; continues to next line
 
import com.example.order.application.port.`in`.PlaceOrderUseCase // => same interface as Ktor route
// => executes the statement above; continues to next line
import com.example.order.domain.*
// => executes the statement above; continues to next line
import kotlinx.coroutines.runBlocking
 
// OrderCliAdapter: CLI delivery mechanism; calls same PlaceOrderUseCase as Ktor route
// => Injected at startup from same Koin module that wires Ktor routes
class OrderCliAdapter(
// => executes the statement above; continues to next line
    private val placeOrderUseCase: PlaceOrderUseCase // => identical interface as web adapter
    // => executes the statement above; continues to next line
) {                                                  // => no PlaceOrderService in constructor; interface only
// => interface only: contract definition — no implementation details here
    fun run(args: Array<String>): Unit = runBlocking { // => runBlocking bridges CLI to coroutine
        // => Parse CLI arguments; different format than JSON body but same domain types produced
        val input = UnvalidatedOrder(
            // => UnvalidatedOrder: same domain type produced by Ktor route mapper
            customerId = CustomerId(args[0]),     // => first arg → typed CustomerId
            // => args[0]: raw string; wrapped in CustomerId value object
            lines      = listOf(OrderLineInput(
            // => executes the statement above; continues to next line
                productId = ProductId(args[1]),   // => second arg → typed ProductId
                // => args[1]: raw string; wrapped in ProductId value object
                quantity  = Quantity(args[2].toInt()) // => third arg → typed Quantity
                // => args[2].toInt(): parse String to Int; Quantity validates domain rules
            ))
            // => operation completes; execution continues to next statement
        )
        // => input : UnvalidatedOrder — identical type to what Ktor route produces from JSON
 
        // => placeOrder: same method call; same PlaceOrderService implementation runs
        placeOrderUseCase.placeOrder(input)
            // => Result<List<OrderPlaced>>: same type returned whether caller is HTTP or CLI
            .onSuccess { events ->
            // => executes the statement above; continues to next line
                println("Order placed: ${events.first().orderId.value}") // => CLI output
                // => orderId.value: unwrap typed OrderId to raw String for printing
            }
            // => operation completes; execution continues to next statement
            .onFailure { error ->
            // => executes the statement above; continues to next line
                System.err.println("Failed: ${error.message}")            // => CLI error output
                // => stderr: CLI convention for error messages; non-zero exit code expected
            }
    }
}
// Kotlin note: runBlocking used in CLI entry point only; suspend propagates through app and adapters
// => all business logic is suspend-compatible; CLI is the only blocking boundary

namespace Example.Order.Adapter.In.Cli;
// => executes the statement above; continues to next line
 
using Example.Order.Application.Port.In; // => IPlaceOrderUseCase: same interface as controller
// => executes the statement above; continues to next line
using Example.Order.Domain;
// => executes the statement above; continues to next line
using System.CommandLine;                // => System.CommandLine NuGet: CLI framework; adapter zone
 
// OrderCliAdapter: CLI delivery mechanism; System.CommandLine parses args
// => Receives IPlaceOrderUseCase from DI; same interface ASP.NET controller receives
public class OrderCliAdapter  // => no [ApiController]; pure CLI concerns
// => executes the statement above; continues to next line
{
// => operation completes; execution continues to next statement
    private readonly IPlaceOrderUseCase _placeOrderUseCase; // => same interface as OrderController
    // => IPlaceOrderUseCase: resolved to PlaceOrderService by DI at startup
 
    public OrderCliAdapter(IPlaceOrderUseCase placeOrderUseCase)
    // => constructor: receives all dependencies — enables testing with any adapter implementation
    {
    // => operation completes; execution continues to next statement
        _placeOrderUseCase = placeOrderUseCase; // => injected; PlaceOrderService runs behind this
        // => executes the statement above; continues to next line
    }
    // => operation completes; execution continues to next statement
 
    public async Task<int> RunAsync(string[] args)
    // => executes the statement above; continues to next line
    {
        // => System.CommandLine: parses --customer-id, --product-id, --quantity from args
        var customerIdOpt = new Option<string>("--customer-id") { IsRequired = true };
        // => Option<string>: typed option; System.CommandLine validates presence
        var productIdOpt  = new Option<string>("--product-id")  { IsRequired = true };
        // => IsRequired = true: System.CommandLine produces error if option missing
        var quantityOpt   = new Option<int>   ("--quantity")    { IsRequired = true };
        // => Option<int>: CLI framework parses string to int before SetHandler receives it
 
        var rootCmd = new RootCommand("Place an order via CLI");
        // => RootCommand: top-level command; maps args to handler
        rootCmd.AddOption(customerIdOpt); rootCmd.AddOption(productIdOpt); rootCmd.AddOption(quantityOpt);
        // => AddOption: registers each option with the root command
 
        rootCmd.SetHandler(async (customerId, productId, quantity) =>
        // => method call: delegates to collaborator; result captured above
        {
            // => Map parsed CLI args to domain input type — adapter responsibility
            var input = new UnvalidatedOrder(
            // => input: holds the result of the expression on the right
                new CustomerId(customerId),
                // => CustomerId: wraps raw string; domain validates further downstream
                new[] { new OrderLineInput(new ProductId(productId), new Quantity(quantity)) }
                // => OrderLineInput: domain type; same shape regardless of delivery mechanism
            );
            // => input : UnvalidatedOrder — identical type to what OrderController produces
 
            // => SAME PlaceOrder call as OrderController; same PlaceOrderService executes
            var result = await _placeOrderUseCase.PlaceOrder(input);
            // => result : OneOf<IReadOnlyList<OrderPlaced>, PlacingOrderError>
            result.Switch(
            // => executes the statement above; continues to next line
                events => Console.WriteLine($"Order placed: {events[0].OrderId.Value}"),
                // => stdout: CLI convention for success output
                error  => Console.Error.WriteLine($"Failed: {error.Message}")
                // => stderr: CLI convention for error output; caller checks exit code
            );
        }, customerIdOpt, productIdOpt, quantityOpt);
        // => executes the statement above; continues to next line
 
        return await rootCmd.InvokeAsync(args);
        // => InvokeAsync: System.CommandLine parses args, calls SetHandler, returns exit code
    }
}
// PlaceOrderService.PlaceOrder executes once; HTTP and CLI share it through IPlaceOrderUseCase
// => adding a gRPC or message queue adapter follows the same pattern: one new class, zero service changes

// PlaceOrderService.placeOrder: full orchestration showing each step's nature
// => Package: com.example.order.application.service
// => No framework imports; only domain types and output port interfaces
 
@Override
public Result<List<OrderPlaced>, PlacingOrderError> placeOrder(UnvalidatedOrder input) {
    // === STEP 1: PURE DOMAIN VALIDATION =====================================
    // => OrderValidator.validate is a static pure function; no I/O; no database
    // => Returns Result<ValidatedOrder, PlacingOrderError>; fast; testable without mocks
    var validated = OrderValidator.validate(input);
    if (validated.isFailure()) {
        return Result.failure(validated.getError()); // => early return; no side effects yet
    }
 
    // === STEP 2: PURE DOMAIN PRICING ========================================
    // => OrderPricer.price is a static pure function; reads product catalogue from memory
    // => Returns PricedOrder with calculated Money total; still no I/O
    var priced = OrderPricer.price(validated.getValue());
 
    // === STEP 3: PERSIST THROUGH OUTPUT PORT (effectful) ====================
    // => orderRepository is an interface; JPA adapter runs in production; InMemory in tests
    // => No import jakarta.persistence.*; adapter decides how to store
    var saved = orderRepository.save(priced); // => side effect: writes to database
 
    // === STEP 4: NOTIFY THROUGH OUTPUT PORT (effectful) =====================
    // => notificationPort is an interface; SMTP adapter in production; FakePort in tests
    // => No import jakarta.mail.*; adapter decides which channel and how
    notificationPort.sendOrderConfirmation(saved); // => side effect: sends email/SMS
 
    // === STEP 5: RETURN DOMAIN EVENTS =======================================
    // => Domain event list returned; controller maps to HTTP response; CLI prints to stdout
    return Result.success(List.of(new OrderPlaced(saved.id(), saved.customerId(), saved.status())));
}
// No @Transactional here (that annotation goes on the adapter or a thin wrapper, not the service)
// No HTTP import; no framework annotation; pure orchestration