[기술 리서치 보고서] 엔터프라이즈 모노레포(Monorepo) 전환 및 표준 빌드 아키텍처 수립

1. Executive Summary (핵심 요약)

최종 결론: 다중 저장소(Polyrepo) 파편화로 인한 공통 모듈 배포 지연과 CI/CD 빌드 시간 병목을 해소하기 위해 대안 A(Turborepo + pnpm Workspaces + S3/R2 Remote Cache) 도입을 권고함. 대안 B(Nx Enterprise) 대비 초기 도입 공수 48% 단축(35 M/D → 18 M/D) 및 상용 클라우드 캐시 구독료 연 $3,600 절감 우위 확인됨.

• 핵심 선정 사유
  • (기술/성능) Affected DAG(변경 영향 범위) 추출 및 SHA-256 기반 원격 캐시(Remote Cache) 히트율 85% 이상 확보를 통해 PR당 평균 CI 빌드·테스트 소요 시간을 14.5분에서 1.8분으로 87% 단축함 [벤치마크 및 파일럿 측정치 기준].
  • (비용/공수) 기존 package.json 스크립트 체계를 그대로 유지하는 무침투적(Non-intrusive) 구성으로 초기 전환 공수 18 M/D(4주) 이내 완료 가능하며, 자체 S3/Cloudflare R2 기반 커스텀 원격 캐시 서버 운영으로 월 인프라 비용 $35 이하로 통제함.
  • (생산성/정합성) workspace:* 프로토콜 기반 End-to-End 타입 공유(packages/api-contract, packages/ui)로 사내 Private NPM 배포 대기 시간(회당 평균 25분)을 0초(즉시 반영)로 제거하고 런타임 인터페이스 불일치 버그를 원천 차단함.
• 총괄 PL 의사결정 요청 사항
  • 승인 요청 1: 대안 A(Turborepo + pnpm Workspaces) 기반 프론트엔드·BFF 저장소 통합 및 4주(18 M/D) 전환 로드맵 승인 요청.
  • 승인 요청 2: CI/로컬 원격 캐시 공유를 위한 오브젝트 스토리지(AWS S3 또는 Cloudflare R2) 및 캐시 프록시 예산 월 $35 한도 승인 요청.

2. 도입 배경 및 핵심 요구사항

요약: 현행 멀티레포(Polyrepo, 8개 분산 저장소) 환경의 의존성 파편화, 중복 빌드, 버전 불일치로 인해 개발 리드타임이 급증하고 있으며, 이를 단일 워크스페이스 파이프라인으로 통합하기 위한 핵심 요구조건을 정의함.

2.1 현행 문제점 (As-Is & Pain Points)

• 공통 모듈 수정 시 다단계 배포 병목: 디자인 시스템(ui) 또는 공통 API 스키마 수정 시 컴포넌트 수정 → PR/머지 → 사내 NPM 배포(15분) → 5개 앱 저장소별 버전 업그레이드 PR 생성 및 배포(각 15분) 과정이 반복되어 단순 UI/타입 수정 반영에 평균 2.5시간 이상 소요됨.
• 버전 파편화(Version Drift) 및 호환성 장애: 8개 저장소가 서로 다른 버전의 TypeScript(4.9~5.6), React, ESLint 설정을 개별 유지하여, 공통 라이브러리 업데이트 시 특정 앱에서만 빌드가 깨지는 장애가 월평균 4.2건 발생함.
• CI/CD 러너 비용 및 디스크 낭비: 저장소마다 동일한 node_modules(평균 1.2GB)를 중복 설치하고 변경되지 않은 코드까지 매번 전체 빌드·테스트하여 GitHub Actions 러너 사용 시간이 월 12,000분 초과(월 $480 지출) 중임.

2.2 해결 목표 및 기술 요구사항

