# [[React Frontend Architecture|React Frontend Architecture]]

## 📌 Brief Summary
React 프론트엔드 아키텍처는 확장 가능하고 유지보수하기 쉬운 애플리케이션을 구축하기 위한 구조적 뼈대이자 조직화 방법론이다 [1, 2]. 기존의 기술적 파일 단위 분리에서 벗어나, 비즈니스 도메인과 기능(Feature-Based)을 중심으로 코드를 구성하여 결합도를 낮추고 응집도를 높이는 것을 목표로 한다 [3-5]. 이를 통해 무분별한 비즈니스 로직의 UI 누수를 막고 명확한 상태 소유권을 확립하며, 팀과 코드베이스가 성장함에 따라 시스템이 예측 가능하게 확장할 수 있도록 돕는다 [6-8].

## 📖 Core Content

*   **폴더 구조와 모듈화의 진화**: 과거에는 컴포넌트, 훅, 스타일 등을 파일 유형별로 그룹화했으나, 프로젝트가 커질수록 논리적 기능이 파편화되어 탐색과 확장이 어려웠다 [4, 9]. 2025년 기준 프론트엔드 업계 표준은 비즈니스 기능을 중심으로 코드를 묶는 '기능 기반(Feature-Based)' 구조로 전환되었다 [5, 10]. 특정 기능과 관련된 컴포넌트, 훅, API 로직 등을 단일 디렉토리에 캡슐화함으로써 모듈의 독립성과 확장성을 크게 향상시킨다 [11, 12].
*   **기능 분할 설계 (Feature-Sliced Design, FSD)**: FSD는 도메인 주도 설계(DDD)와 모듈형 아키텍처를 결합한 프론트엔드 전용 방법론이다 [3, 13]. 애플리케이션을 `app`, `pages`, `widgets`, `features`, `entities`, `shared`의 계층(Layer)으로 나누고, 상위 계층은 하위 계층에만 의존할 수 있다는 엄격한 '단방향 의존성' 규칙을 강제한다 [11, 14, 15]. 각 슬라이스는 `index.ts` 형태의 'Public API'를 통해서만 외부에 기능과 컴포넌트를 노출하여 내부 구현을 안전하게 캡슐화한다 [16-18].
*   **상태 관리 아키텍처의 세분화**: 단일 모놀리식 스토어(예: 대규모 Redux)에 의존하던 방식에서 벗어나, 데이터의 성격에 따라 최적의 도구를 선택하도록 상태 관리가 파편화되었다 [19, 20]. 서버에서 가져오는 데이터인 '서버 상태'는 TanStack Query(React Query)를 이용해 캐싱 및 네트워크 로직을 격리하고, 테마나 설정 등 정적인 '전역 상태'는 Context API로, 장바구니나 실시간 데이터처럼 빈번하게 변하는 상태는 Zustand나 Jotai 등 선택적 렌더링을 지원하는 도구로 관리한다 [20-24].
*   **소프트웨어 공학 원칙의 적용 (SOLID & Clean Code)**: React의 함수형 컴포넌트 개발에도 단일 책임 원칙(SRP)을 적용하여, 컴포넌트가 커지면 상태 관리, 데이터 페칭, 렌더링 등 각기 다른 책임을 가진 작은 컴포넌트로 분리해야 한다 [25, 26]. 중복을 피하는 DRY 원칙을 통해 공통 로직을 커스텀 훅으로 추출하면서도, 코드를 단순하게 유지하는 KISS 원칙과 미래를 위한 과도한 최적화를 피하는 YAGNI 원칙 간의 균형을 맞추는 것이 핵심이다 [27, 28].
*   **명명 규칙과 거버넌스 도구**: 폴더와 파일 시스템은 OS 환경에 따른 오류를 방지하기 위해 `kebab-case`를, React 컴포넌트는 `PascalCase`를, 변수와 함수는 `camelCase`를 사용하는 것이 보편적인 컨벤션이다 [29-33]. 이러한 규칙과 아키텍처 의존성 경계는 ESLint나 Prettier, Husky와 같은 도구를 활용해 빌드 타임 및 커밋 단계에서 자동으로 강제(Linting)된다 [30, 34].

## ⚖️ Trade-offs & Caveats

