2nd/00_Raw/React Application Architecture.md

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