MODO 프론트엔드 레포지토리입니다.

Stack

• Next.js, TypeScript, TanstackQuery

프로젝트 구조 (FSD Architecture)

src/
├── app/ # Next.js App Router (페이지 라우팅)
│ ├── about/
│ │ └── page.tsx # About 페이지
│ ├── api/ # Next.js API Routes
│ │ └── login/
│ │ └── route.ts # 로그인 API Route (서버 사이드)
│ ├── login/
│ │ └── page.tsx # 로그인 페이지
│ ├── layout.tsx # 루트 레이아웃
│ ├── page.tsx # 홈 페이지
│ └── globals.css # 전역 스타일
│
├── widgets/ # 복합 UI 컴포넌트 (재사용 가능한 위젯)
│ └── login-form/
│ ├── ui/
│ │ └── login-form.tsx # 로그인 폼 컴포넌트
│ └── index.ts # Public API
│
├── features/ # 비즈니스 기능 모듈
│ └── auth/
│ ├── api/
│ │ └── auth.ts # 인증 API 래퍼 (변환 로직 포함)
│ ├── model/
│ │ ├── types.ts # Auth 도메인 타입 정의
│ │ └── mappers.ts # Generated → Refined 타입 변환 함수
│ └── index.ts # Public API
│
├── entities/ # 비즈니스 엔티티 (도메인 모델)
│ └── user/
│ ├── model/
│ │ ├── types.ts # User 엔티티 타입
│ │ └── mappers.ts # API → Entity 변환 함수
│ └── index.ts # Public API
│
└── shared/ # 공유 유틸리티 및 인프라
├── api/
│ ├── generated/ # Swagger에서 자동 생성된 타입 (원본)
│ │ ├── types.example.ts # 예시 파일
│ │ ├── index.ts
│ │ └── README.md
│ ├── auth.ts # 클라이언트용 인증 API (Generated 타입 사용)
│ ├── auth.server.ts # 서버용 인증 API (API Route, Server Component)
│ ├── instance.ts # API 인스턴스 (fetch 래퍼)
│ └── user.ts # User API
├── lib/
│ └── hooks/ # 공유 커스텀 훅
│ ├── use-loading.ts # 로딩 상태 관리 훅
│ └── index.ts
└── ui/ # 공유 UI 컴포넌트
└── button/
└── button.tsx

레이어 설명

📄 app/

Next.js App Router의 페이지 라우팅 레이어

• 각 페이지는 widgets와 features를 조합하여 구성
• app/api/: Next.js API Routes (서버 사이드 엔드포인트)
• 비즈니스 로직은 포함하지 않음 (shared/api 또는 features에 위임)

🧩 widgets/

재사용 가능한 복합 UI 컴포넌트

• 여러 features를 조합하여 완성된 UI 제공
• 비즈니스 로직은 props로 주입받음

⚙️ features/

비즈니스 기능 모듈

• api/: API 호출 및 변환 로직
• model/: 도메인 타입 및 변환 함수
• entities의 타입을 사용하여 도메인 특화 타입 생성

🏗️ entities/

비즈니스 엔티티 (도메인 모델)

• 여러 features에서 공유되는 순수한 도메인 타입
• model/types.ts: 엔티티 타입 정의
• model/mappers.ts: API 응답 → Entity 변환 함수

🔧 shared/

프로젝트 전반에서 공유되는 유틸리티

• api/generated/: Swagger에서 자동 생성된 원본 타입
• api/instance.ts: 클라이언트용 API 호출 인스턴스
• api/*.ts: 클라이언트용 API 함수 (Generated 타입 사용)
• api/*.server.ts: 서버용 API 함수 (API Route, Server Component에서 사용)
• lib/hooks/: 범용 커스텀 React 훅 (예: useLoading)
• ui/: 공유 UI 컴포넌트

데이터 흐름

Swagger 스펙
↓ (자동 생성)
shared/api/generated/types.ts (원본 타입)
↓ (정제)
entities/user/model/types.ts (도메인 모델)
↓ (조합)
features/auth/model/types.ts (도메인 특화 타입)
↓ (변환)
features/auth/api/auth.ts (실제 사용)
↓
widgets/login-form (UI 컴포넌트)
↓
app/login/page.tsx (페이지)

타입 정제 원칙

1. Generated 타입은 내부적으로만 사용 - 외부에 노출하지 않음
2. Entity는 도메인 모델 - 여러 feature에서 공유 가능
3. Feature 타입은 도메인 특화 - Entity를 조합하여 사용
4. 변환은 API 레이어에서 - 외부에서는 정제된 타입만 노출