---
id: s1c2a3l4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
category: Dev
confidence_score: 0.99
tags: [react, architecture, scalability, large-scale, fsd, folder-structure]
last_reinforced: 2026-05-01
github_commit: "wikification-scalable-architecture"
---

# Scalable Frontend Architecture & System Design

## 📌 한 줄 통찰 (The Karpathy Summary)
> 대규모 프론트엔드 시스템의 확장은 단순히 코드 양을 늘리는 것이 아니라, Feature-Sliced Design(FSD)과 같은 계층적 관심사 분리를 통해 모듈 간 결합도를 제어하고 단방향 의존성을 강제함으로써 예측 가능한 유지보수성을 확보하는 것이다.

## 📖 구조화된 지식 (Synthesized Content)

### 1. 계층적 관심사 분리 (FSD 도입)
- **Layered Architecture**: `app` (설정), `pages` (라우트), `widgets` (조합), `features` (비즈니스 가치), `entities` (데이터 모델), `shared` (공통 유틸)로 계층을 나눈다.
- **단방향 의존성**: 상위 계층은 하위 계층만 참조할 수 있도록 제한하여 순환 참조를 차단한다.
- **Public API**: 각 슬라이스는 `index.ts`를 통해서만 내부 로직을 노출하여 캡슐화를 실현한다.

### 2. 폴더 구조 및 모듈화
- **기능 중심 분리 (Feature-based)**: 기술적 유형(components, hooks)이 아닌 도메인과 기능 단위로 폴더를 구성하여 응집도를 높인다.
- **마이크로 프론트엔드 대비**: 시스템이 극도로 비대해질 경우 모노레포(Nx, Turborepo)를 활용하여 모듈별 독립 배포 및 빌드를 준비한다.

### 3. 기술 부채 및 확장성 관리
- **추상화 게이트**: 성급한 공통화(Over-generalization)를 경계하고, 도메인 로직이 유출되지 않도록 경계를 엄격히 관리한다.
- **거버넌스 자동화**: ESLint 규칙(예: `eslint-plugin-import`)을 통해 계층 위반을 빌드 타임에 감지한다.

## ⚠️ 모순 및 업데이트 (Contradictions & RL Update)
- **오버엔지니어링**: 소규모 프로젝트에서는 FSD가 불필요한 보일러플레이트와 인지 부하를 발생시킨다. 프로젝트 성숙도에 따른 단계적 도입이 필요하다.
- **Shared 계층의 비대화**: 모든 것을 `shared`에 넣으려는 유혹을 뿌리쳐야 한다. 최대한 하위 엔티티나 기능으로 분산시켜야 한다.

## 🔗 지식 연결 (Graph)
- **Parent**: 10_Wiki/Topics/Development
- **Related**: Legacy React Migration & Refactoring Standard, [[Feature-Sliced Design|Feature-Sliced Design]]
- **Raw Source**: 00_Raw/Scalable React Apps, 00_Raw/Frontend Scalable Architecture, 00_Raw/Large-scale React Applications, 00_Raw/대규모 React 애플리케이션 아키텍처 구성, 00_Raw/확장 가능한 React 아키텍처 및 폴\353\215\224 \352\265\254\354\241\260 \354\204\244\352\263\204

## 💻 GitHub 동기화 자동화 워크플로우
1. Stage: git add .
2. Commit: `git commit -m "[P-Reinforce] Wikify Scalable Frontend Architecture and System Design"`
3. Push: `git push origin main`