gaegulzip
공통 기능은 한 번만 만들고, 비즈니스에 집중해서 제품을 찍어내는 하이브리드 모노레포.
왜 이 구조인가
- 인증, 푸시, 디자인 시스템 같은 공통 기능을 제품마다 다시 만들기 싫었음
- 서버(Node.js)와 모바일(Flutter) 각각의 생태계 도구를 그대로 쓰면서 하나의 저장소로 관리
- 새 제품을 추가할 때
apps/ 아래에 디렉토리 하나 만들면 공통 인프라를 즉시 사용 가능
아키텍처
gaegulzip/
├── apps/
│ ├── server/ # 공통 백엔드 (Express + Drizzle + PostgreSQL)
│ │ └── src/modules/ # 기능 모듈 (auth, box, notice, push-alert, qna, wod)
│ ├── mobile/ # Flutter 모노레포 (Melos)
│ │ ├── apps/wowa/ # 제품: 크로스핏 WOD 알리미
│ │ ├── apps/design_system_demo/ # 디자인 시스템 데모 앱
│ │ ├── apps/[next-app]/ # 다음 제품은 여기에
│ │ └── packages/ # 공유 패키지
│ │ ├── core/ # DI, 로깅, 유틸리티
│ │ ├── design_system/ # UI 컴포넌트, 테마
│ │ ├── auth_sdk/ # 인증 SDK (소셜 로그인, 토큰 관리, Dio 포함)
│ │ ├── push/ # 푸시 알림 SDK (Dio 포함)
│ │ ├── notice/ # 공지사항 SDK (Dio 포함)
│ │ ├── qna/ # QnA SDK (Dio 포함)
│ │ └── admob/ # Google 광고 SDK
│ └── web/
│ ├── admin/ # 관리자 대시보드 (Next.js 16 + shadcn/ui)
│ └── talmosang/ # AI 두피 분석 웹앱 (Next.js 15 + Tailwind CSS v4)
├── turbo.json # Turborepo (서버/웹 빌드 오케스트레이션)
├── pnpm-workspace.yaml # pnpm 워크스페이스 (Node.js)
└── melos.yaml # Melos (Flutter 패키지 관리)
핵심 설계 결정
| 결정 | 이유 |
|---|
| pnpm + Melos 하이브리드 | Node.js와 Flutter 각각 최적의 패키지 매니저 사용 |
| Express 5 (Controller/Service 패턴 없음) | 미들웨어 함수면 충분. 복잡해지면 그때 분리 (YAGNI) |
| Drizzle ORM + FK 없음 | 앱 레벨에서 관계 관리. DB 마이그레이션 유연성 확보 |
| Flutter packages/ 계층 분리 | core → design_system, SDK → app 단방향 의존. 각 SDK는 독립적 |
| GetX 통일 | 상태 관리 + DI + 라우팅을 하나로. 패키지 간 일관성 |
| Turborepo | 서버 빌드/테스트 캐싱과 병렬 실행 |
의존성 방향 (모바일)
core (기반 - 의존성 없음)
↑
├── design_system (UI 컴포넌트)
├── *_sdk (각 SDK는 자체 Dio + 모델 포함)
└── wowa app (제품 로직, 앱 전용 모델 + 클라이언트 포함)
빠른 시작
# 서버
pnpm install
cp apps/server/.env.example apps/server/.env # 환경변수 설정
pnpm dev:server
# 모바일
cd apps/mobile && melos bootstrap
cd apps/wowa && flutter run
주요 명령어
서버
pnpm dev:server # 개발 서버 (hot reload)
pnpm build:server # 프로덕션 빌드
pnpm test:server # 테스트 (Vitest)
# apps/server 내에서
pnpm db:generate # 마이그레이션 생성
pnpm db:migrate # 마이그레이션 적용
pnpm db:push # 스키마 직접 푸시 (개발용)
모바일
pnpm mobile:bootstrap # 의존성 설치 (flutter pub get 대신)
pnpm mobile:generate # 코드 생성 (Freezed, json_serializable)
pnpm mobile:clean # 빌드 아티팩트 정리
# apps/mobile 내에서
melos generate:watch # 코드 생성 watch 모드
melos analyze # 전체 패키지 정적 분석
웹 (Admin)
pnpm dev:admin # 개발 서버
pnpm build:admin # 프로덕션 빌드
웹 (탈모상)
pnpm dev:talmosang # 개발 서버
pnpm build:talmosang # 프로덕션 빌드
디자인 시스템 데모
pnpm demo # 디자인 시스템 데모 앱 실행
새 제품 추가하는 법
모바일 앱
apps/mobile/apps/ 아래에 Flutter 프로젝트 생성pubspec.yaml에 공유 패키지 path 의존성 추가:
dependencies:
core:
path: ../../packages/core
design_system:
path: ../../packages/design_system
auth_sdk:
path: ../../packages/auth_sdk
melos.yaml의 packages 경로에 이미 apps/**가 포함되어 있으므로 melos bootstrap만 실행
서버 모듈
apps/server/src/modules/ 아래에 디렉토리 생성index.ts (라우터), handlers.ts (핸들러), schema.ts (DB 스키마) 작성app.ts에서 라우터 등록
배포
- 서버: Docker 멀티스테이지 빌드 → Render (싱가포르, free tier)
- 헬스체크:
GET /health
- API 문서:
GET /api-docs (Swagger UI)
- 환경변수는 Render 대시보드에서 설정
- 웹: Vercel (Hobby 플랜, 비상업적 용도)
- Serverless Function 12개 제한
환경변수
서버 (apps/server/.env)
| 변수 | 설명 | 기본값 |
|---|
PORT | 서버 포트 | 3001 |
DATABASE_URL | PostgreSQL 연결 문자열 | - |
JWT_SECRET_FALLBACK | JWT 시크릿 | - |
SUPABASE_URL | Supabase 프로젝트 URL | - |
SUPABASE_ANON_KEY | Supabase anon 키 | - |
LOG_LEVEL | 로그 레벨 | info |
ADMIN_SECRET | 관리자 API 시크릿 | - |
기술 스택
| 영역 | 기술 |
|---|
| 서버 런타임 | Node.js + TypeScript (ES2022) |
| 서버 프레임워크 | Express 5.x |
| ORM / DB | Drizzle ORM + PostgreSQL (Supabase) |
| 모바일 | Flutter (SDK >=3.10.7) |
| 상태 관리 | GetX |
| HTTP 클라이언트 | Dio (각 SDK 독립적으로 포함) |
| 코드 생성 | Freezed + json_serializable |
| 웹 프레임워크 | Next.js 15~16 (App Router) |
| 웹 UI | shadcn/ui + Tailwind CSS v4 (admin) / Tailwind CSS v4 + GSAP (talmosang) |
| 모노레포 | pnpm + Turborepo (서버/웹) / Melos (모바일) |
| 테스트 | Vitest (서버) / Playwright (웹 E2E) / 모바일은 테스트 안 함 |
| 배포 | Docker + Render (서버) / Vercel (웹) |
현재 제품
popup-studio-ai