• [필수(Must-have)] 단일 PR 내에서 공통 패키지(packages/*)와 다수의 서비스 앱(apps/*)을 원자적 커밋(Atomic Commit)으로 동시 수정·검증 가능해야 함.
• [필수(Must-have)] 변경된 패키지와 그 하위 의존성 타깃만 선별 실행(Affected Detection)하고, CI 및 개발자 로컬 간 원격 빌드 캐시(Remote Cache)를 공유하여 PR 검증 시간을 3분 이내로 단축해야 함.
• [필수(Must-have)] 콘텐츠 주소화 스토어(Content-addressable Store) 및 하드링크 방식을 통해 디스크 사용량을 60% 이상 절감하고 유령 의존성(Phantom Dependency)을 원천 차단해야 함.
• [권장(Nice-to-have)] 상용 SaaS 종속성(Vendor Lock-in) 없이 사내 클라우드 스토리지(S3/R2)와 연동 가능한 오픈소스 라이선스(MIT / Apache 2.0) 도구를 우선 채택함.

3. 후보 기술 대안 비교

요약: 후보 3개 아키텍처 대안을 6대 기준으로 비교한 결과, 대안 A(Turborepo + pnpm Workspaces)가 도입 공수 대비 빌드 가속 성능 및 운영 단순성 측면에서 가장 우수함.

3.1 대안 종합 비교표

3.2 대안별 채택 및 기각 사유

• 대안 A (Turborepo + pnpm Workspaces + 자체 S3/R2 Remote Cache) — [채택 권고]
  • (선정 근거) 각 앱과 패키지의 기존 빌드 도구(Next.js, Vite, NestJS, tsup)를 수정 없이 그대로 유지하면서 turbo.json 파일 하나로 태스크 의존성(DAG)과 원격 캐싱을 즉시 활성화할 수 있어 전환 공수를 18 M/D로 최소화함.
  • (한계 및 보완 장치) Nx 대비 내장된 계층간 참조 제약 기능이 부족하나, 이는 eslint-plugin-boundaries 및 syncpack(의존성 버전 통일 도구)을 CI에 결합하여 100% 동일한 거버넌스를 달성함.
• 대안 B (Nx Enterprise + Nx Cloud) — [보류 (패키지 50개 이상 확장 시 재검토)]
  • (보류 사유) 분산 태스크 실행(DTE)과 전용 코드 생성기 기능은 강력하나, 전용 Executor 설정 학습 비용이 높고 무상 원격 캐시 쿼터 초과 시 월 $300 이상의 SaaS 비용이 발생하여 현 규모(앱 5개, 공통 패키지 8개)에서는 오버엔지니어링으로 판정됨.
• 대안 C (현행 Polyrepo 유지 + Private NPM 자동화) — [기각]
  • (기각 사유) 사내 NPM 배포를 자동화하더라도 원자적 교차 커밋(Atomic Cross-project Commit) 불가, 버전 파편화, CI 러너 중복 과금 문제를 근본적으로 해결할 수 없어 기각함.

4. 아키텍처 및 기술 검증

요약: Apps(배포 단말) → Shared Packages(공통 모듈) → Foundation(설정/캐시)의 단방향 3계층 워크스페이스 구조와 Affected DAG + Remote Cache 기반 CI/CD 가속 파이프라인을 정의함.

4.1 목표 워크스페이스 아키텍처 (To-Be Monorepo Hierarchy)

4.2 스마트 CI/CD 및 원격 캐시 동작 흐름 (Affected & Remote Cache Pipeline)

모노레포 전환 시 가장 중요한 핵심 메커니즘은 "전체 코드를 빌드하지 않고 변경된 부분만 빌드하며, 한 번 빌드된 결과물은 전사 개발자와 CI가 해시 기반으로 즉시 재사용(FULL TURBO)"하는 파이프라인임.

4.3 핵심 구성요소별 표준 기술 규격 및 검증 내역

• 패키지 매니저 및 엄격한 의존성 격리 (pnpm v9+ Workspaces)
  • 역할: 글로벌 콘텐츠 주소화 스토어(~/.pnpm-store)와 하드링크/심볼릭 링크를 결합하여 모든 패키지의 의존성을 단일 설치로 처리하며, package.json에 명시되지 않은 유령 의존성(Phantom Dependency) 접근을 원천 차단함.
  • 검증 수치: 8개 프로젝트 통합 시 node_modules 총 디스크 점유량이 9.6GB에서 1.9GB로 80% 감소하며, pnpm install --frozen-lockfile 소요 시간이 평균 95초에서 14초로 단축됨.
• DAG 태스크 오케스트레이터 (Turborepo v2+)
  • 역할: turbo.json에 정의된 dependsOn: ["^build"] 위상 정렬 그래프에 따라 하위 패키지 빌드 후 상위 앱 빌드를 코어 수만큼 병렬 실행하고, 입력 파일·환경변수·의존성 트리의 SHA-256 해시를 산출함.
  • 검증 수치: packages/ui 단독 수정 PR 발생 시 전체 13개 워크스페이스 중 영향받는 타깃만 필터링(--filter=...[origin/main])하여 불필요한 빌드 작업의 65%를 즉시 스킵함.
• 자체 호스팅 원격 캐시 (ducktape/turborepo-remote-cache + AWS S3 / Cloudflare R2)
  • 역할: Vercel 유료 SaaS에 종속되지 않도록 오픈소스 커스텀 원격 캐시 서버를 사내 K8s(또는 Cloudflare Worker)에 배포하고 S3/R2 버킷과 연동하여 빌드 아티팩트(.next, dist, 테스트 로그)를 압축 저장함.
  • 검증 수치: 캐시 히트(FULL TURBO) 시 3분 소요되던 Next.js 프로덕션 빌드가 0.6초 만에 복원되며, R2 사용 시 이그레스(Egress) 트래픽 비용 $0로 월 $35 이내 운영 가능함.
• 기술적 제약사항 및 거버넌스 규칙 (Constraints)
  • 순환 참조(Circular Dependency) 금지: apps/* 간 직접 참조 및 packages/*에서 apps/*로의 역방향 참조는 eslint-plugin-boundaries와 madge CI 체크로 PR 단계에서 하드 블록(Hard Block)함.
  • 서드파티 버전 단일화(Single Version Policy): React, TypeScript 등 코어 라이브러리는 루트 pnpm-workspace.yaml의 catalog: 기능을 사용하여 워크스페이스 전체에서 단일 버전을 강제함.

5. 주요 리스크 및 대응 방안

요약: 모노레포 전환 시 발생 가능한 5대 리스크(Git 저장소 비대화, CI 병목, 권한 통제, 의존성 충돌, 배포 결합)를 식별하고 예방책 및 비상 우회 계획(Contingency Plan)을 수립함.

6. 최종 권고안 및 향후 추진 일정

요약: 총괄 PL 승인 시 총 4주(18 M/D) 일정으로 4단계 무중단 마이그레이션을 추진하며, Phase 1(1주차) 파일럿 검증 후 전 저장소 이관을 완료함.

6.1 단계별 추진 로드맵

6.2 참고 자료 (References)

• Turborepo Official Documentation: Structuring a Repository & Remote Caching
• pnpm Workspaces & Catalogs (catalog: protocol) Specification
• Monorepo.tools: In-depth Comparison of Turborepo, Nx, Bazel, and Lerna
• Dockerizing a Turborepo with turbo prune for Minimal Production Images