Files
clean-architecture-frontend…/docs/architecture/scale-architecture.md
DongHyeonka af10cae9a6 docs(architecture): 현재 계약 문서와 매뉴얼의 영어 부분을 한국어로 옮긴다
문제: docs/architecture의 현재 계약 문서 가운데 scale-architecture.md,
starter-experience.md, capability-consumer-experience.md,
contract-ownership.md, static-delivery.md, review-evidence.md는 본문이
영어이고, backend-api-and-server-state-contract.md와
optional-adapter-recipes.md에는 영어 문단이 남아 있다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. 백틱 안, 링크 대상, 절 번호(코드
주석이 `scale-architecture.md §N`으로 인용한다), 표 구조, 코드 블록은
그대로 둔다. 문서를 읽는 테스트와 절 이름을 인용한 곳을 같은 변경에서
고친다.
- tests/unit/feature-tracked-files.test.ts: starter-experience.md 표를
  자르는 시작·끝 문장과 표 행마다 찾는 낱말(`병합 충돌`)
- 「Ownership declarations」「Adding a feature」를 인용한 주석
  (create-feature.ts, generate-product-feature-index.ts, app-module.ts)과
  docs/manual의 절 이름 인용
- optional-adapter-recipes.md의 recipe 개수 복사를 카탈로그를 가리키게
  바꾼다(number 검사)

위험: create-feature.ts 417줄은 생성하는 context-module.ts의 JSDoc이라
새로 만드는 기능의 주석 글자가 바뀐다. 그 글자를 비교하는 테스트는 없다.
review-evidence.md는 산문만 옮겼고 해시·점수 칸은 그대로다.

검증: 백틱 span·링크 대상·코드 블록·번호 제목을 옮기기 전과 python으로
비교해 같다. 문서 검사의 language 줄이 이 문서들에서 0이 되어 예외
목록에서 지웠다.
2026-11-08 21:57:47 +09:00

1409 lines
47 KiB
Markdown

