Layered vs Hexagonal vs Onion vs Clean Architecture

flowchart LR
    subgraph L[Layered]
        direction TB
        LC[Controller] --> LS[OrderService]
        LS --> LR[TypeOrmOrderRepository]
        LR --> LDB[(DB)]
    end

    subgraph H[Hexagonal / Onion / Clean]
        direction TB
        HC[Controller] --> HS[OrderService]
        HS --> HP([OrderRepository<br/>interface])
        HR[TypeOrmOrderRepository] -. implements .-> HP
        HR --> HDB[(DB)]
    end

// Layered: Service가 Persistence 계층의 클래스를 안다
import { OrderRepository } from '../persistence/order.repository'; // TypeORM 구현체

// Hexagonal / Onion / Clean: Service가 자기 쪽 인터페이스만 안다
import { OrderRepository } from '../domain/order.repository'; // interface

src/order/
├── order.controller.ts       # Presentation
├── order.service.ts          # Business
├── order.repository.ts       # Persistence (TypeORM 직접 사용)
└── order.entity.ts           # TypeORM 엔티티 = 도메인 모델

src/order/
├── domain/
│   └── order.ts
├── application/
│   ├── port/in/place-order.use-case.ts
│   ├── port/out/order.repository.ts
│   └── service/place-order.service.ts
└── adapter/
    ├── in/web/order.controller.ts
    └── out/persistence/typeorm-order.repository.ts

src/order/
├── domain/
│   ├── model/order.ts
│   └── services/
│       ├── discount-policy.ts
│       └── order.repository.ts        # 인터페이스
├── application/
│   └── place-order.service.ts
├── infrastructure/
│   └── persistence/typeorm-order.repository.ts
└── presentation/
    └── order.controller.ts

src/order/
├── entities/
│   └── order.ts
├── use-cases/
│   ├── place-order/
│   │   ├── place-order.input-port.ts
│   │   ├── place-order.output-port.ts
│   │   └── place-order.interactor.ts
│   └── ports/order.gateway.ts         # 인터페이스
├── adapters/
│   ├── controllers/order.controller.ts
│   ├── presenters/place-order.presenter.ts
│   └── gateways/typeorm-order.gateway.ts
└── order.module.ts

Hexagonal:  [ 안 ] │ [ 밖 ]          ← 경계(테두리)를 강조
Onion:      ((( 도메인 )))           ← 안쪽 겹(심)을 강조
Clean:      규칙: 바깥 → 안쪽만      ← 원칙을 강조

// ── Layered ──────────────────────────────────────────
@Injectable()
export class OrderService {
  constructor(
    @InjectRepository(OrderEntity) private readonly orders: Repository<OrderEntity>, // TypeORM
    @InjectRepository(CustomerEntity) private readonly customers: Repository<CustomerEntity>,
  ) {}

  async place(dto: CreateOrderDto) {
    const customer = await this.customers.findOneByOrFail({ id: dto.customerId });
    const total = dto.lines.reduce((s, l) => s + l.price * l.quantity, 0);
    const discount = customer.grade === 'VIP' ? Math.floor(total * 0.1) : 0; // 규칙이 서비스에
    return this.orders.save({ customerId: customer.id, total: total - discount });
  }
}

// ── Hexagonal / Onion / Clean (공통 골격) ───────────
export class PlaceOrderService {
  constructor(
    private readonly orders: OrderRepository,       // 안쪽 인터페이스
    private readonly customers: CustomerRepository, // 안쪽 인터페이스
    private readonly discountPolicy: DiscountPolicy,
  ) {}

  async execute(cmd: PlaceOrderCommand): Promise<OrderId> {
    const customer = await this.customers.findById(cmd.customerId);
    const order = Order.place(this.orders.nextId(), customer.id, cmd.lines); // 규칙은 도메인에
    order.applyDiscount(this.discountPolicy.calculate(order, customer));
    await this.orders.save(order);
    return order.id;
  }
}

flowchart TD
    A[새 서비스 / 모듈] --> B{비즈니스 규칙이<br/>복잡한가?}
    B -- 아니오, CRUD 위주 --> L[Layered]
    B -- 예 --> C{외부 시스템 연동이 많거나<br/>DB·프레임워크 교체 가능성이 있나?}
    C -- 아니오 --> L2[Layered +<br/>Repository 인터페이스만 분리]
    C -- 예 --> D{DDD로 도메인을<br/>깊게 모델링하나?}
    D -- 예 --> O[Onion<br/>또는 Hexagonal + DDD]
    D -- 아니오 --> E{유스케이스를 명시적으로 드러내고<br/>출력 형식이 다양한가?}
    E -- 예 --> CL[Clean]
    E -- 아니오 --> H[Hexagonal]

src/
├── ordering/     # Core 도메인       → Onion / Clean
├── payment/      # 외부 PG 연동      → Hexagonal
├── admin/        # 관리자 CRUD       → Layered
└── notification/ # 범용 (메일/푸시)  → Layered + 외부 SDK 어댑터