카사요 인슈어런스

CommonJS 프로젝트의 Monorepo 한계

Turborepo 기반의 모노레포 아키텍처에서 공통 유틸리티와 모듈을 사내 패키지 형태로 분리 구성하는 과정에서 문제가 발생했습니다.

당초 앱 구동 시 내부 패키지를 JIT(Just-In-Time) 컴파일 형태로 직접 참조하려 했으나, NestJS 프레임워크가 CommonJS 기반으로 빌드되고 의존성 주입 등을 위한 다수의 메타 데코레이터를 사용하기 때문에, 최신 ESM 환경으로의 변환과 즉각적인 소스 참조 시점 컴파일(JIT) 환경을 구축하는 데 한계가 있었습니다.

이를 해결하기 위해 각 앱 모듈이 실행 단계에서 내부 패키지 코드를 직접 파싱하고 컴파일하는 방식을 탈피했습니다.

공통 패키지에 대해 개별적인 빌드 스크립트를 마련하고, 터보레포의 파이프라인에 작업 의존성을 명확하게 선언했습니다.

그 결과, 빌드 수행 시 공통 패키지들이 우선적으로 산출물(dist)을 생성하고 애플리케이션에서는 이 빌드 완료된 산출물을 안전하게 참조하는 방식으로 문제를 해결하여 구조적 유연성과 안정적인 런타임 환경을 확립할 수 있었습니다.

파편화된 프로젝트 구조 통합 및 코드 컨벤션 확립으로 유지보수성 개선

'카사요 인슈어런스' 프로젝트를 운영하는 과정에서 기존 시스템 구조의 한계로 인해 유지보수 비용이 증가하고 개발 생산성이 심각하게 저하되는 문제에 직면했습니다. 프론트엔드와 백엔드의 타입을 맞추기 위해 공통 타입 라이브러리를 별도로 배포해야 했고, 데이터베이스를 관리하는 프리즈마(Prisma) 스키마 역시 별도의 프로젝트로 분리되어 있었습니다. 이로 인해 사소한 수정에도 매번 별도 프로젝트에서 마이그레이션과 재배포를 진행하고 API 프로젝트에서 db pull을 받아야 하는 극심한 시간 낭비가 발생했습니다. 또한, 전체적인 코드 컨벤션이 없어 카멜 케이스와 스네이크 케이스 등이 무분별하게 혼재되어 가독성을 떨어뜨렸으며, 단일 서버 구조로 인해 특정 서비스에 트래픽이 몰리면 전체 시스템에 영향을 미치는 구조적 취약점도 안고 있었습니다.

이러한 복합적인 문제들을 해결하기 위해, 시스템을 단순하고 명확한 체계를 갖춘 환경으로 전면 마이그레이션했습니다. 먼저 터보레포(Turborepo)를 도입하여 모노레포 환경을 구축하고, 서비스 사용 대상자에 따라 '사용자', '관리자', '설계사' API 서버를 독립적으로 분리하여 구성했습니다. 이는 특정 타겟의 서비스에 트래픽이 집중되더라도 다른 서버에 영향을 주지 않도록 장애를 격리하고 안정적인 스케일 아웃을 도모하기 위한 설계였습니다. 이와 함께 개발 병목의 원인이었던 분리된 프리즈마 프로젝트와 공통 타입 라이브러리 구조를 폐기하고, 백엔드 API 프로젝트 내에서 데이터베이스 라이프사이클을 주도하도록 개편했습니다. 더불어 팀 내부에 명확한 코드 컨벤션을 수립하여 파편화된 네이밍 규칙과 스타일을 터보레포 환경 내에서 일관되게 통일했습니다.

마이그레이션 결과, 대상자별 독립적인 서버 운용을 통해 트래픽 부하를 분산시키고 운영 환경의 안정성을 성공적으로 확보했습니다. 불필요하게 쪼개져 있던 프로젝트 구조를 모노레포로 통합하고 결합도를 낮춤으로써, 동기화와 배포에 낭비되던 대기 시간을 완전히 제거했습니다. 통일된 코드 컨벤션을 통해 협업 효율과 코드 가독성 또한 크게 향상되어, 온전히 비즈니스 로직 개발과 서버 성능 최적화에 집중할 수 있는 쾌적한 환경을 구축했습니다. 이번 프로젝트를 통해 트래픽을 고려한 아키텍처 분리와 일관된 개발 규칙이 시스템의 확장성 및 팀의 생산성에 얼마나 핵심적인 영향을 미치는지 깊이 체감할 수 있었습니다.