# 규모 아키텍처
> **상태 머리말 (2026-11-03)**
>
> - **현재 계약인 범위.** 아래 표에서 상태가 "현재 계약"인 절만 지금 코드가 지키는 규칙이다. "기록만"인 절은 2026-09-23 설계 당시의 계획·목록이고, 구현되지 않았거나 바뀌었다. 문서와 코드가 다르면 코드가 맞다.
> - **출처.** 2026-09-23 설계서 "Extreme-Scale Frontend Architecture Design"을 커밋 `6f6c48e`(2026-09-24)에서 옮겼다. 원래 파일은 작업 이력 묶음 안에 있어 복사한 프로젝트가 지울 수 있다. 원문은 `git show 6f6c48e:docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/design/2026-09-23-extreme-scale-frontend-architecture-design.md`로 볼 수 있다.
> - **본문.** §1~§55는 영어 원문을 2026-11-08에 한국어로 옮긴 것이다. 뜻은 바꾸지 않았고 절 번호도 그대로다. 원문 머리의 날짜·대상·상태·예정 경로 줄만 이 머리말로 바꿨다.
> - **코드가 이 문서를 가리키는 방법.** 코드 주석은 `scale-architecture.md §N` 형식으로 쓴다. 문서 이름이 없는 "Spec" + 절 번호 참조는 `tests/unit/deletable-history-documents.test.ts`가 거부한다. 절 번호를 바꾸면 `git grep "scale-architecture.md §"`로 찾은 주석을 모두 함께 고친다.
> - **코드와 달라진 곳을 적는 규칙.** 원문 문장은 고치지 않는다. 확인한 차이는 그 절 끝에 `> YYYY-MM-DD 현재:` 한두 줄로 적는다. 절의 상태가 바뀌면 아래 표도 고친다.
## 절 상태
- **현재 계약 (코드 참조)**: 코드 주석이 `scale-architecture.md §N`으로 가리키는 절이다. 2026-11-03에 절의 주장을 그 절을 가리키는 모듈의 타입·머리 주석·테스트 이름과 대조했다. 동작을 실행해 확인한 것은 아니다.
- **현재 계약**: 코드가 가리키지 않지만 지금 코드가 지키는 절이다. 같은 날 같은 방법으로 대조했다.
- **기록만**: 구현되지 않았거나 바뀐 절이다. 설계 당시의 기록으로 남긴다.
- "차이 메모"가 "있음"이면 그 절 끝에 `2026-11-03 현재` 메모가 있다.
집계: 현재 계약 (코드 참조) 41 · 현재 계약 10 · 기록만 4 · 미확인 0.
| § | 제목 | 상태 | 차이 메모 |
|---|---|---|---|
| 1 | 목적 | 현재 계약 | |
| 2 | 핵심 원칙 | 현재 계약 | |
| 3 | 규모 모델 | 현재 계약 (코드 참조) | |
| 4 | 목표 소스 구조 | 현재 계약 (코드 참조) | 있음 |
| 5 | 모듈 소유 | 현재 계약 | 있음 |
| 6 | 의존성 규칙 | 현재 계약 | |
| 7 | 개수 예산 | 현재 계약 | 있음 |
| 8 | registry 조립 | 현재 계약 | |
| 9 | 라우터 구조 | 현재 계약 | |
| 10 | 실행 모델 | 현재 계약 (코드 참조) | 있음 |
| 11 | 트래픽 예산 | 현재 계약 (코드 참조) | 있음 |
| 12 | 요청 fan-out | 현재 계약 (코드 참조) | |
| 13 | 재시도 모델 | 현재 계약 (코드 참조) | |
| 14 | 동시 실행 예산 | 현재 계약 (코드 참조) | |
| 15 | 마감 시간 전파 | 현재 계약 (코드 참조) | |
| 16 | 요청 중복 제거와 합치기 | 현재 계약 (코드 참조) | |
| 17 | 오류 모델 | 현재 계약 (코드 참조) | |
| 18 | 오류 봉투 | 현재 계약 (코드 참조) | |
| 19 | presentation 오류 매핑 | 현재 계약 (코드 참조) | |
| 20 | 검증 경계 | 현재 계약 (코드 참조) | |
| 21 | 신뢰 경계에서 한 번만 검증 | 현재 계약 (코드 참조) | |
| 22 | 검증 예산 | 현재 계약 (코드 참조) | |
| 23 | telemetry 모델 | 현재 계약 (코드 참조) | |
| 24 | telemetry 소유 | 현재 계약 (코드 참조) | 있음 |
| 25 | telemetry 파이프라인 | 현재 계약 (코드 참조) | 있음 |
| 26 | 업무 동작에는 telemetry가 fail-open이어야 한다 | 현재 계약 (코드 참조) | |
| 27 | telemetry 폭주 방어 | 현재 계약 (코드 참조) | |
| 28 | telemetry 개인정보 보호와 redaction | 현재 계약 (코드 참조) | |
| 29 | trace와 correlation | 현재 계약 (코드 참조) | 있음 |
| 30 | 실패 경계 | 현재 계약 (코드 참조) | |
| 31 | 비동기 실패 모델 | 현재 계약 | 있음 |
| 32 | 급증 트래픽 설계 | 현재 계약 (코드 참조) | 있음 |
| 33 | 지속 트래픽 설계 | 현재 계약 (코드 참조) | |
| 34 | 증폭 지표 | 현재 계약 (코드 참조) | |
| 35 | 규모 프로필 | 현재 계약 (코드 참조) | |
| 36 | 로컬 규모 검증 | 현재 계약 (코드 참조) | 있음 |
| 37 | 전역 토폴로지 검증 | 현재 계약 (코드 참조) | 있음 |
| 38 | TypeScript 규모 게이트 | 현재 계약 (코드 참조) | |
| 39 | runtime 조립 규모 게이트 | 현재 계약 (코드 참조) | |
| 40 | 브라우저 부팅 게이트 | 기록만 | 있음 |
| 41 | 요청 fan-out 게이트 | 현재 계약 (코드 참조) | |
| 42 | 실패·카오스 시나리오 | 현재 계약 (코드 참조) | |
| 43 | telemetry 폭주 테스트 | 현재 계약 (코드 참조) | |
| 44 | soak 테스트 | 현재 계약 (코드 참조) | 있음 |
| 45 | 수평 확장과 릴리스 일관성 | 현재 계약 (코드 참조) | 있음 |
| 46 | 다중 replica 릴리스 행렬 | 현재 계약 (코드 참조) | |
| 47 | CI 실행 단계 | 현재 계약 (코드 참조) | 있음 |
| 48 | 벤치마크 결과 형식 | 현재 계약 (코드 참조) | 있음 |
| 49 | 회귀 정책 | 현재 계약 (코드 참조) | |
| 50 | 필요한 아키텍처 게이트 | 현재 계약 (코드 참조) | 있음 |
| 51 | 현재 템플릿 강점과의 호환 | 기록만 | |
| 52 | 명시적으로 하지 않는 것 | 현재 계약 | |
| 53 | 구현 순서 제약 | 기록만 | |
| 54 | 완료 기준 | 기록만 | |
| 55 | 설계 요약 | 현재 계약 | |
## 1. 목적
이 설계는 프론트엔드 템플릿을 앱 하나짜리 Clean Architecture 뼈대에서 프론트엔드 애플리케이션 플랫폼으로 키운다. 이 플랫폼은 논리 도메인 수, 트래픽, 실패율, 운영 기간이 극단으로 커져도 유지보수할 수 있어야 한다.
이 설계는 아래 최악의 성장 가정에서도 성립해야 한다.
- 제품 생태계 전체에 논리 기능·도메인이 100, 1,000, 10,000, 100,000, 1,000,000개 있다.
- 짧고 심한 급증 트래픽이 온다.
- 높은 트래픽이 오래 이어진다.
- 백엔드가 일부 또는 전부 실패한다.
- 재시도 폭주, telemetry 폭주, cache-miss 폭주, 느린 upstream이 생긴다.
- 브라우저 세션이 오래 열려 있다.
- rolling 릴리스 중에 프론트엔드가 여러 replica로 배포되어 있다.
목표는 SPA 하나가 기능 백만 개를 컴파일하고 부팅하게 만드는 것이 **아니다**. 목표는 한도가 있는 아키텍처 경계를 강제해서, 전역 규모가 커져도 로컬 runtime 비용과 빌드 비용이 따라 늘지 않게 하는 것이다.
## 2. 핵심 원칙
> 어떤 개수(cardinality)도 암묵적으로 무제한이 되어서는 안 된다.
이 규칙은 아래 모두에 똑같이 적용된다.
- 컴파일 그래프
- route 그래프
- 기능 registry
- 기능 간 의존성
- HTTP 요청 fan-out(요청 하나가 여러 요청으로 퍼지는 것)
- 재시도
- 동시 실행 수
- payload 크기
- 검증 비용
- telemetry 버퍼링
- timer·listener
- 브라우저 저장소
- 실패 전파
플랫폼은 이 비용을 코드와 CI에서 드러내야 한다. 배열, `map`, `Promise.all`, 전역 registry, 재시도, timer, 프레임워크 추상화 뒤에 숨게 두면 안 된다.
## 3. 규모 모델
### 3.1 전역 개수와 로컬 개수를 나눈다
서로 다른 두 개념을 절대 섞지 않는다.
```text
GlobalFeatureCount
= logical feature count across the whole product ecosystem
LocalFeatureCount
= feature count compiled and booted by one deployable frontend application
```
시스템 전체에는 논리 기능이 1,000,000개 있어도, 배포 단위 app 하나는 기능을 100~300개만 볼 수 있다.
### 3.2 아키텍처 계층 구조
```text
Product
-> Deployable App
-> Bounded Context
-> Feature
-> Use Case / Operation
-> Route / Adapter
```
부모 경계는 바로 아래 자식만 안다. 모든 자손을 전역 registry 하나로 펼치지 않는다.
예:
```text
Product
-> Commerce App
-> Order Context
-> Order Creation Feature
-> Payment Context
-> Account App
-> Identity Context
```
`Product`는 `OrderCreatePage`, `PaymentRefundUseCase` 같은 깊은 자손을 import하면 안 된다.
### 3.3 규모 탈출 규칙
경계가 측정한 개수 한도에 닿으면 아키텍처를 나눈다. 한도를 끝없이 올리지 않는다.
```text
Feature too large
-> split feature
Context too large
-> split bounded context
App too large
-> split deployable app
```
서버 아키텍처에서 한도 없는 암묵적 일대다 관계를 거부하는 것과 같다.
## 4. 목표 소스 구조
```text
src/
├─ domain/
├─ application/
│ └─ ports/
├─ contracts/
├─ platform/
│ ├─ cardinality/
│ ├─ traffic/
│ ├─ resilience/
│ ├─ errors/
│ ├─ validation/
│ └─ telemetry/
├─ features/
│ └─ <feature>/
│ ├─ domain/
│ ├─ application/
│ ├─ contracts/
│ ├─ adapters/
│ ├─ presentation/
│ └─ feature-module.ts
├─ contexts/
│ └─ <bounded-context>/
│ └─ context-module.ts
├─ apps/
│ └─ <deployable-app>/
│ └─ app-module.ts
├─ .generated/
│ └─ <generated static indexes>
└─ bootstrap/
└─ compose-product.ts
```
정확한 경로 배치는 repo의 현재 관례에 맞춰 바꿔도 된다. 소유 경계는 반드시 지킨다.
> 2026-11-03 현재: 위 그림의 최상위 `domain/` 폴더는 없다. domain 계층은 기능 안(`src/features/<id>/domain`)에만 있다. `src/platform`에는 `execution`·`release`·`routing`도 있다.
> 색인은 생성기가 git이 무시하는 `src/.generated/`에 쓴다. 조립 코드는 `src/bootstrap/`에 있고 `compose-product.ts`라는 파일은 없다. 실제 폴더 목록의 정본은 [`layers.md`](layers.md)다.
## 5. 모듈 소유
### 5.1 기능 모듈
기능마다 자기 기여(contribution)를 담은 descriptor 하나를 소유한다.
개념 API:
```ts
export const ORDER_FEATURE = defineFeatureModule({
id: "order",
contracts,
adapters,
runtime,
routes,
messages,
invalidation,
telemetry,
});
```
새 기능을 넣으려고 중앙 설치 파일 여러 개를 손으로 고치게 하면 안 된다.
목표 변경 범위:
```text
src/features/new-feature/**
.generated/**
```
보통의 기능 추가에서 고치는, 손으로 쓴 중앙 production 파일 수:
```text
0 preferred
1 maximum when a deliberate bounded-context registration is required
```
### 5.2 bounded context 모듈
context는 바로 아래 기능 모듈만 조립한다.
```ts
export const COMMERCE_CONTEXT = defineBoundedContextModule({
id: "commerce",
features: COMMERCE_FEATURE_INDEX,
budget: COMMERCE_CARDINALITY_BUDGET,
});
```
관계없는 context에 기능의 구체적인 내부 구현을 드러내지 않는다.
### 5.3 배포 단위 app 모듈
배포 단위 app은 바로 아래 bounded context만 소유한다.
```ts
export const CUSTOMER_APP = defineDeployableApp({
id: "customer",
contexts: CUSTOMER_CONTEXT_INDEX,
});
```
규모가 그만큼 커지면 app마다 따로 컴파일하고 배포하는 단위가 된다.
### 5.4 생성 색인
색인은 빌드 때 승인된 정적 소스 선언에서 생성한다.
지켜야 할 성질:
- 정적 TypeScript import
- 결정적 출력(같은 입력이면 같은 결과)
- runtime에 임의 경로를 import하지 않음
- 믿을 수 없는 설정을 보고 runtime에 plugin을 찾지 않음
- 생성 파일은 손으로 쓰는 registry가 아님
이렇게 하면 tree-shaking, 공급망 검토 가능성, 컴파일 시점 가시성을 지킨다. 동시에 중앙 파일에서 merge 충돌이 몰리는 지점을 없앤다.
> 2026-11-03 현재: 실제 API는 `defineFeatureModule`(`src/features/feature-module.ts`), `defineBoundedContextModule`(`src/contexts/bounded-context-module.ts`), `defineDeployableAppModule`(`src/apps/deployable-app-module.ts`)이다. 기능 모듈의 필드는 `id`·`contracts`·`routes`·`messages`·`loadRuntime`이다.
> context와 app은 `context-module.ts`·`app-module.ts`의 상수로 소유와 한도를 선언한다. 생성기 `scripts/generate-product-feature-index.ts`가 이 선언을 읽어 색인을 만든다.
## 6. 의존성 규칙
### 6.1 기능 간 구체 import 금지
서로 다른 기능 A와 B 사이의 아래 의존은
```text
src/features/A/** -> src/features/B/**
```
아키텍처 위반이다. 명시적으로 승인한 공개 계약 경계를 거치는 의존만 예외다.
권장하는 상호작용 경계:
```text
feature
-> src/contracts
-> src/application/ports
-> explicit orchestration/workflow feature
```
### 6.2 context 간 import는 더 엄격하다
context는 다른 context에 있는 기능의 구체적인 내부를 import하면 안 된다.
허용하는 통신 경로:
- 공개 계약
- application port
- 이름을 붙여 명시한 통합 계약
- 맞는 경우, 서버를 거친 통합
### 6.3 순환은 언제나 금지다
기능, context, app 경계를 넘는 순환은 하나도 허용하지 않는다.
## 7. 개수 예산
플랫폼은 아키텍처 예산을 명시적으로 정한다.
개념상의 모양:
```ts
interface ArchitectureCardinalityBudget {
readonly maxContextsPerApp: number;
readonly maxFeaturesPerContext: number;
readonly maxRoutesPerFeature: number;
readonly maxOperationsPerFeature: number;
readonly maxMessagesPerFeature: number;
}
```
초기 숫자는 이 설계가 정하지 않는다. repo 벤치마크로 정해야 한다.
예산 파일은 리뷰에서 보여야 하고 버전 관리해야 한다.
예산을 올리면 아키텍처 리뷰가 알아챌 수 있는 신호가 나와야 한다.
실패 예:
```text
ARCHITECTURE_CARDINALITY_EXCEEDED
Context: commerce
Current: 201
Allowed: 200
Action: split the context or create another deployable boundary.
```
> 2026-11-03 현재: 한도를 하나로 묶은 `ArchitectureCardinalityBudget` 타입은 없다. 선언마다 자기 한도를 가진다(`APP_MAX_CONTEXTS = 20`, `CONTEXT_MAX_FEATURES = 200`).
> 한도를 넘으면 `src/platform/cardinality/cardinality-budget.ts`의 `assertWithinCardinalityBudget`이 `CardinalityBudgetExceededError`를 던진다.
## 8. registry 조립
### 8.1 누적 루프에서 객체 spread를 반복하지 않는다
규모에 민감한 조립 경로에서는 아래 패턴을 금지한다.
```ts
features.reduce(
(registry, feature) => ({ ...registry, ...feature.routes }),
{},
);
```
누적한 상태를 매번 복사하므로 registry가 커질수록 제곱에 가깝게 느려진다.
### 8.2 정해진 조립 방법
바꿀 수 있는 로컬 누적 객체 하나를 쓴다. 중복은 명시적으로 검사한다. 마지막에 한 번만 freeze한다.
```ts
const result = Object.create(null);
for (const feature of features) {
for (const [id, route] of Object.entries(feature.routes)) {
if (Object.hasOwn(result, id)) {
throw new DuplicateRouteError(id);
}
result[id] = route;
}
}
return Object.freeze(result);
```
registry가 필요하면 연산, schema, mapper, invalidation, adapter, runtime, message 기여를 조립할 때도 같은 방법을 쓴다.
### 8.3 포함 여부 검사
아래처럼 선형 포함 검사를 반복하는 코드는
```ts
installedIds.includes(featureId)
```
규모에 민감한 루프에서 쓰면 안 된다.
`Set`을 한 번 만들고 `has`를 쓴다.
## 9. 라우터 구조
제품 전체를 담은 평평한 route 표는 극단 규모에서 받아들일 수 없는 모델이다.
목표 계층:
```text
Product Router
-> Deployable App Router
-> Context Router
-> Feature Router
-> Page Route
```
바로 다음 경계만 미리 불러온다.
전역 규모의 예:
```text
Global logical features: 1,000,000
Browser boot routes: product/app boundary only
Commerce app selected: commerce context routes loaded
Order context selected: order feature routes loaded
```
전역 기능 수가 늘어도 초기 route 객체 수, 초기 번들 크기, 부팅 heap이 선형으로 늘면 안 된다.
## 10. 실행 모델
### 10.1 interaction이 가장 바깥 실행 범위다
가장 높은 단위는 HTTP 요청이 아니다. 사용자나 애플리케이션의 동작 하나(interaction)다.
예:
- 주문 페이지 열기
- 결제 제출
- workspace 바꾸기
- 검색 결과 불러오기
개념상의 context:
```ts
interface ExecutionContext {
readonly interaction: InteractionContext;
readonly traffic: TrafficContext;
readonly telemetry: TelemetryContext;
readonly cancellation: CancellationContext;
}
```
연산은 같은 interaction 범위 안에서 돈다.
### 10.2 interaction context
```ts
interface InteractionContext {
readonly interactionId: InteractionId;
readonly startedAt: number;
readonly deadlineAt: number;
}
```
모든 자식 연산은 correlation 정보와 마감 시간 정보를 물려받는다.
> 2026-11-03 현재: `src/platform/execution/execution-context.ts`의 `ExecutionContext` 필드는 `interaction`(`id`·`startedAt`·`deadlineAt`), `cancellation`, `traffic`, 선택 필드 `trace`, `clock`이다. `telemetry` 필드는 없다.
## 11. 트래픽 예산
트래픽 비용은 드러나 있어야 하고 한도가 있어야 한다.
개념 모델:
```ts
interface TrafficBudget {
readonly maxPhysicalRequests: number;
readonly maxConcurrentRequests: number;
readonly maxRetries: number;
readonly deadlineMs: number;
}
```
정책 선언은 기능이 소유한다. 강제는 플랫폼이 소유한다.
```ts
defineQueryOperation({
id: "order.list",
traffic: {
maxPhysicalRequests: 2,
maxConcurrentRequests: 2,
maxRetries: 1,
deadlineMs: 4_000,
},
});
```
플랫폼은 기능별 트래픽 설정을 모은 전역 registry를 하나 두면 안 된다.
> 2026-11-03 현재: `TrafficBudget`의 필드는 `maxPhysicalRequests`·`maxRetries`·`maxConcurrentRequests`·`maxQueuedRequests`다. 마감 시간은 따로 받는다(`createExecutionContext`의 `deadlineMs`, HTTP 계약의 `totalDeadlineMs`).
> 연산의 정책은 HTTP 계약의 선택 필드 `traffic`(`src/contracts/external-contract-runtime.ts`)이다. 없으면 `src/adapters/http/http-execution-v3.ts`의 `DEFAULT_OPERATION_TRAFFIC_BUDGET`을 쓴다. `defineQueryOperation`은 없다.
## 12. 요청 fan-out
프론트엔드 N+1은 아키텍처 결함으로 본다.
금지하는 동작:
```text
load 1 collection
-> N rows
-> N detail requests
```
권장하는 동작:
- 페이지·cursor API
- 한도가 있는 페이지 크기
- 백엔드 bulk 엔드포인트
- 백엔드 read model
- 요청 합치기(coalescing)
- query·cache 소유 공유
대표 사용자 interaction마다 물리 요청 예산이 있어야 한다.
합성 통합 테스트는 데이터 개수를 늘리면서 네트워크 요청 수가 O(N)이 아니라 한도 안에 머무는지 확인한다.
## 13. 재시도 모델
### 13.1 재시도 예산은 interaction 단위다
재시도 횟수는 요청마다 따로 초기화하지 않는다.
```text
Interaction retry budget = 2
A consumes retry
B consumes retry
C cannot retry after budget exhaustion
```
그래서 자식 요청 여러 개가 복구 트래픽을 몇 배로 늘리지 못한다.
### 13.2 재시도 전제 조건
재시도는 연산의 의미가 허락할 때만 한다.
기존 idempotency·replay 의미가 계속 기준이다.
### 13.3 Retry-After와 jitter
`Retry-After` 응답 때문에 모든 클라이언트가 같은 시각에 맞춰져 두 번째 급증을 만들면 안 된다.
실제 재시도 시각은 서버가 알려 준 값에 한도가 있는 jitter(무작위 지연)를 합쳐 정한다.
## 14. 동시 실행 예산
interaction마다 동시에 보내는 물리 요청 수에 한도가 있다.
기다리는 작업은 취소할 수 있어야 한다.
interaction을 취소하면 아래를 취소하거나 놓아 줘야 한다.
- 대기열의 요청
- 가능하면, 진행 중인 요청
- 재시도 timer
- 동시 실행 lease
- 안전하면, 버려진 그 interaction에만 묶인 지연 telemetry
## 15. 마감 시간 전파
timeout은 재시도나 하위 호출마다 다시 시작하지 않는다.
interaction이 시작할 때 루트 마감 시간을 정한다.
자식은 남은 시간을 계산한다.
```ts
remainingMs = deadlineAt - now();
```
그래서 재시도가 이어져도 5초짜리 사용자 동작이 한도 없이 20초, 30초짜리 동작으로 늘어나지 않는다.
## 16. 요청 중복 제거와 합치기
여러 소비자가 같은 논리 자원을 동시에 요청하면, 호환되는 진행 중 작업을 함께 쓰는 것이 맞다.
```text
10 consumers
-> 1 physical request
-> 10 subscribers
```
의미가 연산과 맞는 곳에서는 기존 TanStack Query 기반이 자연스러운 구현 바탕이다.
중복 제거는 인증, tenant, scope, locale, cache 신원 경계가 서로 맞지 않는 요청을 절대 합치면 안 된다.
## 17. 오류 모델
오류는 알맞은 경계가 소유한다.
```text
Platform Error
Contract Error
Application / Domain Error
Presentation Mapping
```
### 17.1 플랫폼 오류
예:
- 네트워크 없음
- 요청 timeout
- 취소
- 너무 큰 응답
- 지원하지 않는 content type
- 형식이 깨진 전송 응답
- 트래픽 예산 초과
### 17.2 계약 오류
계약 실패는 외부 경계에서 생긴 위반을 가리킨다.
- schema 불일치
- protocol 불일치
- 지원하지 않는 media type
- 필수 필드 누락
- 형식이 깨진 payload
### 17.3 domain·application 오류
구체적인 업무 오류는 계속 기능이 소유한다.
예:
```ts
type PaymentError =
| PaymentDeclined
| PaymentAlreadyProcessed
| PaymentLimitExceeded;
```
### 17.4 전역 오류 union 금지
아래는 금지다.
```ts
type GlobalApplicationError =
| OrderError
| PaymentError
| ...;
```
대신 로컬 generic 경계를 쓴다.
```ts
Result<T, E extends AppError>
```
플랫폼은 공통 봉투(envelope)만 안다.
## 18. 오류 봉투
구조 없는 `throw new Error("...")`는 계층을 넘는 주된 오류 계약이 아니다.
개념상의 공통 메타데이터:
```ts
interface AppError {
readonly kind: string;
readonly category: ErrorCategory;
readonly retryability: Retryability;
readonly severity: ErrorSeverity;
}
```
구체적인 domain 오류의 의미는 로컬에 남는다.
## 19. presentation 오류 매핑
HTTP 상태 코드와 전송 세부가 presentation 로직으로 새면 안 된다.
나쁜 예:
```ts
if (status === 409) { ... }
```
권장 흐름:
```text
HTTP 409
-> Transport/Contract interpretation
-> PaymentAlreadyProcessed
-> localized presentation message
```
## 20. 검증 경계
검증은 목적이 서로 다르다.
1. 사용자 입력 검증
2. 전송 검증
3. domain 불변식 검증
4. runtime 설정 검증
프론트엔드 검증은 UX를 좋게 한다. 하지만 기준이 되는 보안 경계는 절대 아니다. 기준은 계속 백엔드 검증이다.
## 21. 신뢰 경계에서 한 번만 검증
외부 데이터는 모르는(unknown), 믿을 수 없는 데이터로 들어온다.
```text
unknown HTTP body
-> size/content checks
-> parse
-> schema validation
-> Validated DTO
-> mapper
-> domain/application types
```
신뢰 경계라는 구체적인 이유 없이 같은 payload를 내부 계층마다 schema로 다시 검증하지 않는다.
## 22. 검증 예산
검증 자체에도 비용 한도가 있다.
비싼 파싱과 검증 전에, 가능한 곳에서 구조 제약을 먼저 건다.
- 응답 최대 바이트
- collection 최대 항목 수
- 문자열 최대 길이
- 해당하면, 허용하는 최대 중첩 깊이
- 한도가 있는 mapper 출력 크기
너무 큰 응답은 크기 제한 없는 객체 그래프를 메모리에 만들거나 검증하기 전에 거절해야 한다.
## 23. telemetry 모델
production 프론트엔드에는 관측성(observability)이 필요하다. 하지만 날 로그를 찍는 것이 아키텍처는 아니다.
플랫폼이 지원하는 것:
- 오류 보고
- 실사용자 모니터링(RUM)
- trace·correlation 전파
- 구조화한 운영 이벤트
- 성능 지표
기능 코드는 Sentry, Datadog 같은 vendor SDK에 직접 의존하면 안 된다.
개념상의 port:
```ts
interface TelemetryPort {
emit<T extends TelemetryPayload>(event: TelemetryEvent<T>): void;
}
```
provider adapter는 플랫폼 경계 뒤에 둔다.
## 24. telemetry 소유
플랫폼은 공통 봉투를 소유한다. 기능마다의 이벤트 정의는 소유하지 않는다.
공통 메타데이터에 들어갈 수 있는 것:
- 이벤트 이름
- 심각도
- 릴리스
- app·context·기능 식별자
- interaction ID
- trace·correlation 식별자
- 시각
- 안전한 속성
구체적인 이벤트 payload schema는 계속 기능이 소유한다.
모든 기능을 담는 전역 telemetry 이벤트 union은 허용하지 않는다.
> 2026-11-03 현재: 봉투(`src/platform/telemetry/telemetry-event.ts`)의 필드는 `kind`·`severity`·`contextId`·`featureId`·`interactionId`·`traceId`·`payload`다.
> 릴리스 식별자(`build_id`·`release_id`)는 수집기 adapter(`src/adapters/telemetry/telemetry-collector.ts`)가 붙인다. 시각과 app 식별자는 봉투에 없다.
## 25. telemetry 파이프라인
필요한 개념 파이프라인:
```text
Feature event
-> normalize
-> redact
-> fingerprint
-> deduplicate
-> sample
-> bounded buffer
-> batch
-> rate limit
-> transport
```
브라우저 안의 모든 queue와 map에는 한도가 있다.
> 2026-11-03 현재: 코드의 순서는 봉투 검사 → redact → fingerprint → deduplicate → sample → buffer → rate limit → batch → transport다(`src/platform/telemetry/telemetry-pipeline.ts`). normalize 자리에 봉투 검사가 있고, rate limit이 batch보다 앞이다.
## 26. 업무 동작에는 telemetry가 fail-open이어야 한다
telemetry가 실패해도 애플리케이션 동작은 실패하면 안 된다.
아래 두 경로는
```text
business path
telemetry path
```
서로 분리되어 있다.
telemetry 용량이 다 차면 우선순위가 낮은 관측 데이터를 버린다. 브라우저 메모리를 늘리거나 사용자 동작을 막지 않는다.
## 27. telemetry 폭주 방어
production 장애 하나 때문에 브라우저 수백만 개가 같은 오류를 동시에 보고할 수 있다.
그래서 telemetry 하위 시스템에는 아래가 필요하다.
- 결정적이거나 정책을 따르는 sampling
- 반복 오류 fingerprint
- 한도가 있는 중복 제거 상태
- 한도가 있는 batch 크기
- queue의 바이트·이벤트 수 한도
- rate limit
- 우선순위에 따른 버리기
관측이 장애를 키워 또 다른 장애를 만들면 절대 안 된다.
## 28. telemetry 개인정보 보호와 redaction
기능 작성자가 무심코 비밀 값을 내보낼 수 없어야 한다.
runtime 정제는 아래 같은 민감한 값을 거절하거나 가려야(redact) 한다.
- Authorization 값
- cookie
- access token
- refresh token
- 비밀번호
- 알려진 비밀 필드
정확성을 높인다면 타입이 있는 안전한 payload를 더해도 된다. 그래도 runtime 방어는 계속 필요하다. 컴파일 시점 타입은 보안 경계가 아니기 때문이다.
## 29. trace와 correlation
지원되는 곳에서는 사용자 interaction이 브라우저 이벤트를 백엔드 trace와 잇는 것이 맞다.
```text
user interaction
-> interaction id
-> request trace/correlation metadata
-> backend trace
-> downstream dependency
```
trace 전파는 선택한 백엔드·OTel 계약을 따라야 한다. 기능마다 호환되지 않는 식별자를 따로 만들면 안 된다.
> 2026-11-03 현재: 전파는 interaction이 켰을 때만 한다(`ExecutionContext`의 `trace`는 선택 필드). 헤더는 `traceparent`와 `x-correlation-id`다(`src/platform/telemetry/trace-context.ts`).
## 30. 실패 경계
실패를 가두는 범위는 아키텍처 소유 구조를 그대로 따른다.
```text
App Boundary
-> Context Boundary
-> Feature Boundary
-> Page Boundary where useful
```
모든 컴포넌트에 ErrorBoundary를 두지 않는다. 경계는 의미 있는 복구·대체 화면 단위에 맞춘다.
결제 UI가 실패했다고 주문, 카탈로그, 계정 UI까지 무너질 필요는 없다.
## 31. 비동기 실패 모델
React 렌더링 실패는 실패의 한 종류일 뿐이다.
아키텍처는 아래도 모델로 다룬다.
- query 실패
- mutation 실패
- 검증 실패
- timeout
- 취소
- 트래픽 예산 소진
쓸모가 있는 곳에서는 화면 상태가 복구할 수 있는 결과, 끝난(terminal) 결과, 취소된 결과를 구분하는 것이 맞다.
> 2026-11-03 현재: 화면 상태는 `src/application/view-models/async-state.ts`가 정한다. 기본 상태 `terminal-error`와 덧씌움 `stale-degraded`·`mutation-effect-unknown`·`mutation-conflict`가 있다. 취소만 따로 보여 주는 상태는 이 목록에 없다.
## 32. 급증 트래픽 설계
급증 시나리오에는 아래 같은 급격한 증가가 있다.
```text
100 clients
-> 10,000
-> 100,000+
```
프론트엔드 플랫폼은 사용자 수를 통제할 수 없다. 하지만 클라이언트 쪽 증폭은 통제해야 한다.
핵심 위험:
- 재시도 폭주
- 인증 갱신 폭주
- cache-miss 폭주
- telemetry 폭주
- 모든 클라이언트가 같은 시각에 맞춰지는 `Retry-After`
- 통제되지 않는 동시 실행
- 중복 요청
> 2026-11-03 현재: 이 절을 가리키는 테스트(`tests/platform/traffic/traffic-amplification.test.ts`)는 실패와 병렬 연산에서 요청·재시도 증폭만 본다. 인증 갱신 폭주와 cache-miss 폭주를 따로 재는 규모 테스트는 찾지 못했다.
## 33. 지속 트래픽 설계
오래 이어지는 높은 트래픽과 오래 열린 SPA 세션은 다른 위험을 드러낸다.
- heap 증가
- timer·listener 누수
- query cache 교체 반복(churn)
- 브라우저 저장소 증가
- 낡은 인증·세션 상태
- 반복되는 백그라운드 polling
- 밀린 telemetry
- 주인 잃은 AbortController나 작업
그래서 규모 검증은 최대 요청 수만 보지 않는다. soak 방식 테스트(오래 돌려 누수를 보는 테스트)와 메모리 기울기도 본다.
## 34. 증폭 지표
플랫폼 테스트 harness가 운영 증폭 지표를 정한다.
### 34.1 요청 증폭
```text
physical HTTP requests / logical interactions
```
### 34.2 재시도 증폭
```text
total physical attempts / initial physical requests
```
### 34.3 telemetry 증폭
```text
telemetry sends / logical failures or events
```
이 지표는 정상, 느림, 부분 실패, 전체 실패 조건에서 잰다.
## 35. 규모 프로필
합성 규모 프로필:
```text
S0 100
S1 1,000
S2 10,000
S3 100,000
S4 1,000,000
```
모든 프로필이 「TypeScript 소스 파일을 그만큼 만든다」는 뜻은 아니다.
### S0-S1
실제 모듈 조립과 타입 검사 fixture를 돌려 볼 수 있다.
### S2
감당할 수 있으면 더 큰 생성 색인과 조립 구조를 돌려 본다.
### S3-S4
주로 전역 토폴로지와 로컬 경계의 독립성을 검증한다. 논리 기능 10만 개나 100만 개를 모델로 만들고, 어느 app·context 하나도 로컬 예산 안에 머무는지 확인한다.
## 36. 로컬 규모 검증
허용된 경계 하나 안에서 아래를 잰다.
- registry 조립
- route 조립
- 생성 색인 비용
- TypeScript 진단
- 번들·빌드 비용
- 브라우저 부팅 비용
선형 작업을 피할 수 없는 곳에서, 규모에 민감한 조립은 선형이거나 그보다 나은 증가를 보여야 한다.
제곱에 가까운 증가는 실패다.
> 2026-11-03 현재: 규모 측정(`scripts/scale/run-composition-scale.ts`, `scripts/scale/collect-tsc-diagnostics.ts`)은 registry·route 조립, 생성 색인, TypeScript 진단을 잰다. 번들·빌드 비용과 브라우저 부팅 비용은 이 측정에 없다(§40).
## 37. 전역 토폴로지 검증
app 하나를 그대로 두고 전역 논리 개수를 늘린다.
확인할 것:
```text
Global feature count increases
but unchanged App A should not materially increase:
- TypeScript source graph
- initial bundle bytes
- initial routes
- initial runtime registries
- boot heap
- boot CPU
```
이것이 아키텍처가 논리 도메인 10만·100만 개까지 늘 수 있다는 핵심 증거다.
> 2026-11-03 현재: `tests/scale/global-local-independence.test.ts`는 생성 색인, 소스 그래프, 부팅 때 읽는 context 루트를 본다. 번들은 `check:app-build-input:bundle`이 "소유하지 않은 기능의 모듈이 없다"만 본다. 부팅 heap·CPU는 재지 않는다.
## 38. TypeScript 규모 게이트
지원되면 `--extendedDiagnostics`를 포함한 컴파일러 진단을 쓴다.
최소한 아래를 기록한다.
- 소스 파일 수
- 타입 수
- symbol 수
- instantiation 수
- 메모리
- 전체 타입 검사 시간
전역 module augmentation이나 거대한 union 때문에, 전역 도메인 수가 늘 때 관계없는 app의 컴파일 비용이 오르면 설계 회귀다.
## 39. runtime 조립 규모 게이트
해당하는 registry를 벤치마크한다.
- route
- API 연산
- schema
- mapper
- invalidation
- adapter 기여
- runtime 기여
- locale·message 기여
N 값을 여러 개로 시험해 비선형 회귀를 찾는다.
절대 시간만으로는 부족하다. 늘어나는 모양이 중요하다.
## 40. 브라우저 부팅 게이트
잴 것:
- 처음 전송하는 JS
- 파싱·실행한 JS
- 초기 route 수
- 초기 heap
- bootstrap CPU
- runtime 설정 가져오기
- 릴리스 manifest 검증
- 의미 있는 첫 애플리케이션 렌더링
전역 토폴로지가 커져도, 바뀌지 않은 app의 이 지표가 비례해서 늘면 안 된다.
> 2026-11-03 현재: 이 목록을 재는 부팅 게이트는 없다. 초기 JS gzip 크기만 `check:bundle`이 `config/performance/budgets.json`의 `initialJsGzipBytes`로 막는다. 초기 heap, 부팅 CPU, 첫 렌더, 초기 route 수는 재지 않는다.
## 41. 요청 fan-out 게이트
서버가 돌려주는 개수를 늘려 가며 대표 collection 페이지를 쓴다.
```text
N = 10
N = 100
N = 1,000
```
한도 있는 bulk 요청 두 개가 필요한 페이지는 요청 수가 그 근처에 머물러야 한다. 행마다 상세 호출을 보내 O(N)번이 되면 안 된다.
> **구현 메모 (2026-09-23).** 템플릿의 대표 collection 계약은 페이지로 나눈 bulk 읽기다. 페이지 한도는 100행으로 고정이다(`limit` ≤ 100, 응답 schema `max(100)`). 위의 `N`은 서버 쪽 collection 개수이지 응답 하나의 크기가 아니다. 그래서 합격 기준은 두 층이다.
>
> - 지원하는 개수 — N = 10 / 50 / 100 / 1,000행 collection은 물리 요청 **1**번으로 한 페이지를 불러온다. 1,000행 전체를 훑는 데는 페이지 요청이 ceil(N / 100) + 1번 이하로 든다. 행마다 요청을 하나씩 보내는 일은 없다.
> - 너무 큰 응답 — 페이지 한도보다 많이 담은 응답 하나(예: 한 번에 1,000행)는 계약 위반으로 보고 요청 **1**번 안에 거절한다. 행마다 하위 fan-out이 생기지 않는다.
>
> 너무 큰 fixture를 통과시키려고 한도를 올리지 않는다. 소스 게이트(`pnpm check:request-fanout`)가 기능·application 코드에서 루프나 배열 순회 callback 안에서 요청을 보내는 코드를 거절한다.
## 42. 실패·카오스 시나리오
필요한 시나리오는 아래와 같다.
### 전체 API 실패
확인할 것:
- 재시도 한도
- 동시 실행 한도
- telemetry 한도
- 한도가 있는 메모리
- 무한 루프 없음
- reload 반복 없음
### 부분 실패
예:
```text
Payment 100% failure
Order healthy
Catalog healthy
```
결제는 기능을 줄인 채 버티고, 관계없는 context를 무너뜨리지 않는 것이 맞다.
### 느린 API
긴 꼬리 지연(long-tail latency)을 시험한다. 마감 시간, 취소, 동시 실행 대기열, 대기열 한도를 확인한다.
### 네트워크 끊김 반복
online·offline이 반복해서 바뀌어도 안전하지 않은 mutation이 중복되거나 재시도가 한꺼번에 몰리면 안 된다.
### telemetry 엔드포인트 실패
업무 동작은 계속 돌고, telemetry 저장량은 한도 안에 머문다.
## 43. telemetry 폭주 테스트
똑같은 오류·이벤트를 아주 많이 만든다.
기대 동작:
```text
many logical errors
-> fingerprint/dedup/sample
-> bounded number of buffered/sent telemetry events
```
테스트는 내보낸 수, 중복 제거한 수, sampling에서 빠진 수, 버린 수, 전송한 수를 기록한다.
## 44. soak 테스트
긴 세션 프로필은 환경 비용에 따라 30분, 2시간, 8시간, 24시간일 수 있다.
볼 것:
- heap 크기와 기울기
- 살아 있는 timer
- event listener
- DOM 노드
- query cache 크기
- telemetry buffer
- IndexedDB·브라우저 저장소
- 낡은 인증·세션 상태가 새는 누수
누수의 주된 신호는 예상한 warm-up 안정화 뒤에도 계속 늘어나는 것이다. 임의로 정한 최대 heap 값만 보지 않는다.
> 2026-11-03 현재: 브라우저 soak(`scripts/scale/browser-soak.ts`)은 nightly 단계에서 2분 돈다. heap, DOM 노드, listener, timer, 진행 중 fetch, Web Storage를 잰다.
> query cache와 telemetry buffer는 논리 테스트(`tests/scale/session/long-session.test.ts`)가 본다. IndexedDB는 재지 않고, 30분 이상 돌리는 실행은 없다.
## 45. 수평 확장과 릴리스 일관성
프론트엔드 애플리케이션 인스턴스는 stateless로 둔다. 브라우저 사용자 상태를 서버 인스턴스에 두지 않는다는 뜻이다.
수평 확장은 릴리스 일관성을 지킬 때만 안전하다.
배포 계약:
- 내용 hash가 붙은 asset은 바꾸지 않는다(immutable).
- HTML은 현재 릴리스 전략에 따라 revalidate하거나 no-cache로 둔다.
- runtime 설정과 릴리스 manifest는 no-store다.
- rolling 릴리스 동안 예전 hash asset을 계속 받을 수 있다.
- 배포는 활성 릴리스 묶음(tuple)을 한 번에(atomic) 바꾼다.
- 호환되지 않는 HTML·설정·manifest가 섞이면 애매하게 실행하지 않고 닫힌 쪽으로 실패한다(fail closed).
> 2026-11-03 현재: 불일치를 만나면 세션마다 한 번만 자동으로 다시 불러오고, 그 뒤의 불일치는 실패 화면으로 끝낸다(`src/platform/release/release-mismatch-recovery.ts`). 이 재시도는 원문에 없다.
## 46. 다중 replica 릴리스 행렬
최소한 아래를 확인한다.
| HTML | 설정 | manifest | asset | 기대 결과 |
| --- | --- | --- | --- | --- |
| R10 | R10 | R10 | R10 | PASS |
| R10 | R11 | R10 | R10 | FAIL CLOSED |
| R10 | R10 | R11 | R10 | FAIL CLOSED |
| R10 | R10 | R10 | 없음/호환 안 됨 | FAIL |
| R11 | R11 | R11 | R11 | PASS |
rolling 배포는 예전 HTML을 불러온 클라이언트가 이전의 immutable hash asset에 계속 닿을 수 있게 해야 한다.
## 47. CI 실행 단계
무거운 규모 테스트 때문에 모든 pull request가 쓸 수 없을 만큼 비싸지면 안 된다.
### pull request 단계
빠르고 결정적인 게이트:
- 의존성 아키텍처
- 개수 예산
- 단위 테스트
- app·테스트 타입 검사
- 작은 조립 fixture
- 중복 충돌 테스트
- 기능 간 의존 fixture
- 작은 요청 fan-out fixture
### main 브랜치 단계
중간 규모 회귀:
- 맞는 경우, 1K/10K 합성 조립
- TypeScript 진단 비교
- route·bootstrap 증가 검사
- 생성 색인 검증
### nightly 단계
무거운 합성 검증과 브라우저 검증:
- 10K/100K/1M 토폴로지 모델
- 브라우저 메모리와 route 불러오기
- telemetry 폭주
- 실패 시나리오
- 더 긴 화면 이동·세션 반복
### 릴리스 / 전용 환경 단계
환경에 따라 달라지는 검사:
- 급증 부하
- soak 부하
- cache 동작
- 다중 replica 혼합 릴리스 검증
- CDN·LB·origin 릴리스 계약
> 2026-11-03 현재: CI는 `pr` 단계만 돌린다(FE-GATE-005). `main`·`nightly`·`release`는 로컬 명령이다. 기준선 시간 비교가 그 기준선을 기록한 CPU에서만 성립하기 때문이다(`scripts/scale/run-scale-profile.ts`).
## 48. 벤치마크 결과 형식
규모 결과는 콘솔 출력으로만 끝내지 않고, 기계가 읽을 수 있는 산출물로 남긴다.
예:
```json
{
"profile": "S2",
"globalLogicalFeatures": 10000,
"localFeatures": 150,
"routeCompositionMs": 3.21,
"typescriptMs": 4312,
"heapBytes": 1234567
}
```
호환되는 기준선과 비교할 수 있을 만큼 메타데이터를 저장한다.
> 2026-11-03 현재: 실제 형식은 `scripts/scale/benchmark-result.ts`의 `BenchmarkResult`(`name`·`profile`·`cardinality`·`samples`·`medianMs`·`heapBytes`·`metadata`)와 이를 담는 `BenchmarkArtifact`다. 위 JSON은 예시다.
## 49. 회귀 정책
기준값은 세 종류를 쓴다.
1. 절대 상한
2. 상대 회귀 비율
3. 증가 복잡도 추세
환경 잡음이 영향을 주는 곳에서는 성능 측정을 여러 번 돌리고, 중앙값처럼 튼튼한 요약값을 쓰는 것이 맞다.
순환, 중복 ID, 기능 간 구체 import, 개수 예산 위반 같은 구조 실패는 결정적이다. 바로 실패해야 한다.
## 50. 필요한 아키텍처 게이트
아키텍처는 결국 아래 항목의 자동 게이트를 갖춰야 한다.
1. 기능 간 구체 import 금지
2. context 간 구체 import 금지
3. 순환 금지
4. 개수 예산
5. 기능·route·연산·schema ID 중복
6. O(N²)식 registry 회귀
7. 요청 fan-out 회귀
8. 재시도 예산 강제
9. telemetry buffer 한도
10. 전역 규모와 로컬 규모의 독립
11. TypeScript·빌드 규모 회귀
12. 다중 replica 릴리스 일관성
> 2026-11-03 현재: 1~3번은 `.dependency-cruiser.json`의 `features-do-not-import-other-features`, `contexts-do-not-import-other-contexts`, `no-circular-dependencies`다. 11번(TypeScript 규모)은 `main` 단계에만 있어 CI에서 돌지 않는다(§47).
## 51. 현재 템플릿 강점과의 호환
이 설계는 현재 강점을 갈아엎지 않는다. 지키면서 넓힌다.
- Clean Architecture 계층 규칙
- capability 기준 adapter 조립
- HTTP 연산 계약
- 한도가 있는 응답 처리
- 재시도·idempotency 의미
- TanStack Query cache 소유
- scope fencing·generation 동작
- 릴리스·빌드·설정 일관성
- immutable 정적 asset 릴리스 모델
구현은 불필요한 UI·디자인 변경 없이 조립을 리팩터링하고 플랫폼 정책을 들여온다.
## 52. 명시적으로 하지 않는 것
이 설계가 요구하지 않는 것:
- TypeScript 기능 100만 개를 담은 SPA 하나
- runtime에 임의의 원격 코드 찾기
- 기본 출발점으로서의 Module Federation이나 micro-frontend
- 전역 초대형 registry
- 전역 초대형 오류 union
- 전역 telemetry schema union
- 기능 코드 안의 vendor 전용 관측 API
- 백엔드 검증을 대신하는 프론트엔드 검증
원격·micro-frontend 배포는 나중에 고를 수 있는 단계로 남긴다. 조직 경계나 배포 경계 때문에 팀·릴리스를 따로 가져가야 할 때다. 지금의 규모 아키텍처를 푸는 데는 필요 없다.
## 53. 구현 순서 제약
구현은 조금씩 하고 동작을 지킨다.
안전한 큰 순서는 아래와 같다.
1. 현재 동작을 감싸는 결정적 아키텍처·규모 테스트를 세운다.
2. 알려진 O(N²) 조립 경로와 포함 검사를 반복하는 조립 경로를 없앤다.
3. 기능이 소유하는 descriptor 경계를 들여온다.
4. 정적 product·context 색인을 생성한다.
5. 기능 간·context 간 의존성 규칙을 강제한다.
6. 계층형 route 조립을 들여온다.
7. 개수 예산을 들여온다.
8. 실행 context와 트래픽 예산을 들여온다.
9. 오류 경계와 검증 경계를 정리한다.
10. telemetry port·파이프라인·예산을 들여온다.
11. CI 단계별로 규모·카오스·soak·릴리스 게이트를 더한다.
자세한 구현 계획은 이 순서를 테스트 먼저(test-first) 작업으로 쪼개야 한다. 그리고 지금 repo 상태를 다시 읽은 뒤 고칠 기존 파일을 정확히 짚어야 한다.
## 54. 완료 기준
아래가 모두 참일 때만 이 설계를 구현했다고 본다.
- 보통의 기능을 더할 때 손으로 쓴 중앙 설치 registry 여러 개를 고치지 않는다.
- 조립에 알려진 제곱 누적 패턴이 없다.
- 규모에 민감한 경로의 포함 검사는 알맞은 색인 구조를 쓴다.
- 관계없는 기능 사이의 구체 import는 아키텍처 검사에서 실패한다.
- context·app 개수 한도가 드러나 있고 테스트할 수 있다.
- 전역 논리 토폴로지가 S3/S4 fixture 쪽으로 커져도, 바뀌지 않은 로컬 app은 눈에 띄게 커지지 않는다.
- 초기 라우팅은 제품 전체의 평평한 기능 표가 아니라 계층형·지연 로딩이다.
- 사용자 interaction은 한도가 있는 요청·재시도·동시 실행·취소·마감 시간 의미를 지닌다.
- 대표 collection은 프론트엔드 N+1 요청 fan-out을 만들지 않는다.
- 오류는 모든 기능 오류를 모은 전역 union 없이, 로컬에서 타입을 가진 채 남는다.
- 외부 데이터는 신뢰 경계에서 검증한다. payload·구조 비용에는 한도가 있다.
- 기능 코드는 vendor SDK가 아니라 플랫폼 port로 관측 데이터를 보낸다.
- telemetry는 한도가 있는 메모리 안에서 redact, 중복 제거, sampling, buffering, rate limit을 거친다.
- telemetry 실패가 업무 동작을 실패시키지 않는다.
- 실패 경계 덕분에 기능·context 하나가 관계없는 UI까지 괜히 무너뜨리지 않는다.
- 급증·지속 부하 테스트가 요청, 재시도, telemetry, 메모리 증폭을 잡아낸다.
- 다중 replica 릴리스 테스트가 fail-closed 일관성과 예전 asset 도달 가능성을 확인한다.
## 55. 설계 요약
이 아키텍처는 규칙 하나에 기댄다.
> 전역 규모는 한도가 있는 로컬 규모로 나눠야 한다. 그리고 남은 로컬 개수에는 모두 명시적인 예산이 있어야 한다.
그래서 플랫폼은 아래를 피한다.
```text
unbounded registry
unbounded compile graph
unbounded route graph
unbounded request fan-out
unbounded retries
unbounded concurrency
unbounded payloads
unbounded validation
unbounded telemetry
unbounded memory growth
unbounded failure propagation
```
그래서 제품 생태계는 논리 도메인 수백 개에서 수십만, 수백만 개로 커질 수 있다. 브라우저 하나, TypeScript 컴파일러 실행 한 번, 라우터 하나, runtime registry 하나가 그 전역 개수를 직접 떠안지 않아도 된다.