ADR-0001: 모노레포·폴리글랏 워크스페이스 구조

• 상태: 승인됨
• 날짜: 2026-06-21

맥락

시스템은 배포 단위 여러 개(외부 위젯, 테넌트 콘솔, 게이트웨이, 각종 API, 파이프라인, 분석 엔진)와 공유 코드(스키마, 공통 도메인, 디자인 시스템, 공통 유틸)로 구성된다. 런타임도 셋이다 — JVM · Node · Python. 이 코드들을 어떻게 저장하고 묶을지 정해야 했다. 특히 여러 런타임이 같은 DB 스키마를 공유하므로, 스키마와 그 소비자들을 한 번에 바꿀 수 있어야 한다.

결정

단일 모노레포로 둔다. 코드는 src/ 아래에 두고: - apps/ — 배포되는 실행 단위, libs/ — 가져다 쓰는 공유 코드. - 런타임별 워크스페이스 루트를 분리한다: settings.gradle(JVM, Groovy DSL) · pnpm-workspace.yaml(Node) · pyproject.toml(Python). - 빈 폴더는 .gitkeep으로 구조를 추적하고, 빌드 산출물 out/은 추적하지 않는다.

자세한 구조는 repo-structure.md 참고.

대안

• 멀티레포(런타임/서비스별 분리) — 공유 스키마·계약을 저장소 간 동기화해야 하고, 크로스-런타임 변경이 원자적이지 않다. 표류 위험이 커서 폐기.
• 단일 빌드 도구로 통일 — 폴리글랏이라 자연스러운 도구(gradle/pnpm/uv)가 런타임마다 다르다. 무리하게 통일하면 각 생태계의 표준에서 벗어난다.

결과

• 스키마와 그 소비자(JVM·Python 모델)를 한 PR로 원자적으로 바꿀 수 있다 → [[0005-db-as-contract]]의 기반.
• 런타임별 빌드는 독립적으로 유지된다.
• 툴체인 3종을 함께 관리하는 부담이 있다(CI에서 변경 경로별 조건부 실행으로 완화).
• 골격만 있고 비어 있는 폴더는 채워질 때까지 .gitkeep으로 유지한다(미리 다 채우지 않는다).