문제: 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이 되어 예외 목록에서 지웠다.
1409 lines
47 KiB
Markdown
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 하나가 그 전역 개수를 직접 떠안지 않아도 된다.
|