문제: context gateway는 적재한 라우트의 handle `routeId`가 가리키는
등록 라우트를 그린다. `context-routes.ts`가 기능 계약에 없는 route id를
handle에 실으면(오타, 계약에서 지운 라우트) 적재는 성공하고, 그 URL을
그릴 때 context 경계 실패 화면이 된다. 7139c7c가 리뷰의 (1)(2)를 했고
(3) "핸들의 route id가 레지스트리에 있는가"는 설계 선택으로 남겼다.
고른 방법: 적재 때 검사한다. `defineBoundedContextModule`이
`route.loadRoutes`를 감싸, 적재한 각 라우트의 handle `routeId`가 그
context 기능들의 계약 라우트 id에 없으면 TypeError로 실패한다. 메시지에
route id, context id, 기능 id를 담는다. handle에 `routeId`가 없어도
실패한다(gateway는 그 라우트를 NOT_FOUND로 그린다).
- 모든 context가 이 함수를 거치므로(생성된 product-context-index) 모든
context에 걸린다. 모든 context의 라우트를 적재하는 기존 단위 테스트
(tests/unit/route-runtime.test.ts)가 개발 단계에서 잡는다.
- 적재 실패는 09-09(de48db2)의 "청크 누락이 아닌 적재 실패" 경로로
context 경계에 가서 `ui.render.failed` 진단을 남긴다. 테스트로 확인했다.
- 라우트는 계속 늦게 읽는다. context를 정의할 때는 loadRoutes를 부르지
않는다.
- 7139c7c의 `contractRoutePaths`를 bounded-context-module.ts로 옮겨
앱 모듈과 같이 쓴다. "계약 라우트"의 정의가 한 곳에 남는다.
- starter-experience.md 기능 추가 3단계에 규칙을 적었다.
버린 대안:
- 헬퍼로 제공: 그 헬퍼를 쓰는 context만 지킨다. 안 쓰면 그만이다.
- 생성기에서 검사: 생성기는 정규식으로 리터럴만 읽어 handle을 모른다.
위험·한계:
- 생성된 index는 기능별 라우트를 합쳐서 돌려주므로, 어느 기능의
`context-routes.ts`가 잘못된 handle을 냈는지는 알 수 없다. 메시지는
그 context의 기능 id 전부를 적는다. 기능이 하나인 context(지금
reference)는 정확하다.
- 최상위 라우트만 본다. 지금 context 라우트는 평평하다. children을 쓰는
context가 생기면 재귀가 필요하다.
- `defineBoundedContextModule`을 거치지 않고 손으로 만든 context 객체는
검사되지 않는다. 그 경우는 기존처럼 렌더 때 context 경계가 잡는다.
- 등록 라우트가 없는 URL에서 난 적재 실패는 진단 route_id가 NOT_FOUND다.
레지스트리의 NOT_FOUND splat이 모든 URL에 맞아 gateway의
`?? routeModule.id` 대체가 쓰이지 않는다. 09-09의 동작이고 고치지 않았다.
- 초기 JS gzip +141 B(203,818 -> 203,959 B, 여유 982 -> 841 B).
같은 worktree에서 `vite build` 두 번으로 쟀다.
검증:
- RED: tests/architecture/context-route-roots.test.ts 새 3건 중 거절
2건이 "promise resolved ... instead of rejecting"으로 실패(10건 중 2
실패). tests/component/context-boundary-diagnostics.test.tsx 새 1건이
route_id "FIXTURE_ITEMSS"(렌더 때 경계)로 실패.
- GREEN: 두 파일 10건, 4건 통과.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
runtime-schema,integration,scripts,scale}(pnpm을 띄우는 4개 제외)
296 files 중 3,383 통과, 1건 실패. 실패는 telemetry-storm.test.ts의
10초 timeout(부하 34)이고 단독 재실행에서 4건 통과했다.
check-registries, check-adapter-inventory 통과.
- tsc app·test·node 통과. 바꾼 파일 eslint 통과.
verify-documentation-readiness PASS_SCOPED.
- check:architecture는 pnpm이 필요해 돌리지 않았다.
Refs: docs/reviews/2026-11-01-maturity-review/09-app-core.md 09-06
185 lines
9.5 KiB
Markdown
185 lines
9.5 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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](./routing-pages-and-patterns.md)
|
|
and the
|
|
[TypeScript, state, and data-flow target](./typescript-state-and-data-flow.md)
|
|
rather than adding another independent route or data-loading convention.
|
|
|
|
### 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/runtime-adapters.ts` | only when `needs` includes `indexedDb`: add the capability, built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts` |
|
|
|
|
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`).
|
|
|
|
### 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.
|