[P-Reinforce] Wikify Modern React Standards and ConnectAI Optimization Plan

00_Raw/확장 가능한 React 아키텍처 및 폴더 구조 설계.md

@@ -0,0 +1,73 @@
+# [[확장 가능한 React 아키텍처 및 폴더 구조 설계]]
+
+## 📌 Brief Summary
+확장 가능한 React 아키텍처 및 폴더 구조 설계란 애플리케이션이 성장함에 따라 발생하는 복잡성을 제어하고, 유지보수성과 팀 협업 효율을 높이기 위해 코드를 논리적이고 예측 가능하게 조직하는 방법입니다. 기존의 파일 유형별 분류를 넘어, 비즈니스 도메인을 중심으로 코드를 그룹화하는 '기능 기반(Feature-Based)' 구조와 단방향 의존성을 강제하는 'Feature-Sliced Design (FSD)' 같은 계층적 모델이 널리 사용됩니다. 이를 통해 컴포넌트 간의 강한 결합도를 낮추고, 각 기능의 독립적인 개발과 안전한 리팩토링을 보장할 수 있습니다.
+
+## 📖 Core 소스에 기반한 Core Content
+*   **폴더 구조의 진화와 하이브리드/기능 기반 접근**
+    초기 React 프로젝트는 `components`, `hooks`, `styles`와 같이 기술적 파일 유형에 따라 폴더를 나누는 방식이 흔했으나, 앱이 확장되면 관련된 기능 로직이 여러 폴더에 파편화되어 유지보수가 매우 어려워집니다. 2025년 기준 권장되는 방식은 기능(Feature)이나 비즈니스 도메인을 중심으로 조직하는 하이브리드 혹은 기능 기반 구조입니다. 예를 들어 `/features/auth` 폴더 내부에 해당 기능의 컴포넌트, 훅, API 로직, 타입 정의 등을 응집시켜 독립적인 모듈처럼 구성합니다. 공유되는 UI 컴포넌트나 유틸리티는 `/components`, `/utils` 등에 별도로 둡니다.
+*   **Feature-Sliced Design (FSD) 방법론**
+    FSD는 프론트엔드 프로젝트를 위한 명확하고 강제력 있는 계층형 아키텍처입니다. 코드를 범위와 책임에 따라 `app`(글로벌 설정), `pages`(라우팅), `widgets`(독립적 UI 블록), `features`(사용자 상호작용 및 비즈니스 로직), `entities`(핵심 비즈니스 모델), `shared`(재사용 가능한 유틸리티) 등 6가지 레이어로 나눕니다. 가장 중요한 규칙은 '단방향 의존성'으로, 상위 레이어는 하위 레이어를 참조할 수 있지만 하위 레이어는 상위 레이어를 참조할 수 없습니다. 또한 각 슬라이스는 `index.ts`를 통한 'Public API'만을 노출하여 내부 구현을 캡슐화합니다.
+*   **관심사 분리와 상태 및 성능 관리**
+    규모가 큰 시스템에서 비즈니스 로직과 UI를 명확히 분리하는 것은 필수입니다. 전역 상태 관리에 있어서, 빈번하게 변경되는 상태(예: 장바구니, 알림)를 다룰 때 React의 내장 Context API를 사용하면 구독 중인 모든 하위 컴포넌트가 불필요하게 리렌더링되는 성능 병목이 발생합니다. 이를 피하기 위해 Zustand나 Redux 같은 특화된 상태 관리 도구를 활용해 선택적 리렌더링(Selector Pattern)을 적용해야 합니다. 서버에서 가져오는 데이터 상태의 경우, TanStack Query와 같은 전용 라이브러리를 통해 클라이언트 상태와 엄격히 분리하여 `/features` 내부에 위치시킵니다.
+*   **명명 규칙(Naming Conventions)과 거버넌스**
+    파일 및 폴더 이름을 일관되게 관리하는 것은 협업 시 혼란을 방지합니다. React 컴포넌트 파일은 `PascalCase`(`UserProfile.tsx`)를 사용하지만, 일반 파일과 폴더명은 OS 호환성을 위해 `kebab-case`(`user-profile`)를 사용하는 것이 모범 사례로 꼽힙니다. 커스텀 훅과 변수는 `camelCase`(`useAuth`)를 사용합니다. 이러한 규칙과 의존성 규칙은 수동이 아닌 ESLint 등 린팅 도구를 통해 자동화하여 거버넌스를 유지합니다.
+*   **클린 코드와 소프트웨어 엔지니어링 원칙 (SOLID 등)**
+    React 코드에 단일 책임 원칙(SRP)을 적용하여 300줄이 넘어가는 다기능 컴포넌트를 작게 쪼개는 것이 권장됩니다. 반복되는 로직은 DRY 원칙을 통해 커스텀 훅으로 추출하되, 과도한 추상화가 오히려 코드의 직관성을 해치지 않도록 KISS 원칙을 준수해야 합니다. 또한, YAGNI 원칙에 따라 미래를 대비한 불필요한 확장 기능 구현을 피하여 코드 복잡도를 낮춰야 합니다.
+
+## ⚖️ Trade-offs & Caveats
+*   **기능 기반 구조(FSD 등)의 도입 오버헤드**
+    FSD나 기능 중심의 디렉토리 구조는 모듈성 측면에서 강력하지만, 소규모 프로젝트에서는 과도한 설정(Overkill)과 불필요한 계층 분리를 초래할 수 있습니다. 어떤 모듈이 "기능(Feature)"인지 "위젯(Widget)"인지 구별하는 등 경계를 나누기 모호한 교차 관심사(Cross-cutting concerns) 처리에서 팀 내 논쟁과 의미론적 오버헤드가 발생할 수 있습니다. 팀 전체가 아키텍처 규칙을 완벽히 이해하지 못하면, 결국 규칙을 우회하기 위해 `/shared` 디렉토리에 모든 코드를 덤프해버리는 혼란이 발생할 위험이 있습니다.
+*   **추상화의 딜레마 (DRY vs KISS)**
+    코드의 중복을 없애기 위해(DRY) 무조건적으로 커스텀 훅이나 고차 컴포넌트(HOC)로 로직을 추출하다 보면, 오히려 로직을 추적하기 어려워지고 이해하기 복잡해져서 "간결함을 유지하라(KISS)"는 원칙을 위반하게 됩니다. 전문가들은 추상화를 서두르지 말고 동일한 패턴이 최소 3번 이상 반복될 때 추출하는 것을 권장합니다.
+*   **상태 관리 도구 도입에 따른 복잡성 증가**
+    0KB의 내장 도구인 Context API는 작고 정적인 상태(테마 등) 관리에 간편하지만, 렌더링 성능 최적화가 불가능하다는 한계가 있습니다. 이를 해결하기 위해 Zustand나 Redux 같은 상태 관리 라이브러리를 프로젝트 폴더(`store/`)에 도입하면 성능 문제는 해결할 수 있으나, 외부 라이브러리에 대한 의존성이 생기며 상태 슬라이스의 모듈화, 선택자(Selector) 작성 등에서 팀의 개발 규율(학습 곡선 및 보일러플레이트)이 부가적으로 요구됩니다.
+
+## 🔗 Knowledge Connections
+
+### Related Concepts
+
+#### [관계 유형: 아키텍처 방법론]
+- [[Feature-Sliced Design (FSD)]]
+  - 연결 이유: 확장 가능한 프론트엔드를 구축하기 위해 고안된 구체적이고 최신화된 디렉토리 아키텍처 패러다임이기 때문입니다.
+  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 레이어(Layers), 슬라이스(Slices), 세그먼트(Segments)의 구분, 단방향 의존성 강제, Public API 캡슐화를 통한 도메인 분리 전략.
+
+#### [관계 유형: 소프트웨어 설계 및 최적화 원칙]
+- [[SOLID 및 Clean Code 원칙]]
+  - 연결 이유: 컴포넌트를 설계하고 리팩토링할 때 폴더와 파일의 책임을 나누는 기반 지침이 됩니다.
+  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 단일 책임 원칙(SRP)을 통한 대형 컴포넌트의 분해, DRY/KISS 원칙을 통한 적절한 훅 추상화의 균형점.
+
+- [[자동 메모이제이션 (React Compiler)]]
+  - 연결 이유: 잘 설계된 아키텍처 내에서도 렌더링 폭포를 막는 것은 필수적인데, 이를 시스템적으로 최적화하는 2025년 주요 기술입니다.
+  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 수동 메모이제이션(`useMemo`, `useCallback`)의 한계 및 코드 복잡성 문제, 컴포넌트가 React 규칙(Rules of React)을 엄격히 준수해야 하는 이유.
+
+#### [관계 유형: 상태 및 데이터 관리 도구]
+- [[Zustand 및 Redux]]
+  - 연결 이유: 전역 상태 관리는 리액트 아키텍처에서 `/store` 또는 각 도메인 기능 내의 핵심 레이어를 구성하며, 시스템 결합도를 결정짓는 요소이기 때문입니다.
+  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: Context API의 전체 리렌더링 문제 해결 방식, 컴포넌트 외부에서 상태를 관리하여 아키텍처 성능을 유지하는 구체적 방법.
+
+### Deeper Research Questions
+
+- 단일 프론트엔드 모노레포에서 FSD(Feature-Sliced Design)를 도입할 때, 기능 간 '공유 관심사(Cross-cutting concerns)'를 명확히 분리하고 레이어 역참조를 막기 위해 ESLint 규칙을 어떻게 구체적으로 세팅해야 하는가?
+- 상태 관리 도구(Context API, Zustand, Redux)의 선택이 프로젝트의 실제 폴더 트리 구성(예: 단일 `/store` 폴더 사용 vs `/features/auth` 내 슬라이스로 분산 배치)에 어떠한 영향을 미치며, 대규모 앱에서의 모범 사례는 무엇인가?
+- 확장성이 큰 애플리케이션에서 라우트 레벨의 코드 스플리팅(Code Splitting)과 `React.lazy`를 적용할 때, Vite의 `manualChunks`를 활용해 서드파티 라이브러리(Vendor)를 분리하는 빌드 최적화 설정 방법론은 무엇인가?
+- 컴포넌트의 책임을 분리(SRP)하기 위해 거대한 로직을 Custom Hooks로 추출할 때, 과도한 추상화(DRY)와 코드의 직관성(KISS) 간의 트레이드오프를 평가할 수 있는 구체적 코드 지표는 무엇인가?
+- 애플리케이션의 안정성을 확보하기 위해 React Error Boundaries를 설계할 때, 앱 전체를 단일로 감싸는 방식과 각 기능별(위젯/라우트 등)로 쪼개어 감싸는 방식이 아키텍처 구조 설계에 어떻게 반영되어야 하는가?
+
+### Practical Application Contexts
+
+- **Implementation:** React 컴포넌트명은 `PascalCase`로 짓고, 폴더와 파일명은 호환성을 위해 `kebab-case`로 명명합니다. 기능 로직은 `features` 폴더 내에 배치하거나 `hooks` 폴더에 분리하여 반복을 줄이고 코드 응집력을 높이도록 구현합니다.
+- **System Design:** 코드를 파일 유형(컴포넌트, 훅 등)이 아닌 비즈니스 흐름과 도메인(Auth, Dashboard 등)에 맞추어 설계해야 합니다. 상위 컴포넌트 계층은 하위 인프라/도메인 계층에만 접근할 수 있도록 의존성 흐름을 설계에 반영합니다.
+- **Operation / Maintenance:** 기능 기반으로 분할된 폴더 구조는 특정 기능(예: 결제 프로세스)에 버그가 발생하거나 유지보수가 필요할 때, 해당 도메인 폴더 하나만 집중 분석하면 되므로 변경에 따른 부작용(Side Effect) 추적 및 디버깅 운영이 훨씬 수월해집니다.
+- **Learning Path:** 리액트를 처음 배울 때는 Flat 구조나 `components`, `hooks`를 나누는 파일 유형 기반으로 시작하지만, 이후 불필요한 리렌더링이나 복잡성 문제에 직면하면 FSD 아키텍처나 Zustand 같은 전역 상태의 역할 범위를 제한하는 고도화된 아키텍처 설계로 발전시켜 나가는 경로가 효과적입니다.
+- **My Project Relevance:** 소스에 관련 정보가 부족합니다. (질문자의 개인 프로젝트와 관련된 명시적 맥락이 소스 데이터에 포함되어 있지 않습니다.)
+
+### Adjacent Topics
+
+- [[마이크로 프론트엔드 (Micro-Frontends)]]
+  - 확장 방향: 단일 리액트 앱의 폴더 구조 분리를 넘어서, 대형 엔터프라이즈 환경에서 여러 팀이 독립적으로 개발하고 배포할 수 있도록 프론트엔드 자체를 물리적으로 분할 및 런타임에 통합하는 설계 방법론으로 확장.
+- [[서버 상태 관리 (Server State Management)]]
+  - 확장 방향: 클라이언트 로컬 상태와 구별하여, API 데이터를 비동기적으로 관리하고 캐싱 및 재검증을 처리하는 TanStack Query(React Query) 기반의 계층 설계 및 데이터 패칭 최적화로 지식 확장.
+
+---
+*Last updated: 2026-04-30*