[아키텍처 설계 명세서] 엔터프라이즈 클라우드 네이티브 어플리케이션 아키텍처 설계서 (SAD)

문서 제·개정 이력 (Revision History)

제1장. 설계 개요 및 아키텍처 원칙 (1. Architecture Overview & Principles)

[설계 핵심 정의 (Architecture Blueprint Summary)]: 본 설계서는 전사 백엔드 어플리케이션의 구조적 일관성, 도메인 순수성, 고가용성을 보장하기 위해 실용적 헥사고날 아키텍처(Pragmatic Hexagonal Architecture, Ports & Adapters)와 CQRS(명령·조회 책임 분리)를 결합한 표준 어플리케이션 참조 아키텍처(Reference Architecture)를 명세함.

1.1 시스템 컨텍스트 및 도메인 코어 격리 개념 (System Context View)

• 시스템 경계 및 내·외부 분리:
  • 어플리케이션 중심부의 도메인 코어(Hexagon Core)는 순수 비즈니스 규칙과 불변식(Invariant)만 보유하며, 외부 프로토콜(REST, GraphQL, gRPC, Kafka) 및 영속성 인프라(RDBMS, Redis, 외부 API)는 포트(Port) 인터페이스와 어댑터(Adapter) 플러그인을 통해서만 결합됨.

1.2 아키텍처 핵심 설계 원칙 명세 (Architecture Principles Specification)

1.3 비기능 품질 속성 및 목표 SLA/SLO 명세 (Quality Attribute Specification)

제2장. 논리 아키텍처 및 컴포넌트 설계 (2. Logical & Component View)

2.1 논리 계층 및 헥사고날(Port & Adapter) 구조도

• 구조 명세: 어플리케이션 내부는 Inbound Adapter (Driving) → Application & Domain Core (Hexagon) ← Outbound Adapter (Driven)의 3대 영역·8개 표준 컴포넌트(COMP-01 ~ COMP-08)로 구성됨.

2.2 컴포넌트 카탈로그 및 책임 명세표 (Component Specification Catalog)

2.3 표준 패키지 구조 및 모듈 경계 규격 (Package Hierarchy Specification)

com.company.{domain}
├── adapter
│   ├── in
│   │   ├── web                    # [COMP-01] *Controller, *Request, *Response, *WebMapper
│   │   ├── event                  # [COMP-02] *EventConsumer, *EventPayload
│   │   └── scheduler              # [COMP-02] *JobScheduler
│   └── out
│       ├── persistence            # [COMP-07] *PersistenceAdapter, *JpaEntity, *JpaRepository, *QueryRepository
│       ├── cache                  # [COMP-07] *CacheAdapter, RedisKeySpec
│       ├── messaging              # [COMP-08] *OutboxAdapter, OutboxJpaEntity, *KafkaProducer
│       └── client                 # [COMP-08] *ExternalClientAdapter, *FeignClient / *RestClient
├── application
│   ├── port
│   │   ├── in                     # [COMP-03] *UseCase, *Query, command/*Command (Java Record)
│   │   └── out                    # [COMP-06] Load*Port, Save*Port, Record*OutboxPort, Request*Port
│   └── service                    # [COMP-04] *CommandService, *QueryService, *OrchestratorFacade
├── domain
│   ├── model                      # [COMP-05] AggregateRoot, Entity, ValueObject (순수 POJO)
│   ├── service                    # [COMP-05] *DomainPolicy, *DomainService
│   ├── event                      # [COMP-05] *DomainEvent
│   └── exception                  # [COMP-05] *DomainException, DomainErrorCode
└── common                         # [공통 커널] config/*, security/*, error/GlobalExceptionHandler, support/*

제3장. 프로세스 및 런타임 파이프라인 설계 (3. Process & Runtime Sequence View)

3.1 표준 요청 처리 8단계 파이프라인 다이어그램 (Process Pipeline View)

• 동적 실행 흐름: 클라이언트 요청은 STEP 1(Ingress)부터 STEP 8(Egress)까지 표준화된 필터·인터셉터·어댑터 체인을 통과하며, 비즈니스 코어는 오직 STEP 4 ~ STEP 6 구간에서만 실행됨.

3.2 단계별 런타임 처리 계약 명세표 (Pipeline Stage Contract Specification)

제4장. 데이터 및 영속성 아키텍처 설계 (4. Data & Persistence View)

4.1 CQRS 데이터 경로 분리, 다계층 캐시(L1/L2) 및 Outbox 아키텍처 다이어그램

• 설계 명세: 쓰기 경로(Command)와 읽기 경로(Query)의 데이터베이스 커넥션 및 모델을 물리적·논리적으로 분리하여, 대량 조회 트래픽이 핵심 트랜잭션 처리 성능을 침해하지 않도록 설계함.

4.2 데이터 저장소 및 다계층 캐시 정책 명세표 (Data & Cache Specification)

제5장. 물리 배포 및 회복탄력성·관측성 설계 (5. Deployment, Resilience & Observability View)

5.1 클라우드 네이티브 런타임 및 배포 토폴로지 다이어그램 (Deployment Topology View)

• 인프라 및 런타임 명세: 외부 트래픽은 CDN/WAF/ALB와 API Gateway를 거쳐 Kubernetes 클러스터 내 Java 21 Virtual Threads 기반 Stateless App Pods로 전달되며, 모든 파드는 OpenTelemetry Java Agent를 통해 메트릭·트레이스·로그를 Grafana LGTM 스택으로 실시간 전송함.

