문제: src/platform·src/apps·src/contexts의 구조·소유·예산·실행· 텔레메트리 규칙과 코드 주석 "Spec §N"의 근거가 2026-09-23 설계서 하나에만 있다. 그 설계서는 docs/reviews/ 안의 계획 묶음에 들어 있어 README가 복사 뒤 지워도 된다고 한 범위 안이다. 현재 계약 목록 (docs/README.md §1)에는 src/platform을 다루는 문서가 없다. 고른 방법: 설계서를 docs/architecture/scale-architecture.md로 복사한다 (git mv가 아니라 복사라 이력 묶음은 그대로 남는다). 본문 §1~§55는 영어 원문 그대로 두고 절 번호를 바꾸지 않는다. 맨 위에 상태 머리말을 붙인다: 현재 계약인 범위, 출처(커밋 6f6c48e와 원래 경로, git show로 보는 법), 코드와 달라진 곳을 절 끝 "> 2026-11-03 현재:"로 적는 규칙. 절 상태 표는 현재 계약(코드 참조) 41, 현재 계약 10, 기록만 4 (§40·§51·§53·§54), 미확인 0이다. 코드와 다른 18개 절에 차이를 한두 줄로 적었다(예: §4 최상위 domain/ 없음, §11 TrafficBudget에 deadline 없음, §40 부팅 게이트 없음, §47 CI는 pr 단계만). docs/README.md §1의 세부 규칙 목록에 새 문서를 더한다. 버린 대안: 필요한 절만 새로 쓰기. 68곳 넘는 주석의 절 번호 대응표가 필요해지고 원문과 갈라진다. 이력을 지우지 말라고 정책을 바꾸기 (리뷰 5.1절 (c)). 동기화 비용과 문서 섞임이 그대로 남는다. 위험·한계: 절 대조는 각 절을 가리키는 모듈의 타입·머리 주석·테스트 이름을 읽는 수준이다. 동작을 실행해 확인하지 않았다. 원문의 "Status: Design approved…"와 예정 경로 줄은 머리말로 바꿨다. 예정 경로가 없는 파일을 가리켜 verify:documentation의 경로 검사에 걸리기 때문이다. 이 커밋만으로는 코드 주석이 아직 이름 없는 "Spec §N"이다. 다음 커밋이 바꾼다. 검증: - 본문 비교: 원문 §1 이후와 새 문서 §1 이후의 diff에서 지운 줄 0, "> 2026-11-03 현재" 메모 외에 더한 줄 0 - node scripts/verify-documentation-readiness.ts: PASS_SCOPED (처음 "src/domain"을 백틱으로 적어 FAIL, 문구를 고쳐 PASS) - node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts tests/unit/deletable-history-documents.test.ts: 15 passed
43 KiB
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:
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
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:
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.
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
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/reference-feature/domain)에만 있다.src/platform에는execution·release·routing도 있다. 색인은 생성기가 git이 무시하는src/.generated/에 쓴다. 조립 코드는src/bootstrap/에 있고compose-product.ts라는 파일은 없다. 실제 폴더 목록의 정본은layers.md다.
5. Module Ownership
5.1 Feature module
Each feature owns one descriptor containing its own contributions.
Conceptual API:
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:
src/features/new-feature/**
.generated/**
Central handwritten production files changed for a normal feature addition:
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.
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.
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:
src/features/A/** -> src/features/B/**
is an architecture violation unless the dependency is through an explicitly approved public contract boundary.
Preferred interaction boundaries:
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:
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:
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:
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.
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:
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:
Product Router
-> Deployable App Router
-> Context Router
-> Feature Router
-> Page Route
Only the next boundary is loaded eagerly.
Example at global scale:
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:
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
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:
interface TrafficBudget {
readonly maxPhysicalRequests: number;
readonly maxConcurrentRequests: number;
readonly maxRetries: number;
readonly deadlineMs: number;
}
A feature owns the policy declaration; the platform owns enforcement.
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:
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.
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:
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.
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.
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:
type PaymentError =
| PaymentDeclined
| PaymentAlreadyProcessed
| PaymentLimitExceeded;
17.4 No global error union
This is forbidden:
type GlobalApplicationError =
| OrderError
| PaymentError
| ...;
Use local generic boundaries instead:
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:
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:
if (status === 409) { ... }
Preferred flow:
HTTP 409
-> Transport/Contract interpretation
-> PaymentAlreadyProcessed
-> localized presentation message
20. Validation Boundaries
Validation has distinct purposes:
- user-input validation,
- transport validation,
- domain invariant validation,
- 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.
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:
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:
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.
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.
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.
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:
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
physical HTTP requests / logical interactions
34.2 Retry amplification
total physical attempts / initial physical requests
34.3 Telemetry amplification
telemetry sends / logical failures or events
These are measured under healthy, slow, partial-failure, and total-failure conditions.
35. Scale Profiles
Synthetic scale profiles:
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:
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:
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 schemamax(100)).Nabove 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:
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:
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:
{
"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:
- absolute ceiling,
- relative regression percentage,
- 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:
- cross-feature concrete import prohibition,
- cross-context concrete import prohibition,
- cycle prohibition,
- cardinality budgets,
- duplicate feature/route/operation/schema IDs,
- O(N²)-style registry regression,
- request fan-out regression,
- retry-budget enforcement,
- telemetry-buffer boundedness,
- global-to-local scale independence,
- TypeScript/build scale regression,
- 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:
- establish deterministic architecture/scale tests around current behavior,
- remove known O(N²) and repeated-membership composition paths,
- introduce feature-owned descriptor boundaries,
- generate static product/context indexes,
- enforce cross-feature/context dependency rules,
- introduce hierarchical route composition,
- introduce cardinality budgets,
- introduce execution context and traffic budgets,
- normalize error and validation boundaries,
- introduce telemetry port/pipeline/budgets,
- 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:
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.