# [[Scalable React Architecture]]

## 📌 Brief Summary
확장 가능한 리액트 아키텍처(Scalable React Architecture)는 애플리케이션의 복잡성 증가, 팀의 확장, 장기적인 유지보수 요구를 원활하게 수용할 수 있도록 프론트엔드 시스템을 설계하는 방법론입니다 [1-4]. 단순한 파일 유형별 폴더 구성을 넘어 기능(Feature) 또는 도메인 기반의 구조인 기능 분할 설계(Feature-Sliced Design)를 채택하는 방향으로 진화해 왔습니다 [5, 6]. 이 아키텍처는 명시적인 경계 설정, 결합도 감소, 일관된 명명 규칙 적용 및 적절한 상태 관리를 통해 높은 성능과 개발 속도를 유지하는 것을 목표로 합니다 [3, 6-12].

## 📖 Core Content

*   **아키텍처의 필요성과 실패 요인:** 리액트 앱이 커질수록 비즈니스 로직이 UI 컴포넌트로 새어나가거나, 상태 소유권이 불분명해지고, 기능 간 암묵적인 의존성이 생기는 문제가 흔히 발생합니다 [2, 13]. 확장 가능한 아키텍처는 결합도(Coupling)를 낮추고 응집도(Cohesion)를 높이며, 모듈과 퍼블릭 API의 명확한 경계를 설정하여 인지 부하를 줄이고 안전한 성장을 가능하게 합니다 [3].
*   **폴더 구조의 진화 (유형 기반에서 기능 기반으로):** 컴포넌트, 훅, 서비스를 각각의 폴더로 모아두는 전통적인 파일 유형 기반 구조는 단일 기능을 수정할 때 여러 폴더를 오가야 하므로 대규모 확장에 불리합니다 [7, 14-16]. 2025년 기준의 모던 리액트 프로젝트는 연관된 컴포넌트, 훅, 로직, 타입을 하나의 도메인/기능 폴더 내에 배치하는 기능 기반(Feature-Based) 구조를 권장합니다 [6, 16, 17].
*   **기능 분할 설계 (Feature-Sliced Design, FSD):** FSD는 프론트엔드 애플리케이션을 위해 설계된 아키텍처 방법론으로, 코드를 기술적 유형이 아닌 범위(Scope)와 책임(Responsibility)에 따라 구성합니다 [5, 18, 19]. 앱(app) -> 페이지(pages) -> 위젯(widgets) -> 기능(features) -> 엔티티(entities) -> 공유(shared)로 이어지는 계층 모델을 가지며, 상위 계층이 하위 계층에만 의존할 수 있는 단방향 의존성 규칙을 엄격히 적용합니다 [8, 9, 18]. 또한 각 슬라이스는 단일 진입점(`index.ts`)만을 노출하는 '퍼블릭 API 규칙'을 통해 내부 구현을 캡슐화합니다 [20-22].
*   **클린 코드 및 SOLID 원칙 적용:** 리액트 컴포넌트의 유지보수성을 높이려면 SOLID, DRY, KISS, YAGNI와 같은 소프트웨어 공학 원칙이 필요합니다 [21, 23-26]. 예를 들어 단일 책임 원칙(SRP)에 따라 컴포넌트가 300줄을 넘어가면 여러 개의 작은 컴포넌트로 분리해야 하며, 반복되는 로직은 커스텀 훅으로 추출(DRY)하여 단순하게 유지(KISS)해야 합니다 [23, 25, 27, 28].
*   **상태 관리와 성능 최적화:** 확장 가능한 아키텍처에서는 상태를 지역 상태, 전역 애플리케이션 상태, 서버 캐시 상태 등으로 엄격히 구분합니다 [29, 30]. 자주 변경되는 상태를 기본 Context API로 관리하면 불필요한 리렌더링 폭풍(Re-render storm)이 발생할 수 있으므로, 상태 슬라이스를 선택(Selector)할 수 있는 Zustand나 대규모 팀에 적합한 Redux 같은 전문 도구를 사용하는 것이 성능에 유리합니다 [31-34]. 더불어 Vite의 `manualChunks`나 `React.lazy`를 이용한 코드 스플리팅을 통해 초기 번들 크기를 줄이는 것도 핵심 전략입니다 [35-38].
*   **명명 규칙 및 거버넌스(Governance):** 확장되는 팀 내 혼란을 막기 위해 엄격한 폴더 및 파일 명명 규칙이 적용됩니다. 리액트 컴포넌트는 PascalCase, 일반 파일/폴더는 OS 호환성을 위해 kebab-case, 훅과 유틸리티 함수는 camelCase를 사용합니다 [39-44]. 또한 ESLint, Prettier, Husky 같은 도구를 통해 아키텍처 규칙과 포맷팅을 CI/CD 파이프라인에서 자동 강제(Governance)합니다 [45, 46].

## 🔗 Knowledge Connections
- **Related Topics:** [[Feature-Sliced Design]], [[Clean Code and SOLID Principles]], [[Frontend Folder Structure]], [[React State Management]], [[Frontend Performance Optimization]]
- **Projects/Contexts:** [[Bulletproof React]] (생산 환경에 적합한 단순하고 확장 가능한 리액트 아키텍처 베스트 프랙티스를 모아둔 오픈소스 레퍼런스 [10])
- **Contradictions/Notes:** 
  - 기능 기반 구조(Feature-Based Structure)가 확장성 측면에서 매우 권장되지만, 매우 작은 소규모 프로젝트나 초보자에게는 오버엔지니어링(Overkill)일 수 있으며 초기에는 플랫(Flat) 구조가 적합할 수 있습니다 [15, 47].
  - Context API는 추가 의존성 없이 상태를 공유할 수 있어 유용하지만, 자주 변경되는 데이터에 사용할 경우 성능이 심각하게 저하되므로 Zustand나 Redux로 대체해야 한다는 명확한 제약 사항이 여러 소스에서 강조됩니다 [31, 33, 34, 48].

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