Files
clean-architecture-frontend…/docs/architecture/starter-experience.md
T
DongHyeonka 1dda18da30 fix(docs): 참조 기능 경로를 다시 백틱으로 적어 문서 검사가 본다
문제
1103/14-04 조치는 참조 기능을 지운 사본에서 문서 검사가 통과하도록 참조
기능·참조 context 경로와 그 전용 파일·script를 백틱 없이 다시 적었다.
검사기는 백틱 안·명령 안·링크의 경로만 보므로(verify-documentation-
readiness.ts) 그 26줄은 참조 기능이 설치된 템플릿에서도 검사 밖이다. 참조
기능 파일 이름이 바뀌면 매뉴얼이 없는 경로를 가리켜도 어느 게이트도
실패하지 않는다. docs/manual/README.md의 "이 폴더 문서의 경로는 검사된다"가
예제 경로에서 거짓이다.

고른 방법
- 앞 커밋(1105/14-01)으로 검사기가 지운 템플릿 기능의 경로를 받으므로,
  README, starter-experience, static-delivery, compatibility,
  backend-api-and-server-state-contract, manual-checklist,
  adapter-remediation-ledger, performance-evidence, 매뉴얼 01·02·patterns의
  참조 기능 경로와 test:reference-feature를 다시 백틱(또는 명령 한 줄)으로
  적는다. 두 줄로 끊겨 검사되지 않던 measure 명령도 한 줄로 적었다.
  1105/15-02·16-01 조치가 starter-experience.md 표와 매뉴얼 03(A 표, "기능을
  지울 때")에 백틱 없이 더한 config/scale/feature-shape-ceilings.json과
  measure 명령 세 줄도 같은 규칙으로 고쳤다.
- patterns.md 첫머리 규칙("백틱 없이 적는다")과 README의 SAMPLE_EXTRAS
  안내를 새 규칙(설치된 동안 검사, 지운 사본에서는 받음)과 목록 모듈
  위치로 고쳤다.
- 테스트: template-feature-removal-documents.test.ts에 "names their paths
  and scripts only where verify:documentation checks them"을 더했다. 검사기가
  읽은 1절 문서 목록(documentation-review.json)을 받아, 지울 수 있는 템플릿
  기능의 경로·script가 백틱 span·링크 대상·셸 블록 밖에 나오면 실패한다.
  같은 우회가 다시 들어오는 것을 막는다. 지운 사본에서 통과하는 성질은 앞
  커밋의 "passes in a copy without reference-feature"가 본다.
- 버린 대안: 경로 존재만 보는 단위 테스트를 따로 두기(리뷰의 차선책).
  검사기와 같은 규칙을 두 곳에 두게 된다.

위험·한계
- 다음에 참조 기능 경로를 백틱 없이 적는 문서 변경은 새 테스트가 막는다.
  백틱으로 적으면 참조 기능을 지운 사본에서도 통과한다.
- 언어 없는 펜스 블록은 검사기처럼 셸 블록으로 보고 넘긴다. 그 안의 명령이
  아닌 줄(트리 그림 등)에 적은 경로는 검사기도 새 테스트도 보지 않는다.

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/unit/template-feature-removal-documents.test.ts
  tests/unit/documentation-readiness.test.ts, corepack pnpm
  verify:documentation, corepack pnpm test:sample-removal

Refs: 1105/14-03
2026-11-06 02:59:02 +09:00

302 lines
20 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`.
The state transitions an owner makes, and what `recover()` leaves behind for
each answer, are written on `SessionState` and `SessionGateway.recover` in
`src/application/ports/auth-session-port.ts`. For the paired backend's two
authentication modes there are owners to copy, not to write:
`recipes/session-owners/oidc-pkce-session-owner.ts` (JWT mode: Keycloak,
authorization code with PKCE, `EXTERNAL_BEARER`) and
`recipes/session-owners/cookie-session-owner.ts` (Redis session mode: the
session cookie, plus `SESSION_COOKIE_*` profiles and the `X-XSRF-TOKEN`
provider). `docs/manual/04-paired-backend-session.md` wires them and lists
what the backend template does not ship (a browser client in its realm; the
sign-in, sign-out and session endpoints).
`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.
### 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 delete
the feature. To delete it, remove those two folders and
`tests/features/platform-examples-feature/` (its component tests), then run
`corepack pnpm generate:feature-index`;
`corepack pnpm test:sample-removal -- --feature=platform-examples-feature`
does the same in a copy of the repository and runs the gates there. Their
routes then leave the registry, the navigation, the bundle and the manual
accessibility list (FE-GATE-028). This document keeps naming the three
folders after they are gone: `verify:documentation` checks the paths of a
removable template feature (`scripts/lib/removable-template-features.ts`)
while the feature is installed and accepts them once its `feature-module.ts`
is gone (1105/14-01).
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_A_FEATURE` marker file (`src/features/local-draft-feature/NOT_A_FEATURE`
is the one intentional example), or has both;
- 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 `schemas` (FE-REG-SCHEMA rows for the
feature's route and API schemas), the adapter contributions
(`defineFeatureAdapterContribution`, with `needs` naming the platform
capabilities it receives) and the contract contributions (the HTTP
operations). 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 | — |
| `public/release-manifest.json` (tracked, the dev server's manifest) | every added or removed feature: `create:feature` rewrites it (`node scripts/write-dev-release-manifest.ts`). Commit it with the feature. Two feature branches change its `setDigest` line; on a merge conflict take either side and run the command again (1105/16-01) | `test:unit` (`tests/unit/dev-release-manifest.test.ts`) names the command; the dev server does not boot (`CONTRACT_SET_PACKAGE_MISSING`) |
| `config/scale/feature-shape-ceilings.json` `initialJavascript` (tracked, only while the sample is installed) | every added or removed feature, and every template change that moves the initial JavaScript: `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`. Commit it with the change; on a merge conflict run the command again | `test:unit` (the feature-shape growth test compares it with a build) |
| `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/features/product-capabilities.ts` (product-owned) | `needs` names a capability the template does not build: type it in `ProductFeaturePlatformCapabilities`. `FeaturePlatformCapabilities` extends it, so the app, scripts and tests typecheck programs all see the key (an augmentation inside `product-composition.ts` is not seen by the scripts' program) | `check:types`: `Type '"<capability>"' is not assignable to type 'keyof FeaturePlatformCapabilities'` in the feature |
| `src/bootstrap/product-composition.ts` (product-owned) | `needs` names a capability the template does not build: return the capability here, typed in `product-capabilities.ts`. `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 `Installed contract contribution is not composable: <featureId>/<operationId>: unknown authProfileId <id>`. Config key: `check:types` where it is read. Give the key a `.default()` or make it `.optional()`: template tests build their config with `tests/helpers/runtime-config.ts`, which fills the product's defaults, and a required key without a default fails them. FE-REG-ENV row: `check:registries` checks its fields, and `tests/unit/env-registry-coverage.test.ts` (`test:unit`) requires a row for every key, with the schema's `required` and `defaultValue` |
| `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; `create:feature` writes
`<Pascal>NoRequest`, so a bare `NoRequest` would collide between features. 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.