Files
clean-architecture-frontend…/docs/architecture/starter-experience.md
T
DongHyeonka b96d61d8f7 feat(examples)!: 예제 화면 3개를 끌 수 있는 기능으로 옮긴다
문제
/examples/ui, /examples/states, /examples/auth(와 /examples/platform)는
플랫폼 라우트 레지스트리에 고정이었다. VITE_PRODUCT_FEATURES와
FEATURE_OVERRIDES는 기능만 빼므로 제품은 이 화면을 끌 수 없었다.
릴리스 게이트 FE-GATE-028은 ROUTE_REGISTRY의 모든 라우트에 서명된
수동 접근성 기록을 요구해서, 제품은 템플릿 갤러리를 운영 메뉴에 두고
서명하거나 템플릿 파일 5개와 src/presentation/examples/를 지워야 했다.

고른 방법
- UI 갤러리·화면 상태·인증 연동을 platform-examples-feature로 옮겼다.
  자기 context platform-examples-context(루트 examples/*)에 산다.
  reference-context의 examples/reference-resources/*와 플랫폼 라우트
  /examples/platform이 더 구체적이라 그 URL은 그대로 간다.
- 라우트 ID·경로·청크 ID·표면은 바꾸지 않았다. 시각·e2e 테스트와 a11y
  기록(artifacts/tests/a11y-manual/EXAMPLES_*.md)이 그대로 이 이름을
  쓴다. 기능을 빼면 a11y 목록은 ROUTE_REGISTRY에서 오므로 같이 빠진다.
- 실행부는 비어 있다(스키마·adapter·계약 기여 없음). 페이지는 context
  routes에서 페이지마다 lazy로 받는다.
- 플랫폼 구성 화면(EXAMPLES_PLATFORM)은 플랫폼 라우트로 남겼다. 처음에는
  같이 옮겼다. 같은 호스트·같은 부하(15~19)에서 d99301b와 번갈아 잰
  lab이 기능 라우트로는 443·432 ms FAIL이었다(d99301b 133·183 ms
  PASS). 기능 라우트의 첫 진입은 context routes 모듈을 받은 뒤에 페이지
  청크를 받는다(요청 추적: 939 B + 177 B 다음에 5,183 B + 3개). 페이지를
  routes 모듈에 정적으로 넣으면 릴리스 매니페스트의 routeChunks 계약
  (페이지마다 dynamic entry)이 깨진다. 15-01의 "예산을 올리지 않는다"를
  지키려고 이 한 화면은 남겼다.
- 홈 화면은 예제 라우트 ID를 적지 않는다. 내비게이션의 처음 세 화면을
  "{title} 보기"로 보여 준다. 템플릿에서는 예전과 같은 세 링크(플랫폼
  구성·UI 구성요소·화면 상태)가 나오고, 예제를 뺀 제품에서는 그 제품의
  화면이 나온다. home.starter.platform·ui·states 키를 home.starter.open
  하나로 바꿨다. VITE_PRODUCT_FEATURES=none 빌드 검사
  (product-feature-selection-build)가 홈 청크의 예제 라우트 ID를 잡았다.
- 예제 화면 component 테스트는 tests/features/platform-examples-feature/로
  옮겼다. 제거 드릴이 같이 지운다. runtime-adapters 테스트는 API가 있는
  기능만 센다(예제 기능은 API가 없다). context-route-roots 테스트의
  "플랫폼 라우트와 같은 경로" 예는 /examples/platform으로 바꿨다.
- old-tab-chunk-recovery e2e는 페이지 소스를 빌드 A의 Vite manifest에서
  찾는다(기능 폴더 이름을 적지 않음). UI 갤러리가 기능 라우트라 B 탭이
  잃는 청크는 그 context routes 모듈이다. 허용 패턴에 넣었다.
- 예제 화면 문구는 08-07대로 한국어 고정이다. 화면 문구 ESLint 규칙의
  예외에 새 폴더를 넣었다.
- 버린 대안: 빌드 변수로 숨김(선택 장치가 하나 더 생김), 예제 화면만
  제품이 지우게 둠(동기화 충돌 자리가 남음).

위험·한계
- 공개 경로가 바뀌었다. src/presentation/examples/{ui-gallery,
  state-gallery,auth-example}-page.tsx, PLATFORM_ROUTE_REGISTRY·
  PLATFORM_ROUTE_RUNTIME(_CONTRACT)의 EXAMPLES_UI·STATES·AUTH,
  home.starter.platform/ui/states 키를 쓰던 다운스트림은 깨진다.
- 플랫폼 구성 화면은 여전히 끌 수 없고 FE-GATE-028 서명 대상이다.
- tests/e2e와 tests/visual의 여러 spec이 예제 화면을 자기 페이지로 쓴다.
  예제를 뺀 제품은 그 spec을 자기 화면으로 바꾸거나 지워야 한다
  (starter-experience.md에 적음). 제거 드릴은 브라우저 테스트를 돌리지
  않아 이것을 보지 않는다.
- 예제 기능 제거 드릴은 16-02(빈 ciScripts로 CI 기준선 사유가 공백)
  때문에 그대로는 시작하자마자 실패한다. 아래 드릴 결과는 그 한 줄을
  임시로 고친 상태에서 낸 것이다(커밋하지 않음).
- 기능 라우트 첫 진입이 이 lab 조건에서 약 430 ms라는 것은 어느 게이트도
  재지 않는다.

검증
- product-feature-selection-build(VITE_PRODUCT_FEATURES=none 빌드):
  홈 청크의 예제 라우트 ID 3건으로 실패한 것을 확인하고 홈 화면을 고친
  뒤 통과.
- test:sample-removal -- --feature=platform-examples-feature(heavy lock,
  16-02 한 줄 임시 패치): PASS, 13 checks(typecheck, architecture,
  registries, test:all, coverage, test-evidence, ci, home-smoke, build,
  route-absent, 잔여 ID 0). 첫 시도에서는 lab-performance 단위 테스트가
  측정 라우트 조회가 포트 검사보다 먼저여서 실패했다(그 뒤 이 변경에서
  측정 라우트를 플랫폼에 남겨 조회 변경 자체를 뺐다).
- test:unit 2,587, test:component 253, tests/features·platform·
  architecture 383 통과. check:types, lint, check:architecture,
  check:i18n, check:registries(additive), verify:documentation 통과.
- test:e2e 세 엔진 187 passed, 3 skipped(Firefox SW quarantine).
  old-tab-chunk-recovery 포함. test:a11y 60 passed.
- build + check:bundle: 초기 JS 201,940 / 204,800 B(+92 B).
- lab(측정 라우트를 기능으로 옮긴 시도): 443·432 ms FAIL, 같은 묶음
  d99301b 133·183 ms PASS(부하 15~19). 남긴 뒤 136·134 ms PASS.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-04
BREAKING CHANGE: 예제 라우트 EXAMPLES_UI·EXAMPLES_STATES·EXAMPLES_AUTH가
플랫폼 레지스트리에서 platform-examples-feature로 옮겨졌다. 페이지 파일은
src/features/platform-examples-feature/presentation/으로 갔고,
PLATFORM_ROUTE_REGISTRY·PLATFORM_ROUTE_RUNTIME_CONTRACT·
PLATFORM_ROUTE_RUNTIME에 이 키들이 없다. 홈 문구 키
home.starter.platform·ui·states는 home.starter.open({title})로 바뀌었다.
예제를 지운 다운스트림은 이 기능 폴더와 context를 지우면 된다.
2026-11-04 22:59:03 +09:00

17 KiB

Starter experience contract

The repository provides a runnable, domain-neutral application rather than only infrastructure contracts. The starter experience is intentionally replaceable at the page level while the shell, providers, boundaries, primitives, and state surfaces remain reusable.

Runtime composition

validated config + coherent release manifest
  -> concrete adapters
  -> QueryClientProvider
  -> ApplicationProvider
  -> RouterProvider
  -> ThemeProvider
  -> SessionProvider
  -> AppShell
  -> lazy route boundary

Boot stops before product mount when configuration or release coherence fails. Each lazy page renders inside Suspense and a telemetry-aware route boundary. Route changes move focus to the new page heading; the skip link and landmarks remain stable in the shell.

Registered routes

The route list is ROUTE_REGISTRY (src/features/installed-feature-contracts.ts): the platform routes of src/contracts/routes.ts plus the routes of every installed feature. The platform overview page (/examples/platform) shows the composed list at runtime, so this document does not keep a copy of it.

Navigation labels and order come from ROUTE_REGISTRY; the sidebar does not maintain a second route list. The client access decision never claims to be authorization.

Authentication seam

The session port exposes state subscription, sign-in start, sign-out, credential attachment, recovery, and unauthenticated notification. Credentials remain opaque to the application and presentation layers.

  • demo: local/development-only state transition with no credentials
  • external: delegates to globalThis.__CA_FRONTEND_AUTH_OWNER__
  • missing/invalid external owner: fails closed as integration-failed

An external owner implements readState, readSubject, subscribe, beginSignIn, signOut, attachCredential, recoverSession, and notifyUnauthenticated. It owns token acquisition and storage. An owner that lacks any of these methods is rejected, and the session fails closed as integration-failed.

readSubject() is required. The server-state cache is cleared only when the session state or the subject changes, so a token refresh for the same user keeps cached data. readSubject() must return:

  • an opaque, non-empty string that stays the same for one user across token refreshes and differs between users: the OIDC sub claim, Supabase session.user.id, or Firebase user.uid
  • null when nobody is signed in
  • never an access token, refresh token, or any other credential

If readSubject() returns null or "" while the owner reports authenticated, the runtime cannot tell a refresh from an account switch. It fails closed: every such notification clears server state, and each one records the cache.operation.failed diagnostic with operation: SCOPE_FENCE and reason: SUBJECT_MISSING. Seeing that diagnostic means the owner is not reporting its subject. The demo adapter reports one fixed demo user as its subject.

Migration: readSubject() used to be optional. An owner written for an earlier release must add it; without it the owner is rejected at startup (the session becomes integration-failed) and a TypeScript owner no longer compiles against ExternalSessionOwner. A code path that implements AuthSessionPort or SessionGateway directly must add getSubject() the same way.

Extending the starter

New platform work should follow routing, page templates, and reusable patterns and the TypeScript, state, and data-flow target rather than adding another independent route or data-loading convention.

Replacing the starter screens

/ (src/presentation/pages/home-page.tsx) is the platform's APP_HOME; a feature takes it over by declaring that route id (see "Product home and layouts"). Its starter links are the first three screens of the navigation.

The example screens /examples/ui, /examples/states and /examples/auth are one feature, src/features/platform-examples-feature/, in its own context src/contexts/platform-examples-context/ (1103/09-04). A product turns them off like any feature: leave the id out of VITE_PRODUCT_FEATURES, or remove it with corepack pnpm test:sample-removal -- --feature=platform-examples-feature as the drill. Their routes then leave the registry, the navigation, the bundle and the manual accessibility list (FE-GATE-028). Their component tests are in tests/features/platform-examples-feature/ and go with them.

The platform overview (/examples/platform, src/presentation/examples/platform-overview-page.tsx) stays a platform route. It describes the installed registries, and the lab gate (FE-GATE-026) times entering it: a feature route's first entry also loads its context's routes module before the page, a second request round the 200 ms budget does not fit. Its tests are the tests/component/starter-*.test.tsx files.

The platform's component tests (router, boundaries, shell, runtime tree) run on the pages of the test-only feature in tests/helpers/fixture-feature.tsx and keep passing without the examples. The browser-level checks in tests/e2e and tests/visual use the example screens as their pages and run where the examples are installed: a product that leaves them out points those specs at its own screens or deletes them.

Ownership declarations

Features, contexts and apps are discovered by scripts/generate-product-feature-index.ts. Each boundary declares only its parent, as exported string or integer literals the generator reads:

File Exports
src/apps/<app>/app-module.ts APP_MODULE_ID, APP_MAX_CONTEXTS
src/contexts/<context>/context-module.ts CONTEXT_MODULE_ID, CONTEXT_APP_ID, CONTEXT_ROUTE_PATH, CONTEXT_MAX_FEATURES
src/features/<feature>/feature-module.ts FEATURE_MODULE_ID, FEATURE_CONTEXT_ID, FEATURE_MODULE
src/features/<feature>/feature-runtime.ts FEATURE_RUNTIME (imported only by feature-module.ts, dynamically)
src/features/<feature>/context-routes.ts FEATURE_CONTEXT_ROUTES
src/contexts/<context>/context-layout.tsx (optional) CONTEXT_LAYOUT, the context's own layout ("Product home and layouts")

The generator writes src/.generated/ (git-ignored): the feature index the installed catalogs import, the context index the router loads lazily, and the selected app. Every build and check script runs it first; run it yourself with corepack pnpm generate:feature-index. It fails, naming the file, when:

  • a directory under src/features/ has no feature-module.ts and no NOT_INSTALLED marker file (src/features/local-draft-feature/NOT_INSTALLED is the one intentional example);
  • a feature names an undeclared context, or a context an undeclared app;
  • a context or app exceeds its declared budget;
  • VITE_PRODUCT_FEATURES names a feature the app does not declare. The variable narrows the installed set here, before anything is compiled.

Adding a feature

  1. Create src/features/<feature>/feature-module.ts. Build FEATURE_MODULE with defineFeatureModule (src/features/feature-module.ts). This is the feature's declaration, and it is in the initial chunk, so it holds data only: the declaration contract (routes, route runtime contracts, invalidation, topic versions and the external contractPackages the release manifest is checked against at boot), its message catalogs, and loadRuntime, which imports feature-runtime.ts dynamically. src/features/reference-feature/feature-module.ts is the complete example.
  2. Create src/features/<feature>/feature-runtime.ts with defineFeatureRuntime: the API contract (operations, schema metadata, runtime schemas, mappers), the adapter contributions (defineFeatureAdapterContribution, with needs naming the platform capabilities it receives) and the contract contributions. The router loads it (application.features.load) when one of the feature's routes is entered. Do not import it statically from anywhere: each feature would add its whole executable code to the initial chunk again, about 3.9 KB gzip (tests/unit/feature-shape-growth.test.ts bounds one feature at 1 KiB). An HTTP API is written once, as its contract contribution descriptor: it executes, and check:registries governs the FE-REG-API row projected from it (projectApiOperationRows in src/contracts/api-operations.ts). A product feature's contract contribution uses an EXTERNAL_PACKAGE source. TEMPLATE_FIXTURE belongs to reference-feature only and never joins the release contract set; the composer rejects it anywhere else.
  3. Create src/features/<feature>/context-routes.ts exporting FEATURE_CONTEXT_ROUTES. Page components are imported lazily here, and each route handle carries the route's params/search codecs; the owning context loads this file only when its route root is visited (src/features/reference-feature/context-routes.ts). Each handle's routeId must be a route of a feature contract in the same context; the context refuses the routes when they load, naming the route, context and features (src/contexts/bounded-context-module.ts).
  4. Name the owning context in FEATURE_CONTEXT_ID. Use an existing context or add src/contexts/<context>/context-module.ts owned by the app. Every route path in the feature contract must sit at or under that context's CONTEXT_ROUTE_PATH and must not fall under another context's identical or more specific root: the router renders feature routes only inside the owning context. No platform route may answer it either: the router tries AppShell's platform routes first, so the same path as a platform route, / under an id other than APP_HOME, or a * root without a layout (the not-found route takes every URL) never renders the feature. The app module refuses anything else when it loads, naming the route, feature and context (src/apps/deployable-app-module.ts). A route that takes over the platform home is the exception ("Product home and layouts").
  5. If the feature has application input, augment ApplicationFeatureInputs from the feature (src/features/local-draft-feature/application/local-draft-api.ts).
  6. Run corepack pnpm check:architecture, corepack pnpm check:types, corepack pnpm check:registries and the tests. tests/unit/two-feature-install-typecheck.test.ts keeps the installed catalogs compiling with more than one feature.
  7. Run corepack pnpm test:sample-removal -- --feature=<feature id> to prove the product still builds and passes its gates without the feature.

Files outside the feature directory. Everything else a feature needs is in src/features/<feature>/ and tests/features/<feature>/.

File When What fails without it
src/.generated/* never by hand: every build and check script regenerates it —
src/contexts/<context>/context-module.ts the feature needs a new context generate:feature-index: Feature <id> belongs to undeclared context <context>
src/contexts/<context>/context-layout.tsx the context needs its own frame instead of AppShell (see "Product home and layouts" below) nothing: without it the context renders in AppShell
artifacts/tests/a11y-manual/<ROUTE_ID>.md every route the feature adds. Copy a record and reset it to Status: pending-manual-review test:unit (tests/unit/manual-a11y-evidence.test.ts), verify:documentation (names the route IDs) and FE-GATE-009 (review:a11y-manual -- --format-only). FE-GATE-028 requires the signed review at release
tests/e2e/accessibility.spec.ts never per feature (1103/16-03): it fills every path parameter with one value and answers each API request from the installed descriptor, a list read with an empty list in its responseEnvelope frame. Edit it only for a protected page that sends something other than an installed GET before it renders test:a11y (FE-GATE-009): a request no installed GET declares fails the route; so does an alert box (role="alert") on a page that read only lists
src/bootstrap/product-composition.ts (product-owned) needs names a capability the template does not build: augment FeaturePlatformCapabilities and return the capability here. indexedDb is built as in recipes/frontend-capabilities/indexeddb-feature-capability.ts. Credentials for a product auth profile are returned here too. A product that owns the session (a BFF's httpOnly cookie) returns its session owner from composeProductSessionOwner instead of installing it on the host global before boot check:types; at runtime feature <id> needs <capability>, which the host did not provide. Without the session owner, AUTH_MODE: "external" boots with the session integration-failed
src/contracts/product-contracts.ts (product-owned) a product auth profile, or a product runtime-config key and its FE-REG-ENV row (PRODUCT_ENV_REGISTRY) auth profile: every gate that loads the operation, with REST security profiles are incoherent for <operationId>: unknown authProfileId …. Config key: check:types where it is read. FE-REG-ENV row: check:registries checks its fields; nothing requires the row
config/runtime/<profile>.json optional: a FEATURE_OVERRIDES entry switches the feature off nothing
package.json, the lockfile, config/security/dependency-change-evidence.json the contract contribution imports a generated @org-contracts/* package as a production dependency generate:supply-chain (in check:bundle): high-risk dependency missing review: add:<package>

The central catalogs (src/features/installed-*.ts) and the registry governance file do not change: consumer directories there are globs over every feature (src/features/*/adapters, config/contracts/registry-governance.json). A route's params/search schema ids are checked against the schemas the feature registers, and its loadingSurface only has to be a kebab-case name, so a route with its own schema and loading surface needs no governance edit either. The registry baseline does not change either. New routes, API operations, schemas and invalidation topics, namespaces and edges are additive registry changes; update:registry-baseline or breaking evidence is needed only to remove or change a row or graph item. tests/unit/second-api-feature-registries.test.ts adds such a feature (an API operation, a route with its own search schema and loading surface, and an invalidation topic) to a copy of the repository and runs check:registries on it.

