[Master Plan] 프론트엔드 모노레포 통합 및 공용 모듈 마이그레이션

1. 개요 (Overview)

현재 adminfront, devfront, orgfront 세 개의 프론트엔드 프로젝트는 동일한 기술 스택을 사용함에도 불구하고 코드가 각자 복제되어 관리되고 있습니다. 이를 NPM Workspaces 기반의 모노레포 구조로 개편하여 중복을 제거하고, 기술적 일관성을 확보하는 것이 본 설계의 목적입니다.

2. 아키텍처 설계 (Architecture)

2.1. 디렉토리 구조

프로젝트 루트를 Workspace로 설정하고, 모든 앱과 공용 모듈을 packages/ 하위로 통합 관리합니다.

baron-sso/
├── package.json               # [New] 루트 레벨 Workspace 및 의존성 관리
├── packages/                  # 재사용 가능한 내부 패키지
│   ├── shared-ui/             # Shadcn UI, 제네릭 AppLayout, 브랜드 자산(로고/아이콘)
│   ├── shared-utils/          # apiClient 팩토리, i18n 엔진, 공용 로케일(사전 병합)
│   ├── shared-auth/           # OIDC 설정, AuthGuard 본체, 세션 관리(Sliding Session)
│   ├── shared-types/          # 도메인 모델 및 API TypeScript 타입
│   └── shared-config/         # Tailwind, Biome, TSConfig 공통 설정
├── adminfront/                # Feature 중심 유지 + Shared 패키지 참조
├── devfront/                  # App Shell 공유 + Shared 패키지 참조
└── orgfront/                  # App Shell 공유 + Shared 패키지 참조

2.2. 모노레포 도입의 이유 (Why Workspaces?)

깔끔한 임포트: ../../common 같은 상대 경로 대신 @shared/ui와 같은 패키지 이름으로 참조 가능.
의존성 단일화: 모든 앱이 동일한 라이브러리 버전을 사용하여 런타임 에러 방지.
설정 자동화: Vite와 TypeScript가 로컬 패키지를 자동으로 인식하여 HMR 및 타입 체킹 지원.

3. 핵심 기술 설계 (Technical Governance)

3.1. 의존성 관리 (Single Version Policy)

react, react-router-dom, tailwindcss, @tanstack/react-query 등 핵심 라이브러리 버전을 루트 package.json에서 고정 관리합니다.
각 패키지는 필요한 경우에만 별도 의존성을 가지며, 가능한 루트 버전을 따릅니다.

3.2. i18n 및 에셋 전략

동적 병합(Dictionary Merge): 공용 문구(Shared)를 먼저 로드하고, 앱별 특화 문구를 그 위에 덮어쓰는(Merge) 로직을 shared-utils에서 제공합니다.
자산 중앙화: 브랜드 로고, 파비콘 등 공통 정적 자산은 shared-ui/assets에서 관리합니다.

3.3. 제네릭 AppLayout 엔진

AppLayout.tsx는 더 이상 하드코딩된 메뉴를 갖지 않습니다.
메뉴(navItems), 브랜드 로고, 역할 스위처 표시 여부 등을 **설정 객체(Config)**로 주입받아 렌더링하는 범용 엔진으로 리팩토링합니다.

4. 실행 로드맵 (Execution Roadmap)

[1단계] 인프라 구축 (Infrastructure)

루트 package.json Workspace 설정.
shared-config 패키지 생성 및 Tailwind/Biome 설정 중앙화.
각 앱에서 @shared/config를 참조하도록 설정 변경.

[2단계] 기초 모듈 추출 (Base Migration)

중복도가 가장 높은 components/ui/*를 shared-ui로 이동.
apiClient, i18n, utils 등 순수 유틸리티 코드를 shared-utils로 이동.
각 앱의 임포트 경로를 @shared/*로 일괄 치환.

[3단계] 플랫폼 레이어 통합 (Platform)

AppLayout.tsx를 제네릭하게 리팩토링하여 shared-ui로 이동.
AuthGuard, LoginPage, sessionSliding 등 인증 관련 핵심 로직을 shared-auth로 통합.

[4단계] 앱별 적용 및 최적화 (Optimization)

devfront와 orgfront를 우선적으로 공용 레이아웃 기반으로 전환.
adminfront는 비즈니스 로직(Feature)은 유지하되 기반 레이어만 교체.
빌드 테스트 및 트리쉐이킹(번들 최적화) 확인.

5. 기대 효과 (Expected Benefits)

관리 비용 절감: 공통 UI 수정 시 3개 앱에 동시 반영.
개발 가속화: 신규 프론트엔드 프로젝트 시작 시 인프라 세팅 시간 단축.
기술적 일관성: 모든 프론트엔드가 동일한 기술 표준과 디자인 시스템을 공유.

4.4 KiB Raw Permalink Blame History