2nd/00_Raw/Frontend System Architecture.md

Frontend System Architecture

📌 Brief Summary

프론트엔드 시스템 아키텍처는 애플리케이션의 복잡성이 증가함에 따라 확장성, 유지보수성 및 고성능을 보장하기 위해 설계되는 구조적 프레임워크입니다 [1]. 이는 단순한 UI 렌더링을 넘어 모듈식 폴더 구조, 클린 코드 방법론, 효율적인 상태 관리 전략, 빌드 및 런타임 최적화를 포괄합니다 [1]. 현대의 React 환경에서는 비즈니스 로직이 UI 컴포넌트로 누수되는 것을 방지하고 명확한 의존성 경계를 설정하여 시스템이 안전하게 확장되도록 하는 것이 핵심입니다 [2, 3].

📖 Core Content

• 아키텍처 패러다임 및 폴더 구조 (Folder Structure):
  • 과거의 파일 유형별(기술적 역할별) 폴더 구조는 규모가 커질수록 유지보수가 어려워, 비즈니스 기능(Feature)이나 도메인을 중심으로 코드를 구성하는 구조가 표준으로 자리 잡았습니다 [4, 5].
  • Feature-Sliced Design (FSD): 프론트엔드에 특화된 아키텍처로, 프로젝트를 app, pages, widgets, features, entities, shared라는 명확한 계층(Layer)으로 나눕니다 [6, 7]. 상위 계층은 하위 계층에만 의존할 수 있다는 엄격한 '단방향 의존성' 규칙을 적용하며, 각 모듈은 index.ts를 통한 단일 퍼블릭 API(Public API)만을 노출하여 캡슐화를 강제합니다 [6, 8, 9].
• 클린 코드 및 소프트웨어 엔지니어링 원칙 (Clean Code Principles):
  • SOLID: 단일 책임 원칙(SRP)에 따라 300줄 이상의 방대한 컴포넌트는 더 작고 명확한 책임을 가진 컴포넌트로 분리해야 하며, 개방-폐쇄 원칙(OCP)을 위해 컴포넌트 합성(children 활용)을 사용하고, 인터페이스 분리 원칙(ISP)을 통해 컴포넌트가 꼭 필요한 Props만 전달받도록 설계해야 합니다 [10-12].
  • DRY, KISS, YAGNI: 커스텀 훅을 통해 코드 반복을 줄이되(DRY), 불필요하고 복잡한 추상화를 피하여 코드를 단순하게 유지하고(KISS), 당장 필요하지 않은 기능은 미리 구현하지 않는(YAGNI) 실용적인 접근이 필요합니다 [13-15].
• 네이밍 규칙 및 거버넌스 (Naming Conventions):
  • 운영체제 간의 호환성을 위해 파일 및 폴더 이름은 kebab-case를 사용합니다 [16-18]. 반면 React 컴포넌트는 HTML 요소와 구분하기 위해 PascalCase를, 변수 및 훅(Hooks)은 camelCase, 상수는 UPPER_SNAKE_CASE를 사용합니다 [19-21].
  • 이러한 규칙은 ESLint, Prettier, Husky와 같은 도구를 통해 자동화 및 검증되어야 합니다 [19].
• 상태 관리 아키텍처 (State Management):
  • 현대의 상태 관리는 로컬 컴포넌트 상태, 전역 애플리케이션 상태, 서버 캐시 상태, URL 상태로 역할을 세분화합니다 [22].
  • 자주 변경되지 않는 설정값(테마 등)은 Context API로 충분하지만, 빈번하게 변경되는 전역 상태는 불필요한 전체 리렌더링을 방지하는 선택자(Selector) 패턴 기반의 Zustand가 유리하며, 복잡한 비동기 작업과 대규모 팀 협업에는 Redux가 권장됩니다 [23-28]. 서버 상태 처리를 위해서는 TanStack Query(React Query)를 사용하여 네트워크 로직을 UI와 분리합니다 [26, 29].
• 성능 최적화 (Performance Optimization):
  • Vite를 활용한 빌드 환경에서는 manualChunks를 통해 무거운 벤더 라이브러리를 분리하고, React.lazy와 Suspense를 결합하여 라우트 기반 코드 스플리팅을 적용함으로써 초기 로딩 속도를 크게 향상시킬 수 있습니다 [30-33].
  • 2025년 기준 React Compiler가 안정화되어 빌드 타임에 자동으로 메모이제이션을 수행하므로 수동적인 useMemo, useCallback의 남용을 줄일 수 있습니다 [30, 34, 35].
• 디버깅 및 회복성 (Debugging & Resilience):
  • 애플리케이션 충돌 시 백지 화면이 나오는 것을 막기 위해 React Error Boundaries를 대시보드나 서드파티 위젯 같은 불안정한 섹션에 개별적으로 적용하여 대체 UI를 제공해야 합니다 [36-38].
  • Chrome DevTools의 Heap Snapshots과 Allocation Timelines를 통해 메모리 누수(예: 분리된 DOM 노드, 해제되지 않은 이벤트 리스너)를 탐지하고 관리합니다 [39-41].
• Git 워크플로우 (Git Workflow):
  • 소규모 팀의 경우, 무거운 Git Flow 대신 '수명이 짧은 기능 브랜치(Feature-branch)' 또는 '트렁크 기반(Trunk-based)' 워크플로우를 채택하는 것이 효율적입니다 [42-44].
  • 추적성을 높이기 위해 브랜치와 커밋 메시지에 티켓 ID를 포함하며, feat:, fix:와 같은 Conventional Commits 규칙을 따릅니다 [45-48]. PR(Pull Request)을 통한 코드 리뷰 및 CI 테스트는 main 병합 전 필수입니다 [45, 49].

🔗 Knowledge Connections

• Related Topics: [[Feature-Sliced Design]], [[SOLID Principles in React]], [[State Management]], [[React Performance Optimization]], [[Git Workflow]], [[Error Boundaries]]
• Projects/Contexts: [[Modern React Application Development (2025)]], [[Vite Build Tool]]
• Contradictions/Notes:
  • 상태 관리 접근에 있어, 소스들은 Context API가 사용하기 간편하지만 잦은 업데이트가 발생하는 전역 상태의 경우 '전체 구독 컴포넌트 리렌더링'이라는 치명적인 성능 병목을 일으킨다고 지적하며, 이를 해결하기 위해 Zustand나 Redux의 도입을 주장합니다 [24, 26, 50-52].
  • 성능 최적화와 관련해, React Compiler의 도입으로 React.memo나 useMemo 같은 수동 메모이제이션의 필요성이 크게 줄어들었으나, 서드파티 라이브러리의 호환성 문제(매 렌더마다 새로운 참조를 반환하는 훅 등)나 규칙을 따르지 않은 레거시 코드에서는 여전히 수동 메모이제이션이 필요할 수 있다고 설명합니다 [35, 53, 54].

---

Last updated: 2026-04-26