클라이언트 앱 프로젝트 구조 가이드
작성일: 2026-04-06 Last Updated: 2026-04-06 대상: Browser Extension, Tauri Desktop App, Flutter Mobile App
1. 모노레포 vs 독립 레포 전략
의사결정 매트릭스
| 기준 | 모노레포 권장 | 독립 레포 권장 |
|---|---|---|
| 공유 코드 비율 > 30% | O | |
| 팀 규모 < 10명 | O | |
| 릴리즈 주기 동일 | O | |
| 플랫폼별 팀 분 리 | O | |
| CI/CD 파이프라인 독립 필요 | O | |
| 스토어 심사 주기 다름 | O |
본 프로젝트 권장: 모노레포 + 플랫폼별 서브 디렉토리
platform/client/
+-- packages/ # 공유 패키지
| +-- shared-types/ # TypeScript/Dart 타입 정의
| +-- api-client/ # API 클라이언트 (자동 생성)
| +-- constants/ # 공유 상수
| +-- i18n/ # 번역 리소스
| +-- theme/ # 공유 테마 토큰
|
+-- browser-ext/ # Chrome/Firefox 확장
+-- tauri/ # Tauri 데스크톱 앱
+-- flutter/ # Flutter 모바일 앱
+-- tools/ # 빌드 도구, 코드 생성기
2. 각 플랫폼별 권장 폴더 구조
2.1 Browser Extension (Chrome/Firefox)
browser-ext/
+-- manifest.json # Manifest V3 (Chrome) / V2 호환 (Firefox)
+-- src/
| +-- background/ # Service Worker (Manifest V3)
| | +-- index.ts
| | +-- listeners/ # 이벤트 리스너
| | +-- alarms/ # 주기 작업
| +-- content/ # Content Scripts
| | +-- index.ts
| | +-- injectors/ # DOM 조작
| +-- popup/ # Popup UI
| | +-- App.tsx
| | +-- pages/
| | +-- components/
| +-- options/ # Options 페이지
| +-- sidepanel/ # Side Panel (Chrome 114+)
| +-- shared/ # 확장 내부 공유
| | +-- api/ # API 클라이언트
| | +-- storage/ # chrome.storage 래퍼
| | +-- auth/ # 인증 모듈
| | +-- i18n/ # 번역 (chrome.i18n 래퍼)
| | +-- hooks/ # React hooks
| | +-- utils/ # 유틸리티
| +-- types/ # TypeScript 타입
+-- public/
| +-- icons/ # 아이콘 (16, 32, 48, 128)
| +-- _locales/ # chrome.i18n 번역 파일
+-- tests/
| +-- unit/
| +-- e2e/
+-- scripts/ # 빌드 스크립트
| +-- build-chrome.ts
| +-- build-firefox.ts
+-- .web-ext/ # web-ext 설정 (Firefox)
+-- vite.config.ts # 또는 webpack.config.ts
+-- tsconfig.json
+-- package.json
2.2 Tauri Desktop App (Win/Mac/Linux)
tauri/
+-- src-tauri/ # Rust 백엔드
| +-- src/
| | +-- main.rs
| | +-- lib.rs
| | +-- commands/ # Tauri 커맨드 (IPC)
| | +-- plugins/ # Tauri 플러그인
| | +-- services/ # Rust 서비스
| | +-- state/ # 앱 상태 관리
| | +-- tray/ # 시스템 트레이
| | +-- updater/ # 자동 업데이트
| +-- Cargo.toml
| +-- tauri.conf.json # Tauri 설정
| +-- capabilities/ # Tauri v2 권한
| +-- icons/ # 앱 아이콘 (각 OS별)
+-- src/ # 프론트엔드 (React/Vue/Svelte)
| +-- App.tsx
| +-- pages/ # 페이지 컴포넌트
| +-- components/ # UI 컴포넌트
| +-- layouts/ # 레이아웃
| +-- features/ # 기능별 모듈 (아래 상세)
| +-- shared/ # 공유 모듈
| | +-- api/ # API 클라이언트
| | +-- auth/ # 인증
| | +-- i18n/ # 다국어
| | +-- store/ # 상태 관리
| | +-- hooks/ # 커스텀 hooks
| | +-- utils/ # 유틸리티
| +-- types/ # TypeScript 타입
+-- tests/
| +-- unit/
| +-- e2e/ # WebDriver 기반 E2E
+-- scripts/ # 빌드/서명 스크립트
+-- package.json
+-- tsconfig.json
+-- vite.config.ts
2.3 Flutter Mobile App (iOS/Android)
flutter/
+-- lib/
| +-- main.dart
| +-- app/ # 앱 진입점
| | +-- app.dart # MaterialApp 설정
| | +-- router.dart # 라우팅 (go_router)
| | +-- di.dart # 의존성 주입 (get_it/riverpod)
| +-- features/ # 기능별 모듈 (아래 상세)
| | +-- auth/
| | +-- home/
| | +-- settings/
| +-- core/ # 앱 핵심 모듈
| | +-- api/ # API 클라이언트 (dio)
| | +-- auth/ # 인증 서비스
| | +-- storage/ # 로컬 저장소 (secure_storage)
| | +-- i18n/ # 다국어
| | +-- theme/ # 테마
| | +-- error/ # 에러 핸들링
| | +-- constants/ # 상수
| +-- shared/ # 공유 위젯/유틸
| | +-- widgets/ # 공용 위젯
| | +-- extensions/ # Dart extensions
| | +-- utils/ # 유틸리티
| +-- l10n/ # ARB 번역 파일
+-- test/
| +-- unit/
| +-- widget/
| +-- integration/
+-- ios/ # iOS 네이티브
+-- android/ # Android 네이티브
+-- assets/ # 에셋 (이미지, 폰트)
| +-- images/
| +-- fonts/
| +-- icons/
+-- scripts/ # 빌드/배포 스크립트
+-- pubspec.yaml
+-- analysis_options.yaml
+-- l10n.yaml # flutter_localizations 설정
3. 기능별 모듈화 패턴
Feature-First 구조 (권장)
각 기능(feature)은 독립적인 폴더로 분리하 며, 내부에 필요한 모든 레이어를 포함한다.
features/
+-- auth/
| +-- data/ # 데이터 레이어 (API 호출, 로컬 저장)
| | +-- auth_repository.ts (또는 .dart)
| | +-- auth_api.ts
| +-- domain/ # 도메인 레이어 (비즈니스 로직)
| | +-- models/
| | +-- use_cases/
| +-- presentation/ # UI 레이어
| | +-- pages/
| | +-- components/
| | +-- hooks/ (또는 providers/)
| +-- index.ts (또는 barrel file)
+-- dashboard/
| +-- data/
| +-- domain/
| +-- presentation/
| +-- index.ts
플랫폼별 적용
| 패턴 | Browser Ext | Tauri | Flutter |
|---|---|---|---|
| Feature-First | O (popup/options 내) | O (src/features/) | O (lib/features/) |
| Clean Architecture | 선택적 | 권장 | 강력 권장 |
| Barrel Exports | index.ts | index.ts | barrel .dart |
| 상태 관리 | Zustand/Jotai | Zustand/Jotai | Riverpod/BLoC |
4. Starter-Kit 필수 공통 모듈
모든 클라이언트에 반드시 포함해야 하는 모듈 목록.
| 모듈 | 설명 | 최소 요구사항 |
|---|---|---|
api/ | API 클라이언트 | Base URL 설정, 인터셉터, 에러 핸들링 |
auth/ | 인증 | OAuth 2.0 PKCE, 토큰 관리, 자동 갱신 |
storage/ | 로컬 저장소 | 보안 저장, 일반 저장, 캐시 |
i18n/ | 다국어 | 최소 한국어/영어, 언어 감지 |
theme/ | 테마 | 라이트/다크 모드, 시스템 연동 |
error/ | 에러 처리 | 글로벌 에러 핸들러, 크래시 리포팅 |
analytics/ | 분석 | 이벤트 트래킹, 사용자 동의 |
update/ | 앱 업데이트 | 자동 업데이트, 강제 업데이트 |
logger/ | 로깅 | 개발/프로덕션 분리, 원격 로깅 |
config/ | 설정 | 환경별 설정, Feature flags |
permissions/ | 권한 | 런타임 권한 요청/상태 관리 |
deeplink/ | 딥링크 | URL 스킴, Universal Links |
플랫폼별 추가 모듈
| 모듈 | Browser Ext | Tauri | Flutter |
|---|---|---|---|
tray/ (시스템 트레이) | - | 필수 | - |
notification/ | chrome.notifications | tauri-plugin-notification | flutter_local_notifications |
clipboard/ | navigator.clipboard | tauri-plugin-clipboard | clipboard 패키지 |
filesystem/ | - | tauri-plugin-fs | path_provider |
biometric/ | - | - | local_auth |
5. 네이밍 컨벤션
파일/폴더 네이밍
| 대상 | 컨벤션 | 예시 |
|---|---|---|
| 폴더명 | kebab-case | auth-service/, api-client/ |
| TS/JS 파일 | kebab-case | auth-service.ts, use-auth.ts |
| Dart 파일 | snake_case | auth_service.dart, login_page.dart |
| React 컴포넌트 | PascalCase | LoginForm.tsx, UserAvatar.tsx |
| Flutter 위젯 | snake_case (파일), PascalCase (클래스) | login_form.dart / LoginForm |
| 테스트 파일 | *.test.ts / *_test.dart | auth.test.ts, auth_test.dart |
| 타입 정의 | *.types.ts / *.d.ts | auth.types.ts |
| 상수 파일 | constants.ts / constants.dart | UPPER_SNAKE_CASE 내부 |
| 환경 설정 | .env.* | .env.development, .env.production |
코드 네이밍
| 대상 | TS/JS | Dart |
|---|---|---|
| 변수/함수 | camelCase | camelCase |
| 클래스 | PascalCase | PascalCase |
| 상수 | UPPER_SNAKE_CASE | lowerCamelCase (Dart 관례) |
| Enum | PascalCase (멤버도) | PascalCase (멤버는 camelCase) |
| Private | #field 또는 _prefix | _prefix |
| 인터페이스 | IAuthService 또는 AuthService | abstract class |
| Type alias | PascalCase | typedef PascalCase |
모듈 Export 패턴
// TypeScript - index.ts (barrel export)
export { AuthService } from './auth-service';
export { useAuth } from './use-auth';
export type { AuthUser, AuthToken } from './auth.types';
// Dart - auth.dart (barrel export)
library auth;
export 'auth_service.dart';
export 'auth_repository.dart';
export 'models/auth_user.dart';
6. 스토어 심사 관련 구조 요구사항
Chrome Web Store
| 요구사항 | 구조 반영 |
|---|---|
| Manifest V3 필수 | manifest.json v3 형식 |
| Service Worker 제한 | background/ 폴더에 SW 패턴 적용 |
| 최소 권한 | manifest.json에 optional_permissions 활용 |
| 원격 코드 금지 | 모든 코드 번들에 포함, CDN 사용 불가 |
| 개인정보 처리방침 | docs/privacy-policy.md 포함 |
| 단일 목적 | 기능별 모듈화로 심사 시 목적 명확화 |
Apple App Store
| 요구사항 | 구조 반영 |
|---|---|
| 앱 아이콘 (1024x1024) | ios/Runner/Assets.xcassets/ |
| Launch Screen | ios/Runner/LaunchScreen.storyboard |
| Privacy manifest | ios/Runner/PrivacyInfo.xcprivacy (iOS 17+) |
| 데이터 수집 고지 | docs/privacy-labels.md |
| NSUserTrackingUsageDescription | ios/Runner/Info.plist |
| 최소 배포 대상 | ios/Podfile - iOS 15.0+ 권장 |
Google Play Store
| 요구사항 | 구조 반영 |
|---|---|
| 타겟 SDK 최신 | android/app/build.gradle - targetSdkVersion |
| 데이터 안전 섹션 | docs/data-safety.md |
| 앱 서명 (AAB) | scripts/build-android.sh - AAB 출력 |
| Adaptive Icon | android/app/src/main/res/mipmap-*/ |
| 권한 최소화 | AndroidManifest.xml 필수 권한만 |
macOS/Windows/Linux (Tauri)
| 요구사항 | 구조 반영 |
|---|---|
| macOS 코드 서명 | scripts/sign-macos.sh + notarization |
| Windows 코드 서명 | scripts/sign-windows.sh + EV 인증서 |
| Linux AppImage/deb | src-tauri/tauri.conf.json 번들 설정 |
| 자동 업데이트 | src-tauri/updater/ + 서명 키 관리 |
| 권한 선언 (Tauri v2) | src-tauri/capabilities/ |
7. 체크리스트: 프로젝트 초기 셋업
- 모노레포 구조 생성 (
platform/client/) - 공유 패키지 폴더 생성 (
packages/) - 각 플랫폼 폴더 생성 및 초기화
- Starter-Kit 필수 모듈 12개 스캐폴딩
- 네이밍 컨벤션 린터 설정 (ESLint/Dart analyzer)
- 환경 설정 파일 분리 (dev/staging/prod)
- CI/CD 파이프라인 기본 구성
- 스토어 심사용 메타데이터 폴더 생성
- README.md 작성 (각 플랫폼별)
-
.gitignore플랫폼별 설정