2nd/10_Wiki/Topics/Frontend/대규모 프론트엔드 아키텍처(Scalable Frontend Architecture).md

---
id: wiki-2026-0508-대규모-프론트엔드-아키텍처-scalable-frontend
title: 대규모 프론트엔드 아키텍처(Scalable Frontend Architecture)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Scalable Frontend, Monorepo, Micro-Frontend, Module Federation]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [frontend, architecture, monorepo, micro-frontend, scalability]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: turborepo
---

# 대규모 프론트엔드 아키텍처(Scalable Frontend Architecture)

## 매 한 줄
> **"매 코드가 아닌 사람의 scaling 문제"**. 100+ engineer / 10+ team 이 한 codebase 를 깨지 않고 동시에 ship 하려면 boundary 가 필요. 2026 답: monorepo (Turborepo/Nx) + design system + module federation 또는 vertical slice + RFC process.

## 매 핵심

### 매 무엇이 scaling 을 막는가
- **Build time**: cold build 30분 → 매 PR review cycle 죽음.
- **Coupling**: import graph 가 mesh → 한 파일 바꾸면 매 rebuild.
- **Ownership 모호**: bug fix 가 누구 책임 인지 모름.
- **Inconsistent UX**: team 마다 다른 button / spacing.
- **Dependency drift**: 매 package version 제각각.

### 매 architecture 패턴
- **Monorepo**: 모든 app/lib 을 한 repo — atomic refactor 쉬움. Turborepo, Nx, Bazel.
- **Polyrepo**: 매 team 별 repo — 독립 deploy. 매 versioning 부담.
- **Micro-frontend**: runtime composition — 매 다른 stack/team 통합. Module Federation, single-spa.
- **Vertical slice**: feature 별 폴더 (UI + state + api 함께) — feature team ownership.
- **Design system**: 매 cross-team UI consistency.

### 매 응용
1. Big tech (Meta, Google) — monorepo + RFC.
2. Enterprise — micro-frontend (legacy + new 통합).
3. Startup scaling — vertical slice → eventual monorepo.

## 💻 패턴

### Turborepo monorepo
```json
// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] },
    "test": { "dependsOn": ["^build"], "outputs": [] },
    "lint": {},
    "dev": { "cache": false, "persistent": true }
  }
}
```
```
apps/
  web/        # 매 main app
  admin/      # 매 admin dashboard
packages/
  ui/         # 매 design system
  config/     # 매 eslint, tsconfig
  api-client/ # 매 typed API client
```

### Module Federation (runtime micro-frontend)
```ts
// host vite.config.ts
import { federation } from '@module-federation/vite';

export default {
  plugins: [
    federation({
      name: 'host',
      remotes: {
        checkout: 'https://checkout.example.com/remoteEntry.js',
      },
      shared: ['react', 'react-dom'],
    }),
  ],
};

// usage
const Checkout = lazy(() => import('checkout/App'));
```

### Vertical slice structure
```
src/features/
  auth/
    components/
    hooks/
    api/
    store.ts
    routes.ts
  cart/
    ...
src/shared/
  ui/
  utils/
```

### Design system package
```tsx
// packages/ui/src/Button.tsx
export const Button = ({ variant = 'primary', ...props }: ButtonProps) => (
  <button className={cn('btn', `btn-${variant}`)} {...props} />
);

// apps/web/package.json
{ "dependencies": { "@acme/ui": "workspace:*" } }
```

### CODEOWNERS for clear ownership
```
# .github/CODEOWNERS
/apps/web/features/checkout/  @team-checkout
/apps/web/features/cart/      @team-checkout
/packages/ui/                 @team-design-system
/packages/api-client/         @team-platform
```

### Type-safe API contract (tRPC / OpenAPI)
```ts
// packages/api-contract/src/index.ts
export const apiSpec = {
  '/products/:id': { method: 'GET', response: ProductSchema },
} as const;

// generated client used by all apps — 매 single source of truth.
```

### Boundary lint rule (eslint-plugin-boundaries)
```js
// .eslintrc
{
  "plugins": ["boundaries"],
  "rules": {
    "boundaries/element-types": ["error", {
      "default": "disallow",
      "rules": [
        { "from": "feature", "allow": ["shared"] },
        { "from": "shared", "allow": ["shared"] },
      ]
    }]
  }
}
```

### Changeset for versioning (publish workflow)
```bash
pnpm changeset       # 매 feature PR 마다 작성
pnpm changeset version  # 매 release 시 version bump
pnpm publish -r
```

### Remote cache (Turborepo / Nx Cloud)
```bash
turbo build --remote-cache=https://...
# 매 CI build 시 다른 사람의 cache hit → 30min → 30sec.
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| 1-3 dev | single repo, single app. |
| 5-20 dev | monorepo + design system. |
| 50+ dev, single product | monorepo + vertical slice + RFC. |
| Multi-product, independent deploy | polyrepo or module federation. |
| Legacy + modern 통합 | micro-frontend (single-spa, MF). |
| Multi-team, shared UX | design system + Storybook. |

**기본값**: Turborepo + pnpm + Tailwind v4 design system + ESLint boundaries + Changesets.

## 🔗 Graph
- 부모: [[Frontend Architecture]] · [[Software Architecture]]
- 변형: [[Monorepo]] · [[Micro-Frontend]] · [[Module Federation]]
- 응용: [[Turborepo]] · [[Nx]] · [[Storybook]]
- Adjacent: [[Design System]] · [[Vertical Slice]] · [[Changeset]]

## 🤖 LLM 활용
**언제**: 5+ 팀, 100k+ LoC, build > 5min, ownership conflict.
**언제 X**: 매 single dev, MVP, < 10 page app.

## ❌ 안티패턴
- **Premature micro-frontend**: 5명 팀이 module federation → 매 overhead 만.
- **Monorepo without cache**: 매 CI 6시간 — Turborepo / Nx remote cache 필수.
- **Shared mega-package**: `@acme/utils` 매 천 함수 — split + tree-shake.
- **No design system**: button 변형 매 50개 — design tokens.
- **Cyclic deps between apps**: app A → app B → app A. boundary lint 로 막음.
- **No CODEOWNERS**: PR review 누가 할지 모름.
- **Mixed package managers**: npm + yarn + pnpm — 매 lockfile chaos. 한 개로 통일.

## 🧪 검증 / 중복
- Verified (Turborepo docs, Nx docs, Module Federation spec, "Building Micro-Frontends" Geers).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Turborepo + module federation + vertical slice |