GAK (모여서 각자 작업)
링크 하나로 빠르게 모여서, 제한된 시간 동안 각자 작업에 몰입하는 협업 플랫폼
MVP 상태
- 2026년 3월 기준 1차 MVP 개발 완료
- 단일 README에서 서비스 가치, 구현 범위, 재현 방법, 품질 검증 근거를 함께 제공
- 1순위 독자: 채용/포트폴리오 리뷰어 및 신규 기여자
핵심 사용자 흐름 (현재 구현 기준)
- 로그인
- 세션 탐색 및 생성
- 홈에서 세션 검색/필터/추천 목록 조회
- 세션 생성 폼으로 카테고리, 시작 시간, 진행 시간, 목표 기준 설정
- 세션 참여 및 대기방
- 목표/할 일 설정 후 입장
- 대기 인원 상태를 SSE로 실시간 반영
- 세션 진행
- 동기화된 타이머 기반 집중 진행
- 참여자 상태(집중/자리 비움), 할 일 진행률, 리액션 이벤트 반영
- 세션 종료 및 결과
- 집중 시간/참여 시간 제출
- 세션 결과 화면과 참여자 리포트 확인
- 프로필/마이페이지
- 프로필 정보 수정, 관심 카테고리 관리
- 개인 리포트(세션 히스토리/통계) 확인
현재 범위 외 (후속 계획)
- 세션 내 실시간 채팅: 실험용 UI 컴포넌트만 존재, 현재 프로덕션 플로우에서는 비활성
- BGM(노동요): 아직 미구현
기술 스택
| 분류 | 기술 |
|---|
| Framework | Next.js 16 (App Router) |
| UI | React 19, Tailwind CSS v4, Storybook |
| Language | TypeScript |
| Data/State | TanStack Query, Zustand |
| Validation/Form | Zod, React Hook Form |
| Realtime | SSE (Server-Sent Events) |
| Test | Jest, Vitest, Testing Library |
| CI/CD | GitHub Actions, Chromatic, Vercel |
아키텍처 요약
- App Router 기반 렌더링
- 페이지/레이아웃은
src/app에서 구성하고, 서버/클라이언트 컴포넌트를 역할에 따라 분리
- BFF 레이어
src/app/api/**/route.ts에서 프런트 전용 API 경계를 제공src/lib/api/api-route-forwarder.ts를 통해 인증 쿠키 전달, 에러 응답 형식, 백엔드 요청 처리를 일관되게 관리
- 프록시 기반 인증 처리
src/proxy.ts에서 공개/보호 경로 분기, 토큰 만료 임박 시 리프레시 자동 시도
- SSE 실시간 이벤트
- 대기방/진행상태/리액션 이벤트를
src/app/api/sse/** + 클라이언트 훅으로 구독
- 데이터 계층
- React Query 기반으로 도메인별 query key 규칙과 공통 훅 패턴을 사용해 조회/캐시 무효화 로직을 표준화
구조적 포인트
이 프로젝트는 기능 구현뿐 아니라, 프런트엔드에서 반복적으로 발생하는 API 호출/캐시 관리 문제를 일관된 규칙으로 다루는 데 초점을 맞췄습니다.
- API Layer
- Route Handler와 공통 forwarder를 통해 인증 쿠키 전달, 백엔드 포워딩, 에러 응답 형식을 프런트 전용 API 경계에서 일관되게 관리합니다.
- Factory 기반 아키텍처
- 반복되는 CRUD/Singleton Query 훅 패턴은 공통 factory 형태로 추상화해 도메인별 훅 구현에서 중복을 줄이고 동일한 사용 방식을 유지하도록 구성했습니다.
- Query Key 자동 생성 로직
- 도메인별 query key는 계층 구조로 생성해 목록, 상세, 단일 리소스 캐시를 예측 가능한 규칙으로 무효화할 수 있도록 정리했습니다.
시작하기
Prerequisites
- Node.js
22.21.1 (.nvmrc)
- Corepack (Node.js 내장)
- pnpm
10.27.0 (packageManager)
설치 및 로컬 실행
# 1. 저장소 클론
git clone https://github.com/dnd-side-project/dnd-14th-9-frontend.git
cd dnd-14th-9-frontend
# 2. pnpm 활성화
corepack enable
# 3. 의존성 설치
pnpm install
# 4. Git hooks 설정 (최초 1회)
pnpm prepare
# 5. 개발 서버 실행 (토큰 빌드 watch + Next dev 동시 실행)
pnpm dev
주요 스크립트
| 명령어 | 설명 |
|---|
pnpm dev | 토큰 watch + Next 개발 서버 실행 |
pnpm build | 디자인 토큰 생성 후 프로덕션 빌드 |
pnpm start | 프로덕션 서버 실행 |
pnpm storybook | Storybook 로컬 실행 (:6006) |
pnpm build-storybook | Storybook 정적 빌드 |
pnpm test | Jest 테스트 실행 |
pnpm test:auth-concurrency | 빌드 후 Refresh Token 다중 인스턴스 통합 검증 |
pnpm test:coverage | 커버리지 포함 테스트 |
pnpm lint | ESLint 검사 |
pnpm typecheck | TypeScript 타입 검사 |
pnpm codegen | Orval 기반 API 클라이언트 코드 생성 |
pnpm tokens | Style Dictionary 기반 디자인 토큰 생성 |
환경 변수 계약 (.env.local)
이 프로젝트는 .env.example 대신 실제 사용 키를 기준으로 환경을 구성합니다.
아래 키를 .env.local에 설정하세요.
보안 원칙
- 실제 토큰/시크릿 값은 절대 저장소에 커밋하지 않습니다.
NEXT_PUBLIC_* 변수는 브라우저에 노출되므로 비밀값을 넣지 않습니다..env*는 기본적으로 .gitignore에 포함되어 있습니다.
| 키 | 필수 | 예시 | 용도 |
|---|
BACKEND_API_BASE | 필수 | https://<backend-api-origin> | 서버 측 API 호출 기본 URL, 프록시 토큰 재발급 호출 |
BACKEND_ORIGIN | 필수 | https://<backend-origin> | OAuth 인가 URL 생성 기준 origin |
FRONTEND_ORIGIN | 필수 | http://localhost:3000 | 서버 측 프런트 오리진 참조 |
NEXT_PUBLIC_BACKEND_API_BASE | 필수 | https://<backend-api-origin> | 클라이언트/API 호출 및 sitemap 데이터 소스 |
NEXT_PUBLIC_BACKEND_ORIGIN | 필수 | https://<backend-origin> | 백엔드 origin 공개값 (OAuth fallback) |
NEXT_PUBLIC_FRONTEND_ORIGIN | 필수 | https://<frontend-origin> | SEO canonical, metadata base URL |
NEXT_PUBLIC_ENABLE_DEVTOOLS | 선택 | true | 개발 환경 React Query Devtools 노출 제어 |
NEXT_PUBLIC_GOOGLE_ANALYTICS | 선택 | G-XXXXXXXXXX | Google Analytics 스크립트 주입 |
NEXT_PUBLIC_GOOGLE_VERIFICATION | 선택 | <google-verification-token> | Google Search Console 검증 |
NEXT_PUBLIC_NAVER_VERIFICATION | 선택 | <naver-verification-token> | 네이버 웹마스터 검증 |
NEXT_PUBLIC_WS_URL | 선택 | ws://localhost:8080 | 웹소켓 클라이언트 기본 주소 |
BACKEND_URL | 선택 | https://<backend-origin> | BACKEND_ORIGIN 미지정 시 fallback |
NEXT_PUBLIC_BACKEND_URL | 선택 | https://<backend-origin> | NEXT_PUBLIC_BACKEND_ORIGIN 미지정 시 fallback |
NEXT_PUBLIC_API_URL | 선택 | https://<backend-api-origin> | API URL 호환용 fallback |
|
품질 보증 현황 (2026-03-06 기준)
- CI 파이프라인 (
.github/workflows/ci.yml)
main 대상 PR 생성 및 업데이트 시 lint -> 기존 Jest 단계 -> 어댑터 빌드 회귀 검사 -> build -> 인증 동시성 통합 검증 실행- 기존 Jest 단계의 인수 전달 및 coverage 문제는 #358에서 별도로 복구하며, 전체 테스트 확인에는
pnpm test:coverage --ci --coverageProvider=v8를 사용
- 어댑터 빌드 회귀 검사 (
scripts/test-next-adapter-build.mjs)
- 최소
onBuildComplete 어댑터를 연결해 실제 앱을 clean build하고, 어댑터와 출력 설정의 호환성을 검증
- 실행 전후
.next를 정리하므로 개발 서버나 다른 빌드와 병렬 실행하지 않으며, 이후 pnpm build로 일반 실행 결과물을 생성
- 인증 동시성 통합 검증 (
scripts/auth-refresh-concurrency.mjs)
- 동일한 프로덕션 빌드를 사용하는 독립
next start 프로세스 2개에서 회전형 Refresh Token 경합과 백엔드 멱등 계약을 로컬 가짜 백엔드로 검증
- 실제 백엔드 구현이 아니라 동일 Refresh Token에 동일 결과를 반환하는 계약의 프론트엔드 호환성을 검증
- UI 변경 검증 (
.github/workflows/chromatic.yml)
- 스토리/디자인 토큰/스토리북 설정 변경 시 Chromatic 자동 실행
- 테스트 및 스토리 자산 규모
- 테스트 파일:
27개 (src/test/**)
- 스토리 파일:
24개 (src/stories/**/*.stories.tsx|ts)
- 배포 빌드
- Vercel이 Next.js 빌드 결과물을 패키징해 배포하며, standalone 출력 및 Docker 이미지 빌드는 사용하지 않음
관련 링크
팀원 (Contributors)
라이선스
MIT License. 자세한 내용은 LICENSE를 참고하세요.
