프론트엔드 개요
Lumie의 프론트엔드는 공개 사이트, 인증 플로우, 테넌트 온보딩, 직원용 관리자 워크스페이스, 학생 대시보드를 제공하는 Next.js 16 App Router 애플리케이션입니다. 라우팅은 app/에 있고, 제품 로직은 src/에 있으며, 브라우저 요청은 브라우저에서 백엔드를 직접 호출하지 않고 프론트엔드 자체의 /api 프록시를 거칩니다.
이 리포지토리가 담당하는 것
- 공개 마케팅 페이지와 academy 랜딩 페이지
- 로그인, 회원가입, OAuth 콜백, 세션 refresh 플로우
- 회원가입 후 owner 온보딩
/admin아래의 관리자용 academy 운영 페이지/dashboard아래의 학생용 페이지- 프론트엔드 측 프록시, 인증 쿠키 처리, 테넌트 헤더 전달
런타임 형태
로컬 개발에서는 프론트엔드가 http://localhost:3000에서 실행되고, 백엔드와 상태 저장 서비스는 dev 클러스터에서 실행됩니다. 브라우저 코드는 /api/v1/...를 호출하고, app/api/[...path]/route.ts가 그 요청을 NEXT_PUBLIC_API_BASE로 전달하며, localhost 쿠키를 위해 응답 헤더를 다시 쓰고, 커스텀 도메인 해석이 활성화되어 있으면 테넌트 컨텍스트를 붙입니다.
app/layout.tsx의 루트 레이아웃은 다음을 연결합니다.
- TanStack Query용
QueryProvider AuthModalUrlSync와 공유 인증 모달- 전역
Toaster - 로컬 Noto Sans KR 폰트와 문서 셸
주요 구현 규칙
| 영역 | 현재 접근 방식 |
|---|---|
| 라우팅 | 라우트 그룹과 중첩 레이아웃을 사용하는 Next.js App Router |
| 애플리케이션 구조 | src/ 아래 Feature-Sliced Design |
| 서버 상태 | TanStack Query |
| 클라이언트 UI 상태 | Zustand와 로컬 컴포넌트 상태 |
| 폼 | Zod 검증을 결합한 React Hook Form |
| API 클라이언트 | 공유 fetch 레이어와 Orval 생성 hook/쿼리 헬퍼 |
| E2E 테스트 | Playwright |
| 단위 테스트 | jsdom 환경의 Vitest |
코드 맵
| 경로 | 책임 |
|---|---|
app/ | 라우트, 레이아웃, 로딩 상태, 에러 바운더리, route handler |
src/shared/ | API 기본 요소, 설정, 범용 UI, provider, 유틸리티 |
src/entities/ | 도메인 모델, 생성된 API hook, 엔티티 수준 헬퍼 |
src/features/ | 사용자 액션과 기능별 UI 또는 상태 |
src/widgets/ | 헤더, 사이드바, 인증 모달 같은 조합된 화면과 셸 |
components/ui/ | 관례상 리포지토리 루트에 유지되는 포크된 shadcn 기본 요소 |
소스 경로
| 주장 | 소스 경로 |
|---|---|
same-origin /api 프록시와 쿠키 재작성 | lumie-frontend/app/api/[...path]/route.ts |
브라우저 API base는 /api | lumie-frontend/src/shared/config/env.ts |
| 루트 provider와 전역 셸 | lumie-frontend/app/layout.tsx |
| TanStack Query provider | lumie-frontend/src/shared/providers/QueryProvider.tsx |
| Feature-Sliced Design alias | lumie-frontend/tsconfig.json |
검증
cd lumie-frontend
rg -n "API_URL: '/api'|app/api/\\[\\.\\.\\.path\\]|QueryProvider|@/shared" \
app src tsconfig.json
npm run type-check
성공 기준은 grep이 프록시, 루트 provider, FSD alias 경계를 찾아내고, npm run type-check가 TypeScript 오류 없이 완료되는 것입니다.