문제
lab 게이트 FE-GATE-026은 내비게이션 클릭부터 플랫폼 구성 화면 제목이
보일 때까지를 잰다. 298201f 뒤로 이 route module은 그리기 전에
loadInstalledFeatureRuntimeRegistries()를 기다린다. 그 함수는 설치된
모든 기능의 실행부를 dynamic import한다. 그래서 클릭 뒤 요청 묶음이
두 번이 되고 상호작용 중앙값이 117 -> 227 ms가 됐다(예산 200 ms).
고른 방법 (영역 문서 최소 개선 방향 (c))
- route module은 페이지 컴포넌트를 바로 돌려준다(default export).
제목·릴리스·라우트 표·서버 상태·능력·기능 상태처럼 선언과 런타임
snapshot으로 아는 것은 바로 그린다.
- 실행부가 있어야 아는 것(HTTP 오퍼레이션 수, 픽스처 수, 오퍼레이션
표, 검증 생략 표)만 Suspense 경계 두 곳 뒤에서 use()로 채운다.
- 실행부 조립 모듈도 dynamic import로 바꿔 제목이 기다리는 페이지
청크에서 뺐다(첫 요청 묶음 8,095 -> 6,919 B).
- 기능 사이 중복은 여전히 이 화면에서 throw하고 route 경계로 간다.
실패한 load는 캐시에서 지워 다음 방문 때 다시 시도한다.
- 버린 대안: 예산 300 ms(회귀를 숨김), lab 대상 라우트 변경(같은
이유), hover 프리페치(키보드·직접 진입에 효과 작음).
위험·한계
- 화면 안에 "기능 실행부를 불러오고 있습니다." 로딩 상태가 생긴다.
- PlatformOverviewPage의 contracts prop이 Promise가 됐다. 이 컴포넌트를
직접 쓰는 다운스트림 테스트는 Promise를 넘기고 act로 기다려야 한다.
- 첫 요청 묶음은 d99301b보다 여전히 크다(6,919 vs 5,019 B). 그 사이
페이지가 커졌고 badge·card가 공유 청크로 갈라졌다. 그래서 d99301b보다
약 30 ms 느리다.
- 실제 CI 러너에서는 재지 않았다.
검증
- 새 component 테스트(실행부 load가 끝나지 않아도 제목·라우트 표가
보이고 오퍼레이션 표만 로딩): 수정 전 실패, 수정 뒤 통과.
- test:component 통과. check:types, check:architecture, 바뀐 파일
eslint 통과.
- lab A/B(heavy lock, 같은 호스트, d99301b worktree와 번갈아,
test:performance --runs=5, CHOKIDAR_USEPOLLING=1, 이 브랜치 끝 기준):
부하 19 -> 11에서 d99301b 107·106 ms PASS, 이 변경 136·134 ms PASS.
LCP 1,968·1,984 ms, CLS 0. (같은 날 다른 묶음 한 번은 두 쪽 모두
홈 링크를 30초 안에 찾지 못해 측정 전에 끝났다. 포트를 바꿔 다시
잰 것이 위 결과다.)
- 요청 추적: 클릭 뒤 제목은 첫 묶음(페이지 청크 4개) 뒤에 나오고,
feature-runtime·reference-schemas는 제목 뒤에 받는다.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-01
13 KiB
Frontend Application Foundation
This repository is not treated as a minimal React project template and it is not an independent general-purpose SDK. Its architectural role is:
Frontend Application Foundation = Starter / Composition Skeleton + Reusable Capability Platform
The starter side owns bootstrap, routing, providers, project conventions and a removable reference feature. The capability side owns reusable technical problems such as HTTP execution, Server State, authentication boundaries, IndexedDB/OPFS, Cache Storage, realtime, browser RPC, transfer and diagnostics.
The cost of a sophisticated capability is acceptable only when product features do not have to understand that internal sophistication.
Hybrid architecture
src/ has nine top-level folders. The descriptions match the table in
the layer contract, which also names every import rule.
Platform code is horizontal:
src/bootstrap— the composition root: runtime configuration, concrete adapter construction and the React mountsrc/presentation— generic UI and the inbound adapter: routes, layouts, the design system, pages and providerssrc/adapters— reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and moresrc/application— generic use cases, ports, policies and view-modelssrc/contracts— shared vocabulary and registries read by several layers, the workers and the build and release scriptssrc/platform— product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence
Ownership declarations group features into deployable units:
src/apps— deployable apps: eachapp-module.tsdeclares an app and its context budget;template-app.tsis the app this build producessrc/contexts— bounded contexts: eachcontext-module.tsdeclares its app, route root and feature budget
Product business code is vertical:
src/features— removable vertical slices (src/features/<id>/{domain,application,contracts,adapters,presentation}) and the installed-feature catalogs (src/features/*.ts)
Inside one feature:
features/<feature>/domainfeatures/<feature>/applicationfeatures/<feature>/contractsfeatures/<feature>/adaptersfeatures/<feature>/presentation
The dependency model is:
Domain / Use case
|
| owns
v
Business port
^
| implements / binds
|
Feature-owned adapter binding
|
| generic type + mapper/codec + policy
v
Reusable capability runtime
|
v
Browser / network / native API
A use case never imports a platform adapter. Generic binding happens in the feature adapter/composition seam.
Capability-specific typed bindings
Do not introduce one universal Repository<TKey, TValue> abstraction for HTTP,
storage, realtime and transfer. Their lifecycle and failure semantics differ.
A reusable capability boundary is composed from:
- generic input/output types,
- feature-owned mapper or codec,
- feature-selected policy,
- one capability-specific runtime.
The HTTP reference path is the first concrete example.
src/adapters/http/feature-http-binding.ts owns transport/outcome
normalization. The reference feature contributes only:
- operation ID,
- route ID,
- exact request input type,
- exact success value type,
- wire-to-domain mapper.
The feature gateway therefore does not reimplement timeout, cancellation, transport failure, authentication failure or contract-violation projection.
Storage, realtime and transfer may gain their own typed binders only after actual feature repetition demonstrates the need. They must not be forced through the HTTP abstraction.
Custom adapter escape hatch
A product feature uses a reusable capability when the capability preserves the business requirement.
If a platform contract would require changing or weakening the business model, the feature implements a custom outbound adapter behind the same application port. The architecture boundary remains stable; platform reuse is optional.
Feature installation
A feature owns its contract, runtime and adapter contributions.
Central installed catalogs are aggregation points only:
installed-product-manifest.ts: which product features are compiled/selectedinstalled-feature-contracts.ts: boot-time contract aggregation (routes, route runtime contracts, invalidation) from the feature declarationsinstalled-feature-adapters.ts: application-input loaders, one per active feature, run when the router enters the feature's routes (15-01)installed-contract-contributions.ts: declared contract packages and the registry the HTTP executor resolves against, filled as features loadinstalled-feature-runtime-registries.ts: loads every runtime half and composes the V2 API registries and contract contributions; the platform overview page calls it after it draws its title (1103/15-01), the boot never doesloaded-feature-runtimes.ts: the same registries as module constants (top- level await) for Node scripts, tests and registry governance; nothing undersrcmay import it (boot-does-not-load-every-feature-runtime)
Feature-specific composition belongs under the feature itself. Central catalogs must not grow feature-specific branching logic.
Adapter contributions declare the platform capabilities they consume through
needs. The generic contribution seam in
src/features/feature-adapter-contribution.ts derives the context from that
list, so an HTTP-only feature cannot reach IndexedDB and an IndexedDB-only
feature does not receive the HTTP executor. It also binds
featureId -> ApplicationFeatureInputs[featureId] at the contribution
definition site instead of recovering that relationship with a final catalog
cast.
A contribution becomes composable only through
defineFeatureAdapterContribution(). That factory adds the private
contribution brand required by composeFeatureAdapterInputs(); a raw object
with the same visible fields is rejected by TypeScript and checked again at
runtime. The negative type fixture
invalid-direct-feature-composition.ts is part of FE-GATE-003 so this
authority cannot be bypassed by calling the composer directly.
For IndexedDB-backed features, createIndexedDbRepositoryProvider() is the
composition helper that maps feature-owned repository identities to typed
IndexedDbRepositoryPort instances. It does not create a universal storage
repository or move dataset/migration/lifecycle policy into the feature.
The repository now has two executable contribution shapes:
- Reference feature:
needs: ["http"] - Local Draft feature:
needs: ["indexedDb"]
Local Draft is a compiled architecture consumer used to prove the second
capability shape; it is not added to the default product manifest. Its
browser-capability test composes the feature over the real
createIndexedDbRuntime and native IndexedDB, proving that this seam is not
limited to an in-memory contract fixture.
The bootstrap does not build indexedDb: IndexedDB is an opt-in reference
runtime (productionComposition: false in
config/recipes/frontend-capability-recipes.json). The composition example is
recipes/frontend-capabilities/indexeddb-feature-capability.ts
(createLocalDraftIndexedDbCapability, exercised by
tests/recipes/indexeddb-feature-capability.test.ts). A product that installs a
feature with needs: ["indexedDb"] copies it and returns indexedDb from the
product-owned src/bootstrap/product-composition.ts. Until it does, the feature
capabilities in src/bootstrap/runtime-adapters.ts fail the app typecheck, and
composeFeatureAdapterInputs() rejects the composition with
feature <id> needs indexedDb, which the host did not provide.
The same file is where a product adds any other capability (it augments
FeaturePlatformCapabilities) and the credential provider for a product auth
profile. The composition root keeps the order: scope fence, ANONYMOUS
profile, product provider, session, scope fence again
(tests/unit/runtime-adapters-credential-order.test.ts). A product that owns
the session itself (a BFF whose session is an httpOnly cookie) returns its
session owner from composeProductSessionOwner in the same file. It is asked
first, before http exists, only when AUTH_MODE is external, and it comes
before the host's __CA_FRONTEND_AUTH_OWNER__; null leaves the session to
that global. Product auth profiles, runtime-config keys and the keys'
FE-REG-ENV rows go in src/contracts/product-contracts.ts; each joins the
template's registry under the same checks
(tests/unit/product-composition-fixture.test.ts).
Presentation consumer surface
ApplicationProvider remains the composition root for presentation, but new
consumers should not navigate a root ApplicationApi service locator.
Use the narrow hooks in
src/presentation/providers/application-provider.tsx:
useApplicationSessionuseApplicationPreferencesuseApplicationDiagnosticsuseApplicationRuntimeuseApplicationRecoveryuseApplicationFeature
useApplication exists only as a deprecated compatibility escape hatch.
Canonical imports
New feature code should use capability public entry points rather than deep
runtime modules. For HTTP the canonical path is
src/adapters/http/index.ts.
Compatibility re-exports may exist during a migration window, but they must be marked as compatibility/deprecated paths and should not expand into an unbounded public barrel.
Policy ownership
Duplication is judged by ownership, not by syntax percentage.
Small local validators can remain duplicated when locality improves auditing.
Business or concurrency policy must have one owner. For example the reference
create mutation keeps definition ID, idempotency requirement, duplicate policy
and invalidation policy in one feature-owned definition and binds only
scope and execute per usage site.
Runtime decomposition rule
Large runtime files are not split by line count.
Extract a boundary when it has its own state machine, lifecycle owner, failure model or compensation/recovery responsibility. Candidate seams include:
- connection/open/upgrade lifecycle,
- transaction ownership,
- migration state machine,
- reconnect/backoff and heartbeat,
- subscription ownership,
- retry/deadline/cancellation ownership,
- settlement/reconciliation/cleanup.
A cohesive 2,000-line state machine can remain together. A 300-line file with multiple lifecycle owners is a better extraction candidate.
Current runtime boundary audit
The current large-runtime inventory was reviewed using that rule.
- IndexedDB remains large, but connection, transaction, migration, maintenance and failure translation already have separate owners/modules.
- resumable upload already separates runtime policy, checkpoint persistence, HTTP control-plane transport, part execution, cancellation and mutation locking.
- realtime already separates reconnect policy/coordinator, event codec/consumer and stream coordination.
- OPFS is separated into browser runtime, journal, byte-store, policy and worker protocol/runtime responsibilities.
- HTTP V3 still owned retry eligibility/backoff inside the execution state
machine, so that responsibility moved to
src/adapters/http/http-retry-lifecycle.ts.
No other runtime is split merely because of its line count.
Consumer quality metrics
Before adding another abstraction, implement or model multiple real feature uses and measure:
- feature-owned adapter LOC,
- repeated platform glue,
- number of platform-internal types exposed to the feature,
- central catalog edits,
- files changed for one normal query/command,
- whether native browser/network APIs leak into the feature.
The target feature-development path is:
- domain type and invariant,
- use case,
- port,
- transport/storage schema plus mapper/codec,
- capability binding,
- presentation controller/page.
A product feature should not need to know the retry scheduler, abort ownership, effect-certainty machinery, transaction leases, reconnect coordinator, OPFS journal or provider lifecycle.
The executable REST and IndexedDB consumer baselines are recorded in
capability-consumer-experience.md.
Contract placement and the global-vs-owner-local audit are recorded in
contract-ownership.md.
Verification paths
Product-development verification, capability verification and release assurance
are intentionally separate. See
docs/testing/taxonomy.md.
Host-level CI-runner tests belong to tests/system, not tests/unit.
Reusable capability consumer contracts belong to tests/contract.