Global Nomad

체험(액티비티) 탐색 · 예약 · 관리 서비스를 제공하는 프론트엔드 프로젝트입니다.
Next.js App Router를 기반으로 FSD(Feature-Sliced Design) 구조를 채택하고,
도메인 로직은 DDD-lite 방식으로 점진적으로 확장할 수 있도록 설계했습니다.

---

🧱 아키텍처 개요

• Framework: Next.js (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• Architecture: FSD + DDD-lite
• Lint / Format: ESLint(v9 Flat Config) + Prettier
• Git Workflow: Husky + lint-staged + commitlint

아키텍처 잡은 기준

• app 디렉토리는 라우팅과 레이아웃만 담당
• 비즈니스 로직은 features / entities에만 존재
• API 네이밍과 도메인 구분은 Swagger 스펙 기준

---

📁 폴더 구조 (하위구조는 네임이 정확하지 않을수있습니다 작업자가 스웨거에 맞춰서 넣어주세요 )

src/
├─ app/                              # Next.js App Router (라우팅/조합 전용)
│  ├─ (auth)/                        # 인증 관련 라우트 그룹
│  │  ├─ login/
│  │  │  └─ page.tsx
│  │  └─ signup/
│  │     └─ page.tsx
│  │
│  ├─ (public)/                      # 로그인 없이 접근 가능한 영역
│  │  ├─ main/
│  │  │  └─ page.tsx
│  │  └─ activities/
│  │     ├─ [activityId]/
│  │     │  └─ page.tsx
│  │     └─ page.tsx
│  │
│  ├─ (mypage)/                      # 로그인 후 개인 영역
│  │  ├─ profile/
│  │  │  └─ page.tsx
│  │  ├─ reservations/
│  │  │  └─ page.tsx
│  │  ├─ experiences/
│  │  │  └─ page.tsx
│  │  └─ booking-status/
│  │     └─ page.tsx
│  │
│  └─ layout.tsx                     # 전역 레이아웃
│
├─ api/                              # BFF 계층 (Route Handlers)
│
├─ features/                         # 사용자 행동 단위 (Use Case)
│  ├─ auth/
│  │  ├─ login/
│  │  │  ├─ ui/
│  │  │  ├─ model/
│  │  │  └─ index.ts
│  │  └─ signup/
│  │     ├─ ui/
│  │     ├─ model/
│  │     └─ index.ts
│  │
│  ├─ activity/
│  │  ├─ list/
│  │  ├─ detail/
│  │  ├─ register/
│  │  └─ reservation/
│  │
│  ├─ review/
│  │  ├─ create/
│  │  └─ list/
│  │
│  ├─ notification/
│  │  ├─ list/
│  │  └─ panel/
│  │
│  └─ profile/
│     └─ edit/
│
├─ entities/                         # 도메인 단위 (DDD-lite)
│  ├─ activity/
│  │  ├─ model/
│  │  └─ api/
│  │
│  ├─ reservation/
│  │  ├─ model/
│  │  └─ api/
│  │
│  ├─ user/
│  │  ├─ model/
│  │  └─ api/
│  │
│  └─ notification/
│     ├─ model/
│     └─ api/
│
├─ widgets/                          # 페이지 레벨 UI 블록
│  ├─ header/
│  ├─ footer/
│  ├─ side-nav/
│  └─ modal/
│
├─ shared/                           # 전역 재사용 영역
│  ├─ ui/                            # 공통 UI 컴포넌트
│  ├─ hooks/                         # 공통 훅
│  ├─ lib/
│  │  ├─ index.ts                    # 공개 API
│  │  └─ internal/                  # 내부 구현 (직접 import 금지)
│  ├─ config/                        # 환경 설정, 상수
│  ├─ types/                         # 전역 타입
│  └─ assets/                        # 정적 자산
│
└─ styles/                           # 글로벌 스타일

---

예시: 로그인 기준 역할 분리 (폴더·파일 단위 명세)

features/auth/login/

features/auth/login/
├─ ui/
│  ├─ LoginForm.tsx
│  ├─ LoginButton.tsx
│  └─ LoginErrorMessage.tsx
│
├─ model/
│  ├─ useLoginForm.ts        // 입력 상태, validation
│  ├─ useLoginSubmit.ts     // submit 트리거, 흐름 제어
│  ├─ login.schema.ts       // form / zod schema
│  └─ login.types.ts
│
└─ index.ts                 // 외부 공개 API

→ 사용자가 로그인하는 행동 단위 (입력, 버튼 클릭, 로딩/에러 처리, 성공 후 이동)

---

entities/user/model/

entities/user/model/
├─ user.types.ts            // User, Role, Token 타입
├─ user.entity.ts           // 사용자 개념 정의
├─ user.mapper.ts           // API 응답 → 도메인 변환
└─ index.ts

→ 로그인된 사용자에 대한 도메인 개념 (User, Role, Token 구조 등 상태와 결과 정의)

---

entities/user/api/

entities/user/api/
├─ login.ts                 // 로그인 요청
├─ refreshToken.ts          // 토큰 재발급
├─ getMe.ts                 // 내 정보 조회
└─ index.ts

→ 사용자 관련 외부 API 호출 (endpoint, request/response 타입 정의)

---

app/api/auth/login/

app/api/auth/login/
└─ route.ts

→ 인증 처리를 위한 서버 중계(BFF) (쿠키 저장, 토큰 보호, 응답 가공)

---

역할 요약

features     = 사용자 행동(Use Case)
entities     = 도메인 개념과 상태
entities/api = 외부 API 호출
app/api      = 보안 및 서버 중계(BFF)

---

구조 규칙

• features는 entities를 사용한다
• entities는 features를 알지 못한다
• app/api는 클라이언트에서 직접 import하지 않는다
• page.tsx는 feature를 조합만 한다