# [[React Application Architecture]]

## 📌 Brief Summary
React 애플리케이션 아키텍처는 확장성, 유지보수성, 고성능을 보장하기 위해 프론트엔드 시스템의 코드를 체계적으로 구조화하는 프레임워크입니다 [1]. 기술적인 파일 유형 기반의 폴더 구조에서 벗어나 비즈니스 기능(Feature) 및 도메인 중심의 구조로 전환하는 것이 최근의 핵심 트렌드입니다 [2, 3]. 효과적인 아키텍처는 비즈니스 로직과 UI의 명확한 분리, 상태 소유권의 정의, 그리고 컴포넌트 간의 암묵적인 결합도 감소를 통해 대규모 시스템에서도 안전하고 지속 가능한 성장을 가능하게 합니다 [4, 5].

## 📖 Core 소스 Content

**1. 폴더 구조의 진화와 FSD (Feature-Sliced Design)**
*   **파일 유형 기반 구조 (File-Type Based Structure):** 과거에는 `components/`, `hooks/`, `services/` 등 기술적 역할에 따라 파일을 분류했으나, 이는 기능이 복잡해질수록 관련 로직이 흩어져 유지보수와 확장에 불리합니다 [2, 6, 7].
*   **기능 기반 구조 (Feature-Based Structure):** 인증(auth), 대시보드(dashboard) 등 비즈니스 기능이나 모듈을 중심으로 폴더를 구성하여 응집도를 높이고 모듈 독립성을 보장합니다 [3, 8].
*   **FSD (Feature-Sliced Design):** 프론트엔드에 특화된 현대적 아키텍처 방법론으로, 코드를 `app`, `pages`, `widgets`, `features`, `entities`, `shared`의 엄격한 계층 구조로 나눕니다 [9-11]. 하위 계층이 상위 계층에 의존하지 못하게 하는 '단방향 의존성' 원칙을 강제하며, 각 슬라이스는 `index.ts`를 통한 단일 진입점(Public API)만 노출하여 캡슐화와 안전한 리팩토링을 보장합니다 [9, 12, 13].

**2. Clean Code 및 확장성을 위한 설계 원칙**
*   **관심사 분리 (Separation of Concerns):** UI 렌더링을 담당하는 컴포넌트와 데이터 페칭 및 외부 통신을 담당하는 서비스 레이어를 분리하여 디버깅을 용이하게 해야 합니다 [14, 15].
*   **SOLID 원칙:** 단일 책임 원칙(SRP)에 따라 하나의 컴포넌트는 하나의 일만 해야 하며, 300줄이 넘어가는 컴포넌트는 너무 많은 역할을 하고 있다는 신호이므로 분리해야 합니다 [16]. 또한 상속 대신 컴포넌트 합성을 사용하고(OCP), 필요 없는 props 의존성을 제거(ISP)해야 합니다 [17, 18].
*   **DRY, KISS, YAGNI:** 중복 로직은 커스텀 훅이나 고차 컴포넌트로 분리하되(DRY), 너무 복잡한 추상화는 피하여 코드를 직관적으로 유지해야 하며(KISS), 현재 필요하지 않은 미래의 기능은 미리 구현하지 않아야 합니다(YAGNI) [19-21].

**3. 상태 관리 (State Management) 아키텍처**
*   현대의 상태 관리는 단일 스토어가 아닌 목적에 따른 세분화가 표준입니다 [22].
*   **서버 상태와 클라이언트 상태 분리:** API에서 가져오는 서버 데이터는 캐싱과 동기화를 지원하는 TanStack Query(React Query)로 관리하며, 네트워크 로직을 UI와 분리합니다 [23, 24]. 전역 애플리케이션 상태는 Context API의 불필요한 리렌더링 문제를 피하기 위해 Zustand와 같은 라이브러리를 사용하는 것이 권장됩니다 [22, 23, 25, 26]. 

**4. 거버넌스: 명명 규칙, 협업 및 리팩토링**
*   **명명 규칙 (Naming Conventions):** 파일 및 폴더 이름은 OS 호환성을 위해 `kebab-case`를, React 컴포넌트는 `PascalCase`를, 함수나 커스텀 훅 및 변수는 `camelCase`를 사용하는 것이 표준입니다 [27-30].
*   **자동화된 거버넌스:** ESLint를 통해 FSD 계층 간 잘못된 임포트를 차단하고, Husky로 커밋 전 포맷팅과 린팅을 강제하여 아키텍처 원칙을 팀 전체에 일관되게 적용합니다 [28].
*   **워크플로우 및 리팩토링:** 소규모 팀이라도 기능 브랜치 워크플로우를 통해 메인 브랜치의 안정성을 유지하며, 커스텀 훅을 리팩토링의 기본 단위로 삼아 비즈니스 로직을 UI로부터 안전하게 격리합니다 [31-34]. 

## 🔗 Knowledge Connections
- **Related Topics:** [[Feature-Sliced Design]], [[State Management Architecture]], [[Clean Code Principles]], [[Folder Structure Best Practices]]
- **Projects/Contexts:** [[Large-scale React Applications]], [[Frontend System Engineering]]
- **Contradictions/Notes:** 
  - 폴더 구조에 관한 시각 차이: 평면 구조나 파일 유형별 구조(components, hooks 등)는 초보자나 소규모 프로젝트에는 시작하기 쉬운 장점이 있지만, 프로젝트가 커짐에 따라 확장성이 크게 떨어지므로 궁극적으로는 기능 단위(Feature-based)나 FSD 아키텍처로 넘어가야 한다고 강조합니다 [6-8, 35, 36].
  - DRY와 KISS 원칙 간의 균형: 소스는 중복을 줄이는 DRY 원칙을 강조하면서도, 코드를 과도하게 추상화하면 직관성과 단순성을 해치는 KISS 원칙 위반을 초래할 수 있으므로 최소 3번 이상 패턴이 반복될 때만 추상화를 적용하도록 권장합니다 [19].

---
*Last updated: 2026-04-26*