Schema, operation, mapper, route and chunk ids and invalidation topics are global. Prefix them with the feature; NoRequest already belongs to the sample. MSW scenarios for the feature's own operations come from createHttpScenarioHandler (tests/mocks/handlers/http-scenarios.ts) with the feature's installed contract; the shared scenario catalog does not change.

Product home and layouts

A product whose home is a feature screen, or whose screens use a frame other than AppShell, declares it. The router and the catalogs do not change.

  • Home. A feature takes over the platform home by declaring a route with the id APP_HOME in its contract. The platform names the routes a feature may take over (FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS in src/contracts/routes.ts); any other platform route id is still a duplicate. Two features declaring APP_HOME fail when the catalogs load, naming both. The router mounts the route at its own path with the owning context, whatever that context's route root. Leaving the feature out of the build (VITE_PRODUCT_FEATURES) brings the platform home back; switching it off at runtime shows the disabled-feature page at its path.
  • Layout. A context with src/contexts/<context>/context-layout.tsx exporting CONTEXT_LAYOUT (a component) renders under that layout instead of AppShell. The generated index loads the file lazily, when one of the context's routes is entered. The router mounts the context at each registered path of its features under the layout, so an unknown URL still gets the not-found page in AppShell. Contexts whose layout files export the same component keep one layout instance when the user moves between them, so several route roots can share a layout.
  • Accessibility. The layout renders a skip link to #main-content and exactly one <main id="main-content" tabIndex={-1}> around <Outlet />. The router moves focus there on every route change. Layout routes are siblings of AppShell, never inside it. tests/component/layout-landmarks.test.tsx renders AppShell and the layout of every installed context and fails one without them.
  • Failures. A layout chunk a deploy removed gets the reload-once recovery of a route chunk. Route and feature boundaries work as they do in AppShell.
  • The route root rule of step 4 spans every layout: a root takes the URLs under it whichever layout either context has.

tests/component/context-layouts.test.tsx installs a product declared this way (tests/helpers/fixture-layout-product.tsx).

Before shipping

  • Use the semantic tokens, UI primitives, and state surfaces before adding a project-specific variant.
  • Add component behavior, all-engine E2E, automated axe, and signed manual route evidence.

Theme preference is the public COLOR_SCHEME storage contract. Authentication tokens and other secrets remain forbidden storage keys.