Files
clean-architecture-frontend…/docs/architecture/scale-architecture.md
T
DongHyeonka c4d587052e fix(removal): 참조 기능을 지워도 문서 게이트가 통과하고 드릴이 그것을 본다
문제
README는 참조 기능을 지울 수 있다고 적는다. 그러나 매뉴얼·입구 문서
10개가 참조 기능과 그 드릴 전용 파일의 경로를 백틱으로 적고,
verify:documentation(FE-GATE-017)은 백틱 경로의 존재를 검사한다. 그래서
참조 기능을 지운 복사본에서 문서 게이트가 경로 24개로 실패한다. 제거
드릴(test:sample-removal)은 문서를 복사하지 않고 그 게이트와 lint·
check:i18n·check:design-system을 돌리지 않아 이 충돌을 보지 못했다.

고른 방법
- 리뷰 5.2절 (b): 참조 기능이 가진 경로는 백틱 없이 "예제(참조 기능)"으로
  적는다. 기능 공통 모양은 생성 경로 꼴(`src/features/<id>/domain`)로
  적는다. 규칙은 docs/manual/reference/patterns.md 첫머리에 적었다.
- 드릴은 REMOVAL_FIXTURE_DOCUMENT_TARGETS(README·CHANGELOG·docs)까지
  복사하고, 지운 뒤와 생성 기능을 더한 뒤 두 번 모두 lint,
  verify:documentation, check:i18n, check:design-system을 돈다
  (FOLLOW-UP 09-07). 문서 테스트 두 개도 fixture에서 다시 돈다.
- 버린 대안: 검사기가 참조 기능 경로를 "없어도 되는 경로"로 보기(5.2
  (c)). 매뉴얼이 없는 파일을 가리키는 상태를 허용한다. 참조 기능을 지울
  수 없게 하기(5.2 (d)). README 약속과 드릴의 존재 이유가 바뀐다.

위험·한계
- 템플릿 자신에서도 참조 기능 경로의 존재를 문서 검사가 더는 보지
  않는다. 참조 기능 파일 이름을 바꾸면 그 문장은 사람이 고쳐야 한다.
- 드릴 시간이 lint·문서 검사 두 번만큼 는다.
- 드릴 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기).

검증
- 참조 기능·참조 context·SAMPLE_EXTRAS를 지운 복사본(scratchpad
  sim-sample-docs.sh)에서 수정 전 FAIL_UNVERIFIED(문서 10개), 수정 뒤
  PASS_SCOPED.
- 저장소에서 verify:documentation PASS_SCOPED,
  documentation-readiness 14건 통과, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
2026-11-04 21:02:14 +09:00

1407 lines
43 KiB
Markdown

