Hexagonal Architecture (헥사고날 아키텍처)

                 ┌────────────┐          ┌────────────┐
                 │ REST       │          │ CLI / 배치 │
                 │ Controller │          │            │
                 └─────┬──────┘          └─────┬──────┘
                       │  Driving Adapter       │
                ╱──────▼─────────────────────────▼──────╲
               ╱       ○ Inbound Port (유스케이스)        ╲
              ╱                                             ╲
             │         Application Core                     │
             │      (도메인 모델 + 유스케이스)               │
              ╲                                             ╱
               ╲       ○ Outbound Port (저장, 결제, 알림)   ╱
                ╲──────┬─────────────────────────┬──────╱
                       │  Driven Adapter          │
                 ┌─────▼──────┐          ┌───────▼──────┐
                 │ PostgreSQL │          │ 외부 PG API  │
                 │ Repository │          │ Client       │
                 └────────────┘          └──────────────┘

Controller ──> Service ──> Repository(TypeORM) ──> DB
                  │
                  └── 비즈니스 로직이 TypeORM에 의존한다

Controller ──> [ Core ] <── Repository 구현(TypeORM)
                  │
                  └── Core는 아무것도 의존하지 않는다
                      바깥이 Core가 정한 인터페이스를 따른다

src/ordering/
├── domain/                              # Core: 도메인
│   ├── order.ts
│   ├── order-id.ts
│   └── money.ts
├── application/                         # Core: 유스케이스
│   ├── port/
│   │   ├── in/
│   │   │   └── place-order.use-case.ts  # Inbound Port
│   │   └── out/
│   │       ├── order.repository.ts      # Outbound Port
│   │       └── payment.gateway.ts       # Outbound Port
│   └── service/
│       └── place-order.service.ts       # Inbound Port 구현
├── adapter/
│   ├── in/
│   │   └── web/
│   │       ├── order.controller.ts      # Driving Adapter
│   │       └── place-order.request.ts
│   └── out/
│       ├── persistence/
│       │   ├── typeorm-order.repository.ts  # Driven Adapter
│       │   └── order.orm-entity.ts
│       └── payment/
│           └── toss-payment.adapter.ts      # Driven Adapter
└── ordering.module.ts                   # 조립(Wiring)

// application/port/in/place-order.use-case.ts
export const PLACE_ORDER_USE_CASE = Symbol('PLACE_ORDER_USE_CASE');

export interface PlaceOrderUseCase {
  execute(command: PlaceOrderCommand): Promise<OrderId>;
}

export class PlaceOrderCommand {
  constructor(
    readonly customerId: string,
    readonly lines: { productId: string; unitPrice: number; quantity: number }[],
    readonly paymentMethodToken: string,
  ) {}
}

// application/port/out/order.repository.ts
export const ORDER_REPOSITORY = Symbol('ORDER_REPOSITORY');

export interface OrderRepository {
  findById(id: OrderId): Promise<Order | null>;
  save(order: Order): Promise<void>;
}

// application/port/out/payment.gateway.ts
export const PAYMENT_GATEWAY = Symbol('PAYMENT_GATEWAY');

export interface PaymentGateway {
  requestPayment(request: {
    orderId: OrderId;
    amount: Money;
    paymentMethodToken: string;
  }): Promise<PaymentResult>;
}

export type PaymentResult =
  | { success: true; transactionId: string }
  | { success: false; reason: string };

// 메모리 기반 가짜 어댑터
class InMemoryOrderRepository implements OrderRepository {
  readonly store = new Map<string, Order>();
  async findById(id: OrderId) { return this.store.get(id.value) ?? null; }
  async save(order: Order) { this.store.set(order.id.value, order); }
}

class FakePaymentGateway implements PaymentGateway {
  constructor(private readonly shouldSucceed = true) {}
  async requestPayment(): Promise<PaymentResult> {
    return this.shouldSucceed
      ? { success: true, transactionId: 'tx-1' }
      : { success: false, reason: 'CARD_DECLINED' };
  }
}

// place-order.service.spec.ts
describe('PlaceOrderService', () => {
  const command = new PlaceOrderCommand(
    'c0a8012e-0000-4000-8000-000000000001',
    [{ productId: 'p-1', unitPrice: 10_000, quantity: 2 }],
    'token',
  );

  it('결제에 성공하면 결제 완료 상태로 저장한다', async () => {
    const orders = new InMemoryOrderRepository();
    const service = new PlaceOrderService(orders, new FakePaymentGateway(true));

    const id = await service.execute(command);

    expect(orders.store.get(id.value)?.isPaid()).toBe(true);
  });

  it('결제에 실패하면 주문을 저장하지 않는다', async () => {
    const orders = new InMemoryOrderRepository();
    const service = new PlaceOrderService(orders, new FakePaymentGateway(false));

    await expect(service.execute(command)).rejects.toThrow(PaymentFailedException);
    expect(orders.store.size).toBe(0);
  });
});

Clean Architecture의 동심원

┌──────────────────────────────────────────────┐
│ Frameworks & Drivers (DB, Web, UI)           │
│  ┌────────────────────────────────────────┐  │
│  │ Interface Adapters (Controller, Repo)  │  │  ← Hexagonal의 Adapter
│  │  ┌──────────────────────────────────┐  │  │
│  │  │ Use Cases                        │  │  │  ← Hexagonal의 Application + Port
│  │  │  ┌────────────────────────────┐  │  │  │
│  │  │  │ Entities                   │  │  │  │  ← Hexagonal의 Domain
│  │  │  └────────────────────────────┘  │  │  │
│  │  └──────────────────────────────────┘  │  │
│  └────────────────────────────────────────┘  │
└──────────────────────────────────────────────┘