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 레이어에서 - 외부에서는 정제된 타입만 노출