*   **FSD 및 기능 기반 모듈화의 복잡성 오버헤드**: Feature-Sliced Design은 구조적 안정성을 제공하지만 "무엇이 하나의 기능(Feature)인가?"를 정의하는 경계를 설정하기 매우 까다롭다는 근본적 어려움이 있다 [35]. 인증(Auth)과 같은 교차 관심사(Cross-cutting concern)는 여러 기능에 걸쳐 있어 적절한 계층을 찾기 모호하며 [35, 36], 엄격한 분할 규칙을 소규모 프로젝트에 도입하면 오히려 불필요한 폴더 구조와 오버엔지니어링으로 인한 개발 속도 저하를 초래할 수 있다 [12, 37]. 또한, 규칙을 제대로 숙지하지 않으면 모든 코드를 'Shared' 계층에 쏟아부어 최악의 파급 효과를 낳는 스파게티 코드가 될 위험이 존재한다 [38, 39].
*   **추상화(DRY)와 단순함(KISS)의 상충**: DRY 원칙에 집착하여 코드 중복을 무조건 피하려고 하면, 수많은 예외 처리와 분기를 포함하는 거대하고 복잡한 커스텀 훅이나 컴포넌트가 탄생하게 된다 [27]. 이러한 과도한 추상화는 단순한 코드 반복보다 가독성과 유지보수성을 떨어뜨려 KISS 원칙을 위반하는 반대 급부를 낳으므로, 명확한 패턴이 3번 이상 반복될 때까지는 추상화를 미루는 것이 권장된다 [27, 40, 41].
*   **상태 관리 도구 선택에 따른 부작용**: React 내장 Context API는 외부 의존성 없이 상태를 주입할 수 있지만, 상태값의 일부만 변경되어도 해당 컨텍스트를 구독하는 모든 하위 컴포넌트가 강제로 리렌더링된다는 치명적인 성능 제약이 있다 [42, 43]. 반대로 Redux는 명확한 구조와 강력한 디버깅 툴을 제공하지만, 보일러플레이트 코드의 폭발적 증가를 동반하여 소규모 팀이나 간단한 애플리케이션에서는 과도한 기술 부채로 작용할 수 있다 [44, 45].
*   **성능 최적화 기법의 숨은 비용**: `React.memo`, `useMemo`, `useCallback`은 불필요한 리렌더링을 막아주지만 그 자체가 공짜는 아니다 [46]. 이전 Props나 의존성 배열을 메모리에 저장하고 변경 여부를 얕은 비교(Shallow compare)하는 연산 비용이 추가된다 [46]. 만약 렌더링 비용이 매우 싼 컴포넌트에 사용하거나 불안정한 참조값(인라인 함수, 객체)을 지속적으로 전달하여 리렌더링 차단에 실패한다면, 최적화 코드 자체가 오히려 애플리케이션을 더 느리게 만드는 부작용이 발생한다 [46, 47].

## 🔗 Knowledge Connections

### Related Concepts

#### [아키텍처 및 디자인 패턴]
- [[Feature-Sliced Design|Feature-Sliced Design]]
  - 연결 이유: 현대 React 애플리케이션의 모듈화 및 계층화를 위해 고안된 가장 대표적이고 구체적인 프론트엔드 아키텍처 방법론이기 때문 [3, 13].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 도메인 기반 분할, 단방향 의존성 규칙 적용 방법, 그리고 Public API를 통한 컴포넌트의 캡슐화 원리 [14, 16, 17].
- [[SOLID Principles|SOLID Principles]]
  - 연결 이유: 확장 가능한 프론트엔드 구조를 짜기 위해 클래스 기반 OOP를 넘어 React의 함수형 컴포넌트에도 적용해야 하는 근본적인 소프트웨어 설계 원칙이기 때문 [17, 48].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 단일 책임 원칙(SRP)을 이용한 비대해진 컴포넌트의 리팩토링 방식 및 개방-폐쇄 원칙(OCP)을 활용한 UI 컴포넌트 합성(Composition) 전략 [25, 49].

#### [상태 관리 및 최적화 전략]
- [[상태 관리(State Management)|State Management]]
  - 연결 이유: 아키텍처 내에서 데이터(서버 데이터, 로컬 상태, 전역 UI 상태)의 성격에 따라 책임과 저장소를 어떻게 나눌지 결정하는 핵심 분야이기 때문 [20, 50].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: Context API의 렌더링 한계를 돌파하기 위한 Zustand/Jotai의 Selector 패턴 작동 원리 및 TanStack Query를 활용한 서버 상태 격리 기법 [21, 43, 51].