# Scale Architecture
> **상태 머리말 (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/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md`로 볼 수 있다.
> - **본문.** §1~§55는 영어 원문 그대로다. 절 번호는 바꾸지 않았다. 원문 머리의 날짜·대상·상태·예정 경로 줄만 이 머리말로 바꿨다.
> - **코드가 이 문서를 가리키는 방법.** 코드 주석은 `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 | Purpose | 현재 계약 | |
| 2 | Core Principle | 현재 계약 | |
| 3 | Scale Model | 현재 계약 (코드 참조) | |
| 4 | Target Source Structure | 현재 계약 (코드 참조) | 있음 |
| 5 | Module Ownership | 현재 계약 | 있음 |
| 6 | Dependency Rules | 현재 계약 | |
| 7 | Cardinality Budgets | 현재 계약 | 있음 |
| 8 | Registry Composition | 현재 계약 | |
| 9 | Router Architecture | 현재 계약 | |
| 10 | Execution Model | 현재 계약 (코드 참조) | 있음 |
| 11 | Traffic Budget | 현재 계약 (코드 참조) | 있음 |
| 12 | Request Fan-Out | 현재 계약 (코드 참조) | |
| 13 | Retry Model | 현재 계약 (코드 참조) | |
| 14 | Concurrency Budget | 현재 계약 (코드 참조) | |
| 15 | Deadline Propagation | 현재 계약 (코드 참조) | |
| 16 | Request Deduplication and Coalescing | 현재 계약 (코드 참조) | |
| 17 | Error Model | 현재 계약 (코드 참조) | |
| 18 | Error Envelope | 현재 계약 (코드 참조) | |
| 19 | Presentation Error Mapping | 현재 계약 (코드 참조) | |
| 20 | Validation Boundaries | 현재 계약 (코드 참조) | |
| 21 | Validate Once at Trust Boundaries | 현재 계약 (코드 참조) | |
| 22 | Validation Budget | 현재 계약 (코드 참조) | |
| 23 | Telemetry Model | 현재 계약 (코드 참조) | |
| 24 | Telemetry Ownership | 현재 계약 (코드 참조) | 있음 |
| 25 | Telemetry Pipeline | 현재 계약 (코드 참조) | 있음 |
| 26 | Telemetry Must Fail Open for Business Behavior | 현재 계약 (코드 참조) | |
| 27 | Telemetry Storm Protection | 현재 계약 (코드 참조) | |
| 28 | Telemetry Privacy and Redaction | 현재 계약 (코드 참조) | |
| 29 | Trace and Correlation | 현재 계약 (코드 참조) | 있음 |
| 30 | Failure Boundaries | 현재 계약 (코드 참조) | |
| 31 | Async Failure Model | 현재 계약 | 있음 |
| 32 | Spike Traffic Design | 현재 계약 (코드 참조) | 있음 |
| 33 | Sustained Traffic Design | 현재 계약 (코드 참조) | |
| 34 | Amplification Metrics | 현재 계약 (코드 참조) | |
| 35 | Scale Profiles | 현재 계약 (코드 참조) | |
| 36 | Local Scale Verification | 현재 계약 (코드 참조) | 있음 |
| 37 | Global Topology Verification | 현재 계약 (코드 참조) | 있음 |
| 38 | TypeScript Scale Gate | 현재 계약 (코드 참조) | |
| 39 | Runtime Composition Scale Gate | 현재 계약 (코드 참조) | |
| 40 | Browser Boot Gate | 기록만 | 있음 |
| 41 | Request Fan-Out Gate | 현재 계약 (코드 참조) | |
| 42 | Failure and Chaos Scenarios | 현재 계약 (코드 참조) | |
| 43 | Telemetry Storm Test | 현재 계약 (코드 참조) | |
| 44 | Soak Testing | 현재 계약 (코드 참조) | 있음 |
| 45 | Horizontal Scaling and Release Coherence | 현재 계약 (코드 참조) | 있음 |
| 46 | Multi-Replica Release Matrix | 현재 계약 (코드 참조) | |
| 47 | CI Execution Tiers | 현재 계약 (코드 참조) | 있음 |
| 48 | Benchmark Result Format | 현재 계약 (코드 참조) | 있음 |
| 49 | Regression Policy | 현재 계약 (코드 참조) | |
| 50 | Required Architecture Gates | 현재 계약 (코드 참조) | 있음 |
| 51 | Compatibility With Current Template Strengths | 기록만 | |
| 52 | Explicit Non-Goals | 현재 계약 | |
| 53 | Implementation Sequence Constraints | 기록만 | |
| 54 | Acceptance Criteria | 기록만 | |
| 55 | Design Summary | 현재 계약 | |
## 1. Purpose
This design evolves the frontend template from a single-application Clean Architecture skeleton into a frontend application platform that remains maintainable when logical domain count, traffic, failure rate, and operating duration become extreme.
The design must remain valid under worst-case growth assumptions:
- 100, 1,000, 10,000, 100,000, or 1,000,000 logical features/domains across the product ecosystem.
- Short, severe spike traffic.
- Sustained high traffic over long periods.
- Partial and total backend failures.
- Retry storms, telemetry storms, cache-miss storms, and slow upstreams.
- Long-lived browser sessions.
- Multi-replica frontend deployments during rolling releases.
The goal is **not** to make one SPA compile and boot one million features. The goal is to make global growth independent from local runtime and build cost by enforcing bounded architecture boundaries.
## 2. Core Principle
> No cardinality may become implicitly unbounded.
The same rule applies to:
- compile graphs,
- route graphs,
- feature registries,
- cross-feature dependencies,
- HTTP request fan-out,
- retries,
- concurrency,
- payload size,
- validation cost,
- telemetry buffering,
- timers/listeners,
- browser storage,
- failure propagation.
The platform must expose these costs explicitly in code and CI instead of allowing them to hide behind arrays, `map`, `Promise.all`, global registries, retries, timers, or framework abstractions.
## 3. Scale Model
### 3.1 Separate global and local cardinality
Two different concepts must never be conflated:
```text
GlobalFeatureCount
= logical feature count across the whole product ecosystem
LocalFeatureCount
= feature count compiled and booted by one deployable frontend application
```
A system may contain 1,000,000 logical features while an individual deployable app sees only 100-300 features.
### 3.2 Architectural hierarchy
```text
Product
-> Deployable App
-> Bounded Context
-> Feature
-> Use Case / Operation
-> Route / Adapter
```
A parent boundary knows only its direct children. It does not flatten every descendant into a global registry.
Example:
```text
Product
-> Commerce App
-> Order Context
-> Order Creation Feature
-> Payment Context
-> Account App
-> Identity Context
```
`Product` must not import `OrderCreatePage`, `PaymentRefundUseCase`, or other deep descendants.
### 3.3 Scale escape rule
When a boundary reaches its measured cardinality ceiling, the response is architectural split, not increasing the ceiling indefinitely.
```text
Feature too large
-> split feature
Context too large
-> split bounded context
App too large
-> split deployable app
```
This is equivalent to refusing an implicit unbounded one-to-many relation in server-side architecture.
## 4. Target Source Structure
```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
```
The exact path layout may adapt to current repository conventions, but ownership boundaries are mandatory.
> 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. Module Ownership
### 5.1 Feature module
Each feature owns one descriptor containing its own contributions.
Conceptual API:
```ts
export const ORDER_FEATURE = defineFeatureModule({
id: "order",
contracts,
adapters,
runtime,
routes,
messages,
invalidation,
telemetry,
});
```
A new feature must not require hand editing multiple central installation files.
Target change surface:
```text
src/features/new-feature/**
.generated/**
```
Central handwritten production files changed for a normal feature addition:
```text
0 preferred
1 maximum when a deliberate bounded-context registration is required
```
### 5.2 Bounded context module
A context composes only its direct feature modules.
```ts
export const COMMERCE_CONTEXT = defineBoundedContextModule({
id: "commerce",
features: COMMERCE_FEATURE_INDEX,
budget: COMMERCE_CARDINALITY_BUDGET,
});
```
It does not expose concrete internal feature implementations to unrelated contexts.
### 5.3 Deployable app module
A deployable app owns only direct bounded contexts.
```ts
export const CUSTOMER_APP = defineDeployableApp({
id: "customer",
contexts: CUSTOMER_CONTEXT_INDEX,
});
```
Each app becomes an independent compilation and deployment unit once scale requires it.
### 5.4 Generated indexes
Indexes are generated at build time from approved static source declarations.
Required properties:
- static TypeScript imports,
- deterministic output,
- no arbitrary runtime import path,
- no runtime plugin discovery from untrusted configuration,
- generated files are not handwritten registries.
This preserves tree-shaking, supply-chain reviewability, and compile-time visibility while eliminating central merge hotspots.
> 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. Dependency Rules
### 6.1 Cross-feature concrete imports are forbidden
For different features A and B:
```text
src/features/A/** -> src/features/B/**
```
is an architecture violation unless the dependency is through an explicitly approved public contract boundary.
Preferred interaction boundaries:
```text
feature
-> src/contracts
-> src/application/ports
-> explicit orchestration/workflow feature
```
### 6.2 Cross-context imports are stricter
A context must not import another context's concrete feature internals.
Allowed communication is through:
- public contracts,
- application ports,
- explicitly named integration contracts,
- server-backed integration where appropriate.
### 6.3 Cycles are always forbidden
No cycle is permitted across feature, context, or app boundaries.
## 7. Cardinality Budgets
The platform defines explicit architectural budgets.
Conceptual shape:
```ts
interface ArchitectureCardinalityBudget {
readonly maxContextsPerApp: number;
readonly maxFeaturesPerContext: number;
readonly maxRoutesPerFeature: number;
readonly maxOperationsPerFeature: number;
readonly maxMessagesPerFeature: number;
}
```
Initial numeric values are not hardcoded by this design. They must be established through repository benchmarks.
Budget files must be visible in review and version controlled.
Budget increases must produce a detectable architecture-review signal.
Example failure:
```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 Composition
### 8.1 No repeated object spread in accumulation loops
This pattern is forbidden in scale-sensitive composition paths:
```ts
features.reduce(
(registry, feature) => ({ ...registry, ...feature.routes }),
{},
);
```
It repeatedly copies accumulated state and becomes quadratic-like as the registry grows.
### 8.2 Required composition strategy
Use one mutable local accumulator, explicit duplicate detection, then freeze once.
```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);
```
The same strategy applies to operation, schema, mapper, invalidation, adapter, runtime, and message contribution composition when a registry is necessary.
### 8.3 Membership checks
Repeated linear membership tests such as:
```ts
installedIds.includes(featureId)
```
must not be used in scale-sensitive loops.
Build a `Set` once and use `has`.
## 9. Router Architecture
A flat product-wide route table is not an acceptable extreme-scale model.
Target hierarchy:
```text
Product Router
-> Deployable App Router
-> Context Router
-> Feature Router
-> Page Route
```
Only the next boundary is loaded eagerly.
Example at global scale:
```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
```
Global feature count must not linearly increase initial route object count, initial bundle size, or boot heap.
## 10. Execution Model
### 10.1 Interaction is the root execution scope
HTTP requests are not the highest-level unit. A user or application interaction is.
Examples:
- open an order page,
- submit a payment,
- change workspace,
- load search results.
Conceptual context:
```ts
interface ExecutionContext {
readonly interaction: InteractionContext;
readonly traffic: TrafficContext;
readonly telemetry: TelemetryContext;
readonly cancellation: CancellationContext;
}
```
Operations run under the same interaction scope.
### 10.2 Interaction context
```ts
interface InteractionContext {
readonly interactionId: InteractionId;
readonly startedAt: number;
readonly deadlineAt: number;
}
```
All child operations inherit correlation and deadline information.
> 2026-11-03 현재: `src/platform/execution/execution-context.ts`의 `ExecutionContext` 필드는 `interaction`(`id`·`startedAt`·`deadlineAt`), `cancellation`, `traffic`, 선택 필드 `trace`, `clock`이다. `telemetry` 필드는 없다.
## 11. Traffic Budget
Traffic cost must be explicit and bounded.
Conceptual model:
```ts
interface TrafficBudget {
readonly maxPhysicalRequests: number;
readonly maxConcurrentRequests: number;
readonly maxRetries: number;
readonly deadlineMs: number;
}
```
A feature owns the policy declaration; the platform owns enforcement.
```ts
defineQueryOperation({
id: "order.list",
traffic: {
maxPhysicalRequests: 2,
maxConcurrentRequests: 2,
maxRetries: 1,
deadlineMs: 4_000,
},
});
```
The platform must not maintain one global per-feature traffic 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. Request Fan-Out
Frontend N+1 is treated as an architecture defect.
Forbidden behavior:
```text
load 1 collection
-> N rows
-> N detail requests
```
Preferred behavior:
- pagination/cursor APIs,
- bounded page sizes,
- backend bulk endpoints,
- backend read models,
- request coalescing,
- shared query/cache ownership.
A representative user interaction must have a physical-request budget.
Synthetic integration tests increase data cardinality while asserting that network request count remains bounded rather than O(N).
## 13. Retry Model
### 13.1 Retry budget is interaction-scoped
Retry count is not independently reset for every request.
```text
Interaction retry budget = 2
A consumes retry
B consumes retry
C cannot retry after budget exhaustion
```
This prevents multiple child requests from multiplying recovery traffic.
### 13.2 Retry prerequisites
Retries are allowed only when operation semantics permit them.
The existing idempotency/replay semantics remain authoritative.
### 13.3 Retry-After and jitter
A `Retry-After` response must not synchronize all clients into a second spike.
Effective scheduling combines server guidance with bounded jitter.
## 14. Concurrency Budget
Each interaction has bounded concurrent physical requests.
Waiting work must be cancelable.
Cancellation of an interaction must cancel or release:
- queued requests,
- in-flight requests where possible,
- retry timers,
- concurrency leases,
- delayed telemetry associated only with that discarded interaction when safe.
## 15. Deadline Propagation
Timeouts do not reset after each retry or downstream call.
A root deadline is established at interaction start.
Each child computes remaining time:
```ts
remainingMs = deadlineAt - now();
```
A chain of retries therefore cannot turn a 5-second user operation into an unbounded 20- or 30-second operation.
## 16. Request Deduplication and Coalescing
Multiple consumers requesting the same logical resource concurrently should share compatible in-flight work.
```text
10 consumers
-> 1 physical request
-> 10 subscribers
```
The existing TanStack Query infrastructure is a natural implementation foundation where its semantics match the operation.
Deduplication must never merge requests across incompatible authentication, tenant, scope, locale, or cache identity boundaries.
## 17. Error Model
Errors are owned at the correct boundary.
```text
Platform Error
Contract Error
Application / Domain Error
Presentation Mapping
```
### 17.1 Platform errors
Examples:
- network unavailable,
- request timeout,
- cancellation,
- response too large,
- unsupported content type,
- malformed transport response,
- traffic budget exceeded.
### 17.2 Contract errors
Contract failures identify violations at an external boundary:
- schema mismatch,
- protocol mismatch,
- unsupported media type,
- missing required field,
- malformed payload.
### 17.3 Domain/application errors
Concrete business errors remain feature-owned.
Example:
```ts
type PaymentError =
| PaymentDeclined
| PaymentAlreadyProcessed
| PaymentLimitExceeded;
```
### 17.4 No global error union
This is forbidden:
```ts
type GlobalApplicationError =
| OrderError
| PaymentError
| ...;
```
Use local generic boundaries instead:
```ts
Result<T, E extends AppError>
```
The platform understands only the common envelope.
## 18. Error Envelope
Unstructured `throw new Error("...")` is not the primary cross-layer error contract.
Conceptual common metadata:
```ts
interface AppError {
readonly kind: string;
readonly category: ErrorCategory;
readonly retryability: Retryability;
readonly severity: ErrorSeverity;
}
```
Concrete domain error semantics remain local.
## 19. Presentation Error Mapping
HTTP status codes and transport details must not leak into presentation logic.
Bad:
```ts
if (status === 409) { ... }
```
Preferred flow:
```text
HTTP 409
-> Transport/Contract interpretation
-> PaymentAlreadyProcessed
-> localized presentation message
```
## 20. Validation Boundaries
Validation has distinct purposes:
1. user-input validation,
2. transport validation,
3. domain invariant validation,
4. runtime configuration validation.
Frontend validation improves UX but is never an authoritative security boundary. Backend validation remains authoritative.
## 21. Validate Once at Trust Boundaries
External data enters as unknown/untrusted data.
```text
unknown HTTP body
-> size/content checks
-> parse
-> schema validation
-> Validated DTO
-> mapper
-> domain/application types
```
The same payload should not be repeatedly schema-validated at every internal layer without a specific trust-boundary reason.
## 22. Validation Budget
Validation itself has bounded cost.
Before expensive parsing and validation, enforce structural constraints where possible:
- maximum response bytes,
- maximum collection items,
- maximum string lengths,
- maximum allowed nesting/depth where relevant,
- bounded mapper output size.
Oversized responses must be rejected before allocating or validating an arbitrarily large object graph.
## 23. Telemetry Model
Production frontend observability is required, but raw logging is not the architecture.
The platform supports:
- error reporting,
- real user monitoring,
- trace/correlation propagation,
- structured operational events,
- performance metrics.
Feature code must not depend directly on a vendor SDK such as Sentry or Datadog.
Conceptual port:
```ts
interface TelemetryPort {
emit<T extends TelemetryPayload>(event: TelemetryEvent<T>): void;
}
```
Provider adapters live behind the platform boundary.
## 24. Telemetry Ownership
The platform owns a common envelope, not every feature event definition.
Common metadata may include:
- event name,
- severity,
- release,
- app/context/feature identifiers,
- interaction ID,
- trace/correlation identifiers,
- timestamp,
- safe attributes.
Concrete event payload schemas remain feature-owned.
No global telemetry event union containing every feature is allowed.
> 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 Pipeline
Required conceptual pipeline:
```text
Feature event
-> normalize
-> redact
-> fingerprint
-> deduplicate
-> sample
-> bounded buffer
-> batch
-> rate limit
-> transport
```
All in-browser queues and maps are bounded.
> 2026-11-03 현재: 코드의 순서는 봉투 검사 → redact → fingerprint → deduplicate → sample → buffer → rate limit → batch → transport다(`src/platform/telemetry/telemetry-pipeline.ts`). normalize 자리에 봉투 검사가 있고, rate limit이 batch보다 앞이다.
## 26. Telemetry Must Fail Open for Business Behavior
Telemetry failure must not fail application behavior.
```text
business path
telemetry path
```
are separated.
When telemetry capacity is exhausted, low-priority observability data is dropped rather than growing browser memory or blocking user operations.
## 27. Telemetry Storm Protection
A production incident may cause millions of browsers to report the same error simultaneously.
The telemetry subsystem therefore requires:
- deterministic or policy-driven sampling,
- repeated-error fingerprinting,
- bounded deduplication state,
- bounded batch size,
- bounded queue bytes/events,
- rate limiting,
- priority-based dropping.
Observability must never amplify an incident into another outage.
## 28. Telemetry Privacy and Redaction
Feature authors must not be able to casually emit secrets.
Runtime sanitization must reject/redact sensitive classes such as:
- Authorization values,
- cookies,
- access tokens,
- refresh tokens,
- passwords,
- known secret fields.
Typed safe payloads may be added where they improve correctness, but runtime defense remains required because compile-time types are not a security boundary.
## 29. Trace and Correlation
User interactions should connect browser events with backend traces where supported.
```text
user interaction
-> interaction id
-> request trace/correlation metadata
-> backend trace
-> downstream dependency
```
Trace propagation must follow the chosen backend/OTel contract and must not invent incompatible identifiers independently per feature.
> 2026-11-03 현재: 전파는 interaction이 켰을 때만 한다(`ExecutionContext`의 `trace`는 선택 필드). 헤더는 `traceparent`와 `x-correlation-id`다(`src/platform/telemetry/trace-context.ts`).
## 30. Failure Boundaries
Failure containment mirrors architecture ownership.
```text
App Boundary
-> Context Boundary
-> Feature Boundary
-> Page Boundary where useful
```
Not every component gets an ErrorBoundary. Boundaries correspond to meaningful recovery/fallback domains.
A payment UI failure should not necessarily destroy order, catalog, or account UI.
## 31. Async Failure Model
React render failures are only one class of failure.
The architecture also models:
- query failure,
- mutation failure,
- validation failure,
- timeout,
- cancellation,
- traffic-budget exhaustion.
Presentation state should distinguish recoverable, terminal, and cancelled outcomes where useful.
> 2026-11-03 현재: 화면 상태는 `src/application/view-models/async-state.ts`가 정한다. 기본 상태 `terminal-error`와 덧씌움 `stale-degraded`·`mutation-effect-unknown`·`mutation-conflict`가 있다. 취소만 따로 보여 주는 상태는 이 목록에 없다.
## 32. Spike Traffic Design
Spike scenarios include rapid jumps such as:
```text
100 clients
-> 10,000
-> 100,000+
```
The frontend platform cannot control the number of users, but it must control client-side amplification.
Critical risks:
- retry storm,
- authentication refresh storm,
- cache-miss storm,
- telemetry storm,
- synchronized `Retry-After`,
- uncontrolled concurrency,
- duplicate requests.
> 2026-11-03 현재: 이 절을 가리키는 테스트(`tests/platform/traffic/traffic-amplification.test.ts`)는 실패와 병렬 연산에서 요청·재시도 증폭만 본다. 인증 갱신 폭주와 cache-miss 폭주를 따로 재는 규모 테스트는 찾지 못했다.
## 33. Sustained Traffic Design
Long-running high traffic and long-lived SPA sessions expose different risks:
- heap growth,
- timer/listener leaks,
- query cache churn,
- browser storage growth,
- stale auth/session state,
- repeated background polling,
- telemetry backlog,
- orphaned AbortControllers or tasks.
Scale verification therefore includes soak-style tests and memory slope, not only peak request count.
## 34. Amplification Metrics
The platform test harness defines operational amplification metrics.
### 34.1 Request amplification
```text
physical HTTP requests / logical interactions
```
### 34.2 Retry amplification
```text
total physical attempts / initial physical requests
```
### 34.3 Telemetry amplification
```text
telemetry sends / logical failures or events
```
These are measured under healthy, slow, partial-failure, and total-failure conditions.
## 35. Scale Profiles
Synthetic scale profiles:
```text
S0 100
S1 1,000
S2 10,000
S3 100,000
S4 1,000,000
```
These do not all mean “generate that many TypeScript source files”.
### S0-S1
Can exercise concrete module composition and type-check fixtures.
### S2
Exercises larger generated indexes and composition structures when affordable.
### S3-S4
Primarily verify global topology and local-boundary independence. They model one hundred thousand or one million logical features while asserting that any one app/context remains within local budgets.
## 36. Local Scale Verification
Within one allowed boundary, measure:
- registry composition,
- route composition,
- generated index cost,
- TypeScript diagnostics,
- bundle/build cost,
- browser boot cost.
Scale-sensitive composition should exhibit linear-or-better growth where linear work is unavoidable.
Quadratic-like growth is a failure.
> 2026-11-03 현재: 규모 측정(`scripts/scale/run-composition-scale.ts`, `scripts/scale/collect-tsc-diagnostics.ts`)은 registry·route 조립, 생성 색인, TypeScript 진단을 잰다. 번들·빌드 비용과 브라우저 부팅 비용은 이 측정에 없다(§40).
## 37. Global Topology Verification
Increase global logical cardinality while holding one app unchanged.
Assertions:
```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
```
This is the critical proof that the architecture can extend toward 100K/1M logical domains.
> 2026-11-03 현재: `tests/scale/global-local-independence.test.ts`는 생성 색인, 소스 그래프, 부팅 때 읽는 context 루트를 본다. 번들은 `check:app-build-input:bundle`이 "소유하지 않은 기능의 모듈이 없다"만 본다. 부팅 heap·CPU는 재지 않는다.
## 38. TypeScript Scale Gate
Use compiler diagnostics where supported, including `--extendedDiagnostics`.
Track at least:
- source file count,
- type count,
- symbol count,
- instantiations,
- memory,
- total type-check time.
A global module augmentation or giant union that causes unrelated app compile cost to rise with global domain count is a design regression.
## 39. Runtime Composition Scale Gate
Benchmark relevant registries:
- route,
- API operation,
- schema,
- mapper,
- invalidation,
- adapter contribution,
- runtime contribution,
- locale/message contribution.
Test multiple N values to detect nonlinear regression.
Absolute timing alone is insufficient; growth behavior matters.
## 40. Browser Boot Gate
Measure:
- initial JS transferred,
- parsed/executed JS,
- initial route count,
- initial heap,
- bootstrap CPU,
- runtime config fetch,
- release manifest verification,
- first meaningful application render.
Global topology growth must not cause proportional growth in these metrics for an unchanged app.
> 2026-11-03 현재: 이 목록을 재는 부팅 게이트는 없다. 초기 JS gzip 크기만 `check:bundle`이 `config/performance/budgets.json`의 `initialJsGzipBytes`로 막는다. 초기 heap, 부팅 CPU, 첫 렌더, 초기 route 수는 재지 않는다.
## 41. Request Fan-Out Gate
Use representative collection pages with increasing server-returned cardinality:
```text
N = 10
N = 100
N = 1,000
```
A page that requires two bounded bulk requests should remain around that request count instead of issuing O(N) row-detail calls.
> **Implementation note (2026-09-23).** The template's representative collection contract is a paginated bulk read with a hard page ceiling of 100 rows (`limit` ≤ 100, response schema `max(100)`). `N` above is the server-side collection cardinality, not the size of one response. Acceptance is therefore two-layered:
>
> - supported cardinality — collections of N = 10 / 50 / 100 / 1,000 rows load a page with **1** physical request, and a full 1,000-row walk costs ≤ ceil(N / 100) + 1 page requests, never one request per row;
> - oversized response — a single response carrying more than the page ceiling (e.g. 1,000 rows at once) is rejected within **1** request as a contract violation, with no per-row downstream fan-out.
>
> The ceiling is not raised to make an oversized fixture pass. A source gate (`pnpm check:request-fanout`) rejects any request dispatch inside a loop or array-iteration callback in feature/application code.
## 42. Failure and Chaos Scenarios
Required scenarios include:
### Total API failure
Verify:
- retry bound,
- concurrency bound,
- telemetry bound,
- bounded memory,
- no infinite loop,
- no reload loop.
### Partial failure
Example:
```text
Payment 100% failure
Order healthy
Catalog healthy
```
Payment should degrade without collapsing unrelated contexts.
### Slow API
Test long-tail latency. Verify deadlines, cancellation, concurrency queues, and queue limits.
### Network flap
Repeated online/offline transitions must not produce duplicate unsafe mutations or retry bursts.
### Telemetry endpoint failure
Business behavior remains functional and telemetry storage remains bounded.
## 43. Telemetry Storm Test
Generate a large number of identical errors/events.
Expected behavior:
```text
many logical errors
-> fingerprint/dedup/sample
-> bounded number of buffered/sent telemetry events
```
The test records emitted, deduplicated, sampled, dropped, and transmitted counts.
## 44. Soak Testing
Long-session profiles may include 30 minutes, 2 hours, 8 hours, or 24 hours depending on environment cost.
Observe:
- heap size and slope,
- active timers,
- event listeners,
- DOM nodes,
- query cache size,
- telemetry buffer,
- IndexedDB/browser storage,
- stale auth/session leakage.
The primary leak signal is sustained positive growth after expected warm-up stabilization, not only an arbitrary maximum heap value.
> 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. Horizontal Scaling and Release Coherence
Frontend application instances are intended to remain stateless with respect to server-hosted browser user state.
Horizontal scaling is safe only when release coherence is maintained.
Deployment contract:
- content-hashed assets are immutable,
- HTML is revalidated/no-cache according to current release strategy,
- runtime config and release manifest are no-store,
- old hashed assets remain available during rolling release windows,
- a deployment switches an active release tuple atomically,
- mixed incompatible HTML/config/manifest combinations fail closed rather than executing ambiguously.
> 2026-11-03 현재: 불일치를 만나면 세션마다 한 번만 자동으로 다시 불러오고, 그 뒤의 불일치는 실패 화면으로 끝낸다(`src/platform/release/release-mismatch-recovery.ts`). 이 재시도는 원문에 없다.
## 46. Multi-Replica Release Matrix
At minimum verify:
| HTML | Config | Manifest | Asset | Expected |
| --- | --- | --- | --- | --- |
| R10 | R10 | R10 | R10 | PASS |
| R10 | R11 | R10 | R10 | FAIL CLOSED |
| R10 | R10 | R11 | R10 | FAIL CLOSED |
| R10 | R10 | R10 | missing/incompatible | FAIL |
| R11 | R11 | R11 | R11 | PASS |
Rolling deployments must also preserve reachability of previous immutable hashed assets for clients that loaded earlier HTML.
## 47. CI Execution Tiers
Heavy scale tests must not make every pull request unusably expensive.
### Pull request
Fast deterministic gates:
- dependency architecture,
- cardinality budgets,
- unit tests,
- app/test type-check,
- small composition fixtures,
- duplicate collision tests,
- cross-feature dependency fixture,
- small request fan-out fixture.
### Main branch
Medium scale regression:
- 1K/10K synthetic composition where appropriate,
- TypeScript diagnostic comparison,
- route/bootstrap growth checks,
- generated index validation.
### Nightly
Heavy synthetic and browser verification:
- 10K/100K/1M topology model,
- browser memory and route loading,
- telemetry storm,
- failure scenarios,
- longer navigation/session cycles.
### Release / dedicated environment
Environment-dependent checks:
- spike load,
- soak load,
- cache behavior,
- multi-replica mixed-release validation,
- CDN/LB/origin release contract.
> 2026-11-03 현재: CI는 `pr` 단계만 돌린다(FE-GATE-005). `main`·`nightly`·`release`는 로컬 명령이다. 기준선 시간 비교가 그 기준선을 기록한 CPU에서만 성립하기 때문이다(`scripts/scale/run-scale-profile.ts`).
## 48. Benchmark Result Format
Scale results are machine-readable artifacts, not only console output.
Example:
```json
{
"profile": "S2",
"globalLogicalFeatures": 10000,
"localFeatures": 150,
"routeCompositionMs": 3.21,
"typescriptMs": 4312,
"heapBytes": 1234567
}
```
Store enough metadata to compare against a compatible baseline.
> 2026-11-03 현재: 실제 형식은 `scripts/scale/benchmark-result.ts`의 `BenchmarkResult`(`name`·`profile`·`cardinality`·`samples`·`medianMs`·`heapBytes`·`metadata`)와 이를 담는 `BenchmarkArtifact`다. 위 JSON은 예시다.
## 49. Regression Policy
Use three kinds of thresholds:
1. absolute ceiling,
2. relative regression percentage,
3. growth-complexity trend.
Performance measurements should use multiple runs and robust summaries such as median where environment noise is relevant.
Structural failures such as cycles, duplicate IDs, cross-feature concrete imports, or cardinality-budget violations are deterministic and should fail immediately.
## 50. Required Architecture Gates
The architecture must eventually provide automated gates for:
1. cross-feature concrete import prohibition,
2. cross-context concrete import prohibition,
3. cycle prohibition,
4. cardinality budgets,
5. duplicate feature/route/operation/schema IDs,
6. O(N²)-style registry regression,
7. request fan-out regression,
8. retry-budget enforcement,
9. telemetry-buffer boundedness,
10. global-to-local scale independence,
11. TypeScript/build scale regression,
12. multi-replica release coherence.
> 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. Compatibility With Current Template Strengths
This design preserves and extends current strengths rather than replacing them:
- Clean Architecture layer rules,
- capability-driven adapter composition,
- HTTP operation contracts,
- bounded response handling,
- retry/idempotency semantics,
- TanStack Query cache ownership,
- scope fencing/generation behavior,
- release/build/config coherence,
- immutable static asset release model.
The implementation should refactor composition and introduce platform policies without unnecessary UI/design changes.
## 52. Explicit Non-Goals
This design does not require:
- one SPA containing 1M TypeScript features,
- runtime discovery of arbitrary remote code,
- Module Federation or micro-frontends as the default starting point,
- a global mega-registry,
- a global mega-error union,
- a global telemetry schema union,
- vendor-specific observability APIs in feature code,
- frontend validation as a replacement for backend validation.
Remote/micro-frontend deployment can remain an optional future escalation when organizational or deployment boundaries require independent teams/releases. It is not required to solve the current scaling architecture.
## 53. Implementation Sequence Constraints
Implementation should be incremental and preserve behavior.
A safe high-level sequence is:
1. establish deterministic architecture/scale tests around current behavior,
2. remove known O(N²) and repeated-membership composition paths,
3. introduce feature-owned descriptor boundaries,
4. generate static product/context indexes,
5. enforce cross-feature/context dependency rules,
6. introduce hierarchical route composition,
7. introduce cardinality budgets,
8. introduce execution context and traffic budgets,
9. normalize error and validation boundaries,
10. introduce telemetry port/pipeline/budgets,
11. add scale/chaos/soak/release gates by CI tier.
The detailed implementation plan must decompose these into test-first tasks and identify exact existing files after re-reading the live repository state.
## 54. Acceptance Criteria
The design is considered implemented only when all of the following are true:
- Adding a normal feature does not require editing a collection of central handwritten installation registries.
- Composition does not contain known quadratic accumulation patterns.
- Membership checks on scale-sensitive paths use appropriate indexed structures.
- Concrete imports across unrelated features fail architecture checks.
- Context/app cardinality ceilings are explicit and testable.
- An unchanged local app does not grow materially when global logical topology grows toward S3/S4 fixtures.
- Initial routing is hierarchical/lazy rather than a product-wide flat feature table.
- User interactions carry bounded request, retry, concurrency, cancellation, and deadline semantics.
- Representative collections do not create frontend N+1 request fan-out.
- Errors remain local and typed without constructing a global union of all feature errors.
- External data is validated at trust boundaries with bounded payload/structure cost.
- Feature code emits observability through a platform port rather than vendor SDKs.
- Telemetry is redacted, deduplicated, sampled, buffered, and rate-limited with bounded memory.
- Telemetry failure does not fail business behavior.
- Failure boundaries prevent one feature/context from unnecessarily collapsing unrelated UI.
- Spike and sustained-load tests detect request, retry, telemetry, and memory amplification.
- Multi-replica release tests verify fail-closed coherence and old-asset reachability.
## 55. Design Summary
The architecture is based on one rule:
> Global scale must be partitioned into bounded local scale, and every remaining local cardinality must have an explicit budget.
Therefore the platform avoids:
```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
```
This allows the product ecosystem to grow from hundreds toward hundreds of thousands or millions of logical domains without requiring a single browser, TypeScript compiler invocation, router, or runtime registry to directly carry that global cardinality.