Files
clean-architecture-frontend…/docs/architecture/starter-experience.md
T
DongHyeonka ca74caa2a8 test(component): 플랫폼 화면 테스트를 테스트 전용 페이지로 옮긴다 (0929/10-02)
문제: 라우터·chunk 복구·render 경계·앱 셸·런타임 트리 테스트가 스타터
화면(`/`의 h1, 홈의 "플랫폼 구성 보기" 링크, /examples/ui·states)을
대상으로 쓴다. 문서는 스타터 화면을 "페이지 단위로 교체 가능"하다고 하는데,
제품이 화면을 바꾸면 스타터와 무관한 플랫폼 테스트가 깨지고 동기화 때마다
같은 파일이 충돌한다(두 제품 기록).

방법: tests/helpers/fixture-feature.tsx에 테스트 전용 public 페이지 4개를
더했다. 메뉴에 나오는 지연 로드 페이지 2개(제목 h1, 런타임 릴리스 표시),
chunk 로드 실패 페이지, render 결함 페이지다. 플랫폼 테스트는 이미 쓰던
방식대로 생성 인덱스를 mock해 이 기능을 설치하고 그 페이지를 쓴다.
스타터 화면 자체를 검사하던 것(홈 시작 링크, 홈·플랫폼 구성의 릴리스 로딩
실패, 인증 예제의 복귀 URL, 상태 갤러리 제목 구조, 플랫폼 구성 화면)은
starter-pages.test.tsx와 starter-platform-overview-page.test.tsx로
모았다. 제품은 스타터 화면과 함께 starter-* 파일을 지우면 된다.
fixture는 design-system 배럴 대신 page-header.tsx를 직접 import한다.
배럴이 설치 카탈로그를 거쳐 mock된 생성 인덱스를 다시 불러 mock 팩토리가
자기 자신을 기다린다.
버린 대안: README에 "함께 사라지는 검사" 목록만 적는다. 비용은 0이지만
화면을 바꾸면 검사는 여전히 깨지거나 사라진다.

위험: 플랫폼 경로(createRegisteredRoutes의 platformChildren)를 지나는
화면 이동 테스트가 줄고 context 라우트 경로로 옮겨 갔다. `/`와 not-found는
여전히 플랫폼 경로로 돈다. ui-gallery-page는 이제 component 테스트에서
렌더되지 않는다(e2e·visual이 본다). sibling chunk 초기화 테스트는
key={definition.routeId}를 지우면 여전히 실패한다(변이 확인).

검증: RED는 템플릿 복사본에서 home-page.tsx와 examples/*를 다른 화면으로
바꾸고 test:component를 돌렸다. 7파일 20개 실패(router 5, route-status 4,
platform-overview 7, app-shell·async-surface·chunk-recovery·
runtime-application 각 1). GREEN은 같은 조작에서 starter-* 2파일 12개만
실패하고, starter-*를 지우면 34파일 216개 전부 통과. worktree에서
tests/component 36파일 228개 통과, tsc -p tsconfig.test.json 통과, 바꾼
파일 eslint 통과.
2026-11-03 01:18:21 +09:00

11 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) and /examples/* (src/presentation/examples/) are template content. Their own tests are the tests/component/starter-*.test.tsx files; delete them together with the screens. 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 when the starter screens change. Browser-level checks of the starter screens stay in tests/e2e and tests/visual.

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

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 twice: its API contract operation (V2) is what check:registries governs, and its contract contribution descriptor (V3) is what executes. tests/unit/http-operation-v2-v3-parity.test.ts fails when one exists without the other or when they disagree. 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. The app module refuses anything else when it loads, naming the route, feature and context (src/apps/deployable-app-module.ts).
  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:

File Change
src/.generated/* regenerated automatically
src/contexts/<context>/context-module.ts only when the feature needs a new context
config/runtime/<profile>.json optional FEATURE_OVERRIDES entry to switch the feature off
src/bootstrap/product-composition.ts (product-owned) only when 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
src/contracts/product-contracts.ts (product-owned) only for a product auth profile or a product runtime-config key

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. tests/unit/second-api-feature-registries.test.ts adds such a feature (an API operation and a route with its own search schema and loading surface) to a copy of the repository and runs check:registries on it.

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.