sample-nuxt-project/.claude/project/architecture.md

아키텍처 (Sample)

레이어 구조

┌───────────────────────────────────┐
│           pages (Nuxt)            │  ← 라우팅, 데이터 페칭 진입점
├───────────────────────────────────┤
│          components               │  ← 재사용 UI (도메인/공용 분리)
├───────────────────────────────────┤
│       composables (use*)          │  ← 상태 + 로직 (뷰 독립)
├───────────────────────────────────┤
│    composables/api (wrapper)      │  ← 서버 통신 단일 창구
├───────────────────────────────────┤
│         server/api                │  ← Nuxt 서버 라우트
└───────────────────────────────────┘

규칙

• 하위 레이어는 상위 레이어를 import 할 수 없습니다. (단방향 의존)
• components 는 비즈니스 로직을 직접 수행하지 않고, composable 에 위임합니다.
• 전역 상태는 필요한 경우에만 Pinia store 로 승격합니다.

데이터 흐름

1. 사용자 이벤트 → components 에서 composable 호출
2. composable → composables/api 래퍼 호출
3. 래퍼 → $fetch 로 Nuxt server/api 또는 외부 API 요청
4. 응답은 타입이 보장된 상태로 composable → component 로 전달

상태 관리 가이드

상태 종류	권장 위치
컴포넌트 로컬 상태	ref / reactive
페이지 단위 공유 상태	provide/inject 또는 composable
앱 전역 상태	Pinia store
서버 데이터	useAsyncData/useFetch