- [[Performance Optimization|Performance Optimization]]
  - 연결 이유: 대규모 아키텍처가 실제로 사용자 브라우저에서 효율적으로 동작하기 위해 필수적으로 수반되어야 하는 성능 지표(Web Vitals) 관리 방법이기 때문 [52, 53].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 지연 로딩(Lazy Loading) 및 코드 스플리팅을 통한 초기 번들 사이즈 최적화, 그리고 동시성 렌더링(Concurrent Rendering) 훅의 활용법 [54-56].

### Deeper Research Questions
- Feature-Sliced Design(FSD)에서 인증(Auth)이나 분석(Analytics) 같은 도메인 간의 교차 관심사(Cross-cutting concerns)가 발생할 때, 결합도를 높이지 않고 주입/공유하는 가장 이상적인 방법은 무엇인가?
- React Compiler가 프로젝트에 성공적으로 도입되어 수동 메모이제이션 로직(`useMemo`, `useCallback`)이 대거 삭제될 때, 프론트엔드 폴더 구조와 코드 응집도에 어떤 형태의 구조적 변화가 일어날 수 있는가?
- 서버 상태(Server State) 관리 라이브러리와 클라이언트 글로벌 상태(Client State) 도구를 완벽히 분리한 아키텍처에서, 두 상태가 불가피하게 동기화되거나 상호작용해야 하는 엣지 케이스를 깨끗하게 처리하는 패턴은 무엇인가?
- 대규모 엔터프라이즈 환경에서 Micro-Frontends 아키텍처와 Feature-Sliced Design은 어떻게 호환되며, 각 독립 서비스 간의 중복 코드(Shared 레이어) 문제를 어떻게 통제할 수 있는가?
- 복잡도 높은 순수 함수형 React 컴포넌트에 의존성 역전 원칙(DIP)을 적용할 때, 컨텍스트(Context API)나 프롭 드릴링(Prop Drilling)을 피하면서 활용할 수 있는 현대적인 제어 역전(IoC) 구현 패턴은 무엇이 있는가?

### Practical Application Contexts

- **Implementation:** 기술적 파일 유형(컴포넌트, 훅) 중심의 디렉토리 구조에서 벗어나, `src/features/` 내에 특정 비즈니스 로직(예: 장바구니, 유저 프로필)에 연관된 UI, API 통신, 로컬 훅을 캡슐화하여 구현한다 [5, 11, 57]. 
- **System Design:** 모놀리식 글로벌 스토어 설계 지양. API 캐싱 및 서버 데이터는 TanStack Query를 사용해 비즈니스 로직 경계로 분리하고, 다크 모드 같은 앱 설정은 Context API로, 실시간 UI 상태 변경은 Zustand 등으로 쪼개어 시스템 데이터 흐름을 최적화한다 [20, 21, 24].
- **Operation / Maintenance:** 런타임 크래시에 대비하기 위해 Error Boundary 컴포넌트를 앱의 최상단뿐 아니라 불안정한 서드파티 위젯이나 개별 라우트 단위에 감싸, 특정 모듈의 에러가 앱 전체의 "화이트 스크린" 장애로 번지는 것을 차단한다 [58-60].
- **Learning Path:** React 기초 문법 및 렌더링 원리 파악 -> 컴포넌트 재사용과 SRP 원칙(SOLID) 학습 -> 기능 기반 폴더 구조 및 FSD 적용 방식 이해 -> 번들 최적화 및 렌더링 리팩토링 스킬 향상의 흐름으로 역량을 발전시킨다 [6, 17, 25].
- **My Project Relevance:** 기존 코드베이스의 `components/` 폴더에 수십 개의 컴포넌트가 방치되어 있거나, `useCallback` 등이 과도하게 사용된 경우, 이를 비즈니스 도메인 단위의 폴더로 재배치하고 프로파일러(Profiler)를 통해 실제 병목 지점을 측정한 뒤 최적화를 진행하는 아키텍처 리팩토링에 직결된다 [12, 61, 62].

### Adjacent Topics

- [[마이크로 프론트엔드 (Micro Frontends)|Micro-Frontends]]
  - 확장 방향: 단일 React SPA 아키텍처의 한계를 넘어, 독립적으로 배포 및 관리 가능한 여러 프론트엔드 팀과 서비스를 하나로 조율하는 엔터프라이즈급 인프라 확장 관점으로 연결 [3, 63].
- Observability and Monitoring
  - 확장 방향: 설계한 아키텍처가 실제 프로덕션 환경에서 어떻게 동작하고 어디서 병목을 일으키는지 측정하기 위한 구조적 로깅, 성능 프로파일링(Web Vitals), 그리고 Sentry를 활용한 세션 모니터링 기법으로 확장 [64-66].

--- 
*Last updated: 2026-04-30*