[7팀 윤지훈] Chapter 3-3 기능 중심 아키텍처와 프로젝트 폴더 구조

docs/architecture.md

@@ -0,0 +1,83 @@
+# 프로젝트 아키텍처 가이드 (FSD 기반)
+
+이 문서는 프로젝트의 코드 구조와 아키텍처에 대한 가이드를 제공합니다. 우리는 Feature-Sliced Design (FSD)를 기반으로 한 폴더 구조를 채택하여 코드의 재사용성, 유지보수성, 확장성을 높이는 것을 목표로 합니다.
+
+## 핵심 원칙
+
+- **단일 책임 원칙 (SRP)**: 각 모듈(컴포넌트, 함수 등)은 하나의 책임만을 가집니다.
+- **단방향 의존성**: 코드의 참조는 정해진 방향으로만 흘러야 합니다. 이를 통해 순환 참조를 방지하고 코드의 결합도를 낮춥니다.
+
+## FSD (Feature-Sliced Design) 개념
+
+FSD는 코드를 세 가지 주요 개념으로 구조화합니다.
+
+1.  **레이어 (Layers)**: 코드를 재사용 범위와 의존성 규칙에 따라 수직적으로 나눈 계층 구조입니다. 상위 레이어는 하위 레이어를 참조할 수 있지만, 그 반대는 불가능합니다.
+2.  **슬라이스 (Slices)**: 각 레이어 내에서 코드를 비즈니스 도메인(기능)별로 분할한 단위입니다. 예를 들어, `posts`, `users`, `comments` 등이 슬라이스가 될 수 있습니다.
+3.  **세그먼트 (Segments)**: 슬라이스 내에서 코드를 기술적 목적에 따라 구분한 가장 작은 단위입니다. `ui`, `model`, `api`, `lib` 등이 여기에 해당합니다.
+
+## 폴더 구조 및 레이어 설명
+
+우리 프로젝트는 다음과 같은 6개의 레이어로 구성되며, 아래 순서대로 단방향 의존성 규칙을 따릅니다.
+
+**`app` → `pages` → `widgets` → `features` → `entities` → `shared`**
+
+(왼쪽이 상위 레이어, 오른쪽이 하위 레이어)
+
+---
+
+### 1. `shared`
+
+-   **역할**: 앱의 가장 기본적인 구성 요소를 모아두는 곳입니다. 특정 비즈니스 로직에 의존하지 않는, 프로젝트 전반에서 재사용되는 코드를 포함합니다.
+-   **구성**:
+    -   `ui/`: 재사용 가능한 UI 컴포넌트 (e.g., `Button`, `Input`, `Modal`)
+    -   `api/`: API 클라이언트 인스턴스, 공통 요청/응답 처리 함수 등
+    -   `lib/`: 순수 헬퍼 함수, 유틸리티 (e.g., `formatDate`, `cn`)
+    -   `assets/`: 이미지, 폰트 등 정적 자원
+-   **특징**: 슬라이스 없이 세그먼트로만 구성됩니다. 다른 어떤 레이어에도 의존하지 않습니다.
+
+### 2. `entities`
+
+-   **역할**: 프로젝트가 다루는 핵심 비즈니스 데이터(명사적 개념)와 관련된 코드를 그룹화합니다. 기획이 변경되어도 쉽게 변하지 않는 안정적인 코드입니다.
+-   **예시 슬라이스**: `post`, `user`, `comment`
+-   **구성 (슬라이스 내부)**:
+    -   `model/`: 데이터 타입(`*.types.ts`), 상태 관리 로직(store), 정규화 로직 등
+    -   `ui/`: 해당 데이터를 표현하는 순수 UI 컴포넌트 (e.g., `PostCard`, `UserAvatar`)
+    -   `api/`: 해당 데이터를 다루는 API 함수 (e.g., `getPostById`, `updateUser`)
+-   **의존성**: `shared` 레이어만 참조할 수 있습니다.
+
+### 3. `features`
+
+-   **역할**: 사용자에게 실질적인 가치를 제공하는 동작(동사적 개념)을 구현합니다. 사용자의 액션과 관련된 비즈니스 로직을 포함하며, 기획 변경에 따라 수정될 가능성이 높습니다.
+-   **예시 슬라이스**: `sort-posts`, `add-to-cart`, `authenticate-user`
+-   **구성 (슬라이스 내부)**:
+    -   `ui/`: 기능을 수행하기 위한 UI 컴포넌트 (e.g., `SortPostsButton`, `AddToCartForm`)
+    -   `model/`: 기능과 관련된 상태 관리 로직
+    -   `api/`: 기능을 수행하기 위한 API 연동 코드
+-   **의존성**: `shared`, `entities` 레이어를 참조할 수 있습니다.
+
+### 4. `widgets`
+
+-   **역할**: 여러 `entities`와 `features`를 조합하여 만드는, 독립적으로 작동하는 대규모 UI 블록입니다. 페이지의 특정 구역을 담당하며, 여러 페이지에서 재사용될 수 있습니다.
+-   **예시**: `Header`, `Footer`, `PostsList`, `Sidebar`
+-   **특징**: 자체적인 비즈니스 로직을 거의 가지지 않고, 하위 레이어의 기능들을 엮어주는 역할을 합니다.
+-   **의존성**: `shared`, `entities`, `features` 레이어를 참조할 수 있습니다.
+
+### 5. `pages`
+
+-   **역할**: 애플리케이션의 실제 페이지를 구성하는 진입점입니다. 라우팅 설정에 따라 렌더링되며, 주로 `widgets`와 `features`를 조립하여 최종 화면을 만듭니다.
+-   **예시**: `PostsManagerPage`, `HomePage`, `UserProfilePage`
+-   **특징**: 페이지 단위의 레이아웃을 정의하고, 필요한 데이터를 불러오는 로직을 트리거할 수 있습니다.
+-   **의존성**: `shared`, `entities`, `features`, `widgets` 레이어를 참조할 수 있습니다.
+
+### 6. `app`
+
+-   **역할**: 애플리케이션 전체에 영향을 주는 코드를 관리합니다. 앱의 초기 설정, 전역 스타일, 라우팅, 프로바이더 등을 포함합니다.
+-   **구성**:
+    -   `providers/`: 라우터, 전역 상태 관리자(Store Provider), 테마 등 앱 전체를 감싸는 컴포넌트
+    -   `styles/`: 전역 CSS, reset.css 등
+    -   `main.tsx` / `App.tsx`: 애플리케이션의 진입점
+-   **의존성**: 프로젝트의 모든 레이어를 참조할 수 있습니다.
+
+---
+
+이 가이드를 통해 모든 개발자가 일관된 구조로 코드를 작성하고, 프로젝트의 복잡성을 효과적으로 관리할 수 있기를 기대합니다.

package.json

@@ -9,9 +9,14 @@
     "lint": "eslint .",
     "preview": "vite preview",
     "test": "vitest",
-    "coverage": "vitest run --coverage"
+    "coverage": "vitest run --coverage",
+    "predeploy": "pnpm run build",
+    "deploy": "gh-pages -d dist"
   },
   "dependencies": {
+    "@tanstack/react-query": "^5.90.12",
+    "@tanstack/react-query-devtools": "^5.91.1",
+    "jotai": "^2.16.0",
     "react": "^19.2.1",
     "react-dom": "^19.2.1"
   },
@@ -30,6 +35,7 @@
     "eslint": "^9.39.1",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.4.24",
+    "gh-pages": "^6.3.0",
     "globals": "^16.5.0",
     "jsdom": "^27.2.0",
     "lucide-react": "^0.556.0",