5.2 회복탄력성(Resilience), 보안 및 관측성(Observability) 상세 설계

• 회복탄력성·보안·관측성 파라미터 명세표 (Runtime Engineering Specification)

제6장. 표준 인터페이스 및 코드 템플릿 명세 (6. Standard Interface & Code Specification)

6.1 계층별 표준 코드 블루프린트 (Reference Implementation Templates)

• [Template 1] 순수 도메인 어그리거트 모델 (COMP-05 — 외부 기술 의존성 0% POJO)
  JAVA

  package com.company.order.domain.model;
  
  public class Order {
      private final OrderId id;
      private final BuyerId buyerId;
      private Money totalAmount;
      private OrderStatus status;
      private final List<OrderDomainEvent> domainEvents = new ArrayList<>();
  
      public static Order place(OrderId id, BuyerId buyerId, List<OrderLine> lines) {
          if (lines == null || lines.isEmpty()) {
              throw new OrderDomainException(OrderErrorCode.EMPTY_ORDER_LINES);
          }
          Money total = lines.stream().map(OrderLine::calculateAmount).reduce(Money.ZERO, Money::add);
          Order order = new Order(id, buyerId, total, OrderStatus.PLACED);
          order.domainEvents.add(new OrderPlacedEvent(id.value(), buyerId.value(), total.amount()));
          return order;
      }
  
      public void confirmPayment(String pgTransactionId) {
          if (this.status != OrderStatus.PLACED) {
              throw new OrderDomainException(OrderErrorCode.INVALID_ORDER_STATE_TRANSITION);
          }
          this.status = OrderStatus.PAID;
          this.domainEvents.add(new OrderPaidEvent(this.id.value(), pgTransactionId));
      }
  }

• [Template 2] 유스케이스 애플리케이션 서비스 (COMP-04 — 포트 조합 및 트랜잭션 경계)
  JAVA

  package com.company.order.application.service;
  
  @Service
  @RequiredArgsConstructor
  @Transactional(readOnly = true)
  public class PlaceOrderCommandService implements PlaceOrderUseCase {
  
      private final LoadOrderPort loadOrderPort;
      private final SaveOrderPort saveOrderPort;
      private final RecordOutboxPort recordOutboxPort;
  
      @Override
      @Transactional(rollbackFor = Exception.class)
      public OrderResult placeOrder(PlaceOrderCommand command) {
          // 1. 멱등성 검증 (중복 주문 요청 방어)
          if (loadOrderPort.existsByIdempotencyKey(command.idempotencyKey())) {
              return loadOrderPort.loadResultByIdempotencyKey(command.idempotencyKey());
          }
          // 2. 순수 도메인 어그리거트 생성 및 비즈니스 규칙 실행
          Order order = Order.place(OrderId.newId(), new BuyerId(command.buyerId()), command.toOrderLines());
  
          // 3. Outbound Port를 통한 상태 영속화 및 Transactional Outbox 원자적 기록
          saveOrderPort.save(order, command.idempotencyKey());
          recordOutboxPort.recordEvents(order.pullDomainEvents());
  
          return OrderResult.from(order);
      }
  }

• [Template 3] 공통 응답(ApiResponse<T>) 및 RFC 9457 ProblemDetail 에러 규격 (COMP-01)
  JAVA

  package com.company.order.common.response;
  
  public record ApiResponse<T>(
      boolean success,
      T data,
      String traceId,
      Instant timestamp
  ) {
      public static <T> ApiResponse<T> ok(T data) {
          return new ApiResponse<>(true, data, MDC.get("traceId"), Instant.now());
      }
  }

제7장. 아키텍처 적합성 검증 및 기술 스택 명세 (7. Architecture Fitness & Tech Stack BOM)

7.1 ArchUnit 자동화 아키텍처 적합성 검증 규칙 (Architecture Fitness Functions)

모든 프로젝트는 아래 5대 아키텍처 규칙(ARCH-RULE-01 ~ ARCH-RULE-05)을 JUnit 테스트 단계에서 자동 실행하며, 단 1건이라도 위반 시 CI 빌드가 실패(Fail) 처리됨.

package com.company.architecture;

@AnalyzeClasses(packages = "com.company", importOptions = ImportOption.DoNotIncludeTests.class)
public class HexagonalArchitectureFitnessTest {

    @ArchTest
    static final ArchRule ARCH_RULE_01_domain_must_be_pure_pojo =
        noClasses().that().resideInAPackage("..domain..")
            .should().dependOnClassesThat()
            .resideInAnyPackage("org.springframework..", "jakarta.persistence..", "com.fasterxml.jackson..", "..adapter..");

    @ArchTest
    static final ArchRule ARCH_RULE_02_hexagonal_layer_isolation =
        layeredArchitecture().consideringOnlyDependenciesInLayers()
            .layer("InboundAdapter").definedBy("..adapter.in..")
            .layer("OutboundAdapter").definedBy("..adapter.out..")
            .layer("Application").definedBy("..application..")
            .layer("Domain").definedBy("..domain..")
            .whereLayer("InboundAdapter").mayNotBeAccessedByAnyLayer()
            .whereLayer("OutboundAdapter").mayNotBeAccessedByAnyLayer()
            .whereLayer("Application").mayOnlyBeAccessedByLayers("InboundAdapter")
            .whereLayer("Domain").mayOnlyBeAccessedByLayers("Application", "OutboundAdapter");
}

7.2 전사 표준 기술 스택 명세서 (Standard Technology BOM)