문제
/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를 지우면 된다.
Clean Architecture Frontend Template
A React/Vite reference implementation where architecture boundaries, integration behavior, release coherence, accessibility, performance, and operations are executable contracts rather than conventions.
Start locally
Requirements: the exact Node.js version in .nvmrc (currently 24.14.0) and
Corepack. The repository pins pnpm in package.json.
Product source, tests, build/quality scripts, and supported tool configuration
are TypeScript/TSX. allowJs is disabled. Node-side .ts scripts run directly
on the pinned Node 24 runtime and are checked with NodeNext resolution plus
erasable-syntax enforcement. Project-owned executable source contains no
JavaScript-family files; negative architecture, security, and type-compatibility
fixtures are TypeScript/TSX as well.
corepack pnpm install --frozen-lockfile
corepack pnpm dev
Runtime configuration
Runtime-public settings are validated against one schema before the product
tree mounts (runtimeConfigV2ArtifactSchema in
src/contracts/release-artifacts.ts). Client secrets are forbidden.
The source of truth is config/runtime/<profile>.json, one file per
environment: local, development, staging, production. corepack pnpm build writes dist/config.json from the selected profile
(scripts/generate-runtime-config.ts). public/config.json is only the local
profile for corepack pnpm dev; the build replaces it, so settings put there
never reach a deployment. Keep it equal to config/runtime/local.json plus
BUILD_ID: local-build and RELEASE_ID: local-release;
tests/unit/deployment-admission.test.ts fails when the two differ.
Build and deploy variables, lowest precedence first:
| Variable | Sets | Default |
|---|---|---|
APP_PROFILE |
which config/runtime/<profile>.json is used |
local; an empty value fails the build |
RUNTIME_API_BASE_URL |
API_BASE_URL, overriding the profile; the CI workflow cannot pass it (see below) |
the profile value |
RUNTIME_TELEMETRY_ENDPOINT |
TELEMETRY_ENDPOINT, overriding the profile; the CI workflow cannot pass it (see below) |
the profile value |
VITE_BUILD_ID |
BUILD_ID in the runtime config and the release manifest |
local-build |
RELEASE_ID |
RELEASE_ID in the runtime config and the release manifest |
local-release |
RELEASE_TARGET |
the environment FE-GATE-027 admits the build to; must equal APP_PROFILE |
none; admission refuses without it |
verify:documentation fails if this table stops naming a variable the build or
admission reads (scripts/verify-documentation-readiness.ts).
Only the two RUNTIME_* values can differ from the reviewed profile. Anything
else changes by editing the profile file. Staging and production reject demo
auth, non-HTTPS endpoints and the names reserved for examples and tests
(example.com, example.net, example.org and their subdomains, .example,
.invalid, .test). The shipped staging and production profiles use
*.example.com, so admission refuses them until a project sets its own
endpoints.
In CI the only way to set the endpoints is to commit them to
config/runtime/<profile>.json. The CI contract binds just APP_PROFILE and
RELEASE_TARGET to the build job (scripts/contracts/ci-gates.ts), so a
RUNTIME_* repository variable never reaches the build.
A local production build and its admission check:
APP_PROFILE=production \
RUNTIME_API_BASE_URL=<your-api-origin>/ \
RUNTIME_TELEMETRY_ENDPOINT=<your-telemetry-endpoint> \
VITE_BUILD_ID=<unique build id> RELEASE_ID=<unique release id> \
corepack pnpm build
APP_PROFILE=production RELEASE_TARGET=production corepack pnpm check:release-admission
With CI=true the gate runner (corepack pnpm ci:gate) also requires
VITE_COMMIT_SHA, SOURCE_DATE_EPOCH and CI_RUNNER_IMAGE before it runs a
gate (scripts/lib/build-environment.ts, scripts/run-ci-gate.ts). The CI variable
list is in docs/operations/ci-quality-gates.md.
Included starter experience
The default build mounts a domain-neutral application shell with a header,
responsive sidebar, route focus management, session integration status, a
persistent system / light / dark theme selector, and a language selector.
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 removable reference feature included. The platform
overview page (/examples/platform) shows the composed list at runtime, so
this README keeps no copy of it and adding a feature does not edit it.
AUTH_MODE=demo is credential-free and accepted only in local/development
environments. Deployments use AUTH_MODE=external and provide the opaque auth
owner described in
docs/architecture/starter-experience.md.
The client route policy is user experience only; server authorization remains
authoritative.
Support scope
Four tiers. The status words on the right are the ones the catalogs and design documents use; the next table maps them.
| Tier | What it covers | Status words |
|---|---|---|
| Default | In the default build and covered by the merge gates: the application shell and example routes, the REST HTTP executor, TanStack Query server state, Local/Session Storage registries, cross-tab invalidation, runtime config profiles and the release manifest check, AUTH_MODE=external (demo only in local/development), the typed message catalog, and the removable reference feature. dist/ is served by a static host (docs/architecture/static-delivery.md) |
COMPOSED |
| Optional (recipe) | Not installed. A project copies one of the recipes in config/recipes/frontend-capability-recipes.json and narrows it (docs/architecture/optional-adapter-recipes.md). realtime, offline-indexeddb, service-worker-pwa and file-transfer also ship a tested reference runtime that the default build leaves out |
RECIPE_AVAILABLE, NOT_INSTALLED, AVAILABLE_NOT_COMPOSED |
| Experimental | Designed and decided, but the runtime is missing or unfinished; finish it before building on it. GraphQL, gRPC-Web, Connect-Web and Protobuf adapters, Range resumable download, IndexedDB query persistence, the local preview decode-safety probe. src/features/local-draft-feature is an architecture sample, not installed |
DESIGNED_NOT_IMPLEMENTED |
| Not supported | Deliberately not selected, or browsers cannot guarantee it: SSR, app-managed background upload and download, directory selection, persistent file handles, product query persistence, exactly-once delivery between tabs | NOT_SELECTED, PLATFORM_LIMITED |
The rows come from
docs/architecture/browser-data-capability-completion-ledger.md,
docs/architecture/client-cache-and-storage.md
and
docs/architecture/api-contract-schema-mapper-and-server-state.md.
| Status word | Where it appears | Meaning | Tier |
|---|---|---|---|
COMPOSED |
capability ledger, design documents | wired into the default production path | Default |
INSTALLED |
a project's own recipe catalog (step 10 of the recipe procedure) | the project added the recipe | Default, for that project |
RECIPE_AVAILABLE |
recipe catalog status |
a recipe exists to copy; nothing is installed | Optional |
NOT_INSTALLED |
recipe catalog defaultStatus; a src/features/<id>/NOT_INSTALLED marker file |
not part of the build | Optional (recipe) or Experimental (feature) |
AVAILABLE_NOT_COMPOSED |
capability ledger; recipe referenceRuntime.status |
code and tests exist; the default build leaves it out | Optional |
DESIGNED_NOT_IMPLEMENTED |
capability ledger, design documents | design approved, runtime missing | Experimental |
NOT_SELECTED |
capability ledger, design documents | deliberately not chosen | Not supported |
PLATFORM_LIMITED |
capability ledger | browsers cannot guarantee it; offered only behind a probe and a fallback, if at all | Not supported as a guarantee |
Gate results (PASS, PASS_SCOPED, UNVERIFIED, FAIL_UNVERIFIED) are
verdicts on evidence, not support tiers.
Browsers: the build targets Chrome and Edge 111, Firefox 128, and Safari and
iOS 16.4. That is the higher of Vite 8's default JavaScript target
(baseline-widely-available; vite.config.ts sets no build.target) and
the CSS targets of Tailwind CSS 4. There is no browserslist. The end-to-end
suite runs on the desktop Chromium, Firefox and WebKit builds that Playwright
1.62 pins, plus one Chromium phone-size smoke (playwright.config.ts). Older
versions inside the target range and real mobile browsers are not tested.
Architecture
This repository is a Frontend Application Foundation: a starter/composition skeleton plus a reusable capability platform. Platform capabilities stay horizontal while product business features use vertical slices.
src/ has nine top-level folders. The descriptions match the table in
docs/architecture/layers.md, which also names every import rule:
src/bootstrap— the composition root: runtime configuration, concrete adapter construction and the React mountsrc/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 budgetsrc/features— removable vertical slices (src/features/<id>/{domain,application,contracts,adapters,presentation}) and the installed-feature catalogs (src/features/*.ts)src/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
Dependencies point inward. Every folder may also import contracts and
platform:
presentation -> application -> contracts -> platform
adapters -----^
bootstrap composes concrete adapters
apps -> contexts -> features (an app deploys contexts; a context owns features)
feature use case -> feature port <- feature-owned capability binding
Domain code lives inside each feature; there is no top-level domain folder.
See
docs/architecture/frontend-application-foundation.md,
docs/architecture/overview.md, docs/architecture/layers.md, and
docs/architecture/starter-experience.md. The removable vertical slice is
under src/features/reference-feature; its domain, application input, HTTP
binding, contracts, route runtime, and presentation own their contributions.
The central installed catalogs only aggregate selected contributions. The
generic starter routes continue to typecheck, test, and build after that
feature is removed.
Platform capability review
The starter shell is implemented, but the repository review also records the remaining work required before feature teams can use every declared contract through one end-to-end application path:
- platform capability review
- ports, adapters, and feature boundaries
- REST, GraphQL, Connect/gRPC-Web, Schema, Mapper, and Server State
- Protobuf browser transports and REST Gateway
- backend API and Server State handoff contract
- TypeScript, state ownership, and data flow
- routing, page templates, and reusable patterns
- browser data capability completion ledger
- browser file and origin-storage platform
- client cache and storage
- realtime events, Web Push, and bounded polling
- presigned transfer, resumable upload, streaming download, and Image CDN
- server file capability infrastructure
- design-system platform
- frontend platform testing strategy
- implementation roadmap
These documents distinguish repository defaults from opt-in adapters and project-owned integrations. They are target designs and review findings; a capability is not treated as implemented until its branch acceptance criteria and executable gates pass.
Documentation
docs/README.md sorts the documents into current contracts,
target designs and work history.
docs/manual/ is the step-by-step guide (Korean) for
adding a feature, starting from corepack pnpm create:feature <id>.
Files you can delete after copying
These record how the template was built. Nothing in the build or the gates
reads them, except the one file noted below
(tests/unit/deletable-history-documents.test.ts checks this).
| Path | Contents |
|---|---|
docs/superpowers/ |
past plans and specs |
docs/reviews/ |
reviews and the review guide. Keep docs/reviews/adapters/: check:adapter-inventory (FE-GATE-010) reads its INVENTORY.md, whose rows link to the adapter reviews beside it, and docs/operations/adapter-remediation-ledger.md cites those reviews |
SPEC.md, tasks/ |
requirements and task list of the 2026-09-25 review fix round |
CLAUDE.md |
review instructions for the template repository itself; replace it with your own |
PRODUCT.md |
product context of the template itself (users, purpose, principles) for design tools; replace it with your product's |
The reference feature is not in this list: deleting its directory alone
leaves tests, policy entries and CI scripts behind that fail the gates.
scripts/test-sample-removal.ts removes it from a copy of
the repository and lists everything that has to go with it (its header comment
and SAMPLE_EXTRAS); do the same in your project and run the gates.
Verification
Common local checks:
corepack pnpm lint
corepack pnpm check:types
corepack pnpm check:types:app
corepack pnpm check:types:node
corepack pnpm check:types:test
corepack pnpm check:architecture
corepack pnpm test:all
corepack pnpm test:contract
corepack pnpm test:e2e
corepack pnpm test:a11y
corepack pnpm build
corepack pnpm check:bundle
corepack pnpm test:performance
corepack pnpm verify:compatibility
corepack pnpm verify:release
corepack pnpm check:registries
corepack pnpm drill:runbooks
corepack pnpm check:ci
drill:runbooks stops at the first drill that is not PASS. Without provider
evidence every drill ends UNVERIFIED (exit 3), because a drill never reports
a check it could not run locally as PASS; see "Runbook jobs" in
docs/operations/ci-quality-gates.md.
test:all is the ordinary product-development loop and intentionally excludes
host-level CI-runner assurance. Run corepack pnpm test:system only on the
compatible Linux assurance host described in
docs/testing/taxonomy.md.
check:types는 source, Node scripts/config와 tests를 분리된 TypeScript
project로 모두 검사한다. type/architecture/security/registry의 invalid
fixture는 config/ci/gates.json에서 “실패해야 통과”하는 negative gate로
실행된다. 도구 호환성 결정은
VD-01에 기록돼
있다.
Application feature input은 module augmentation으로 닫힌 ID와 정확한 input
shape를 제공하며, 공통 Result<Value, Failure = AppFailure>는 error registry의
failure kind만 application/presentation 경계를 통과시킨다. Architecture gate는
TypeScript/TSX의 static, dynamic, type import를 별도 정적 그래프로 분석하고
runtime/source 영역의 JavaScript 재유입도 거절한다. 해석되지 않은 import,
parse failure, 금지 계층 edge와 순환 의존은 모두 fail-closed이며 전용
TypeScript/TSX negative fixture로도 검증된다.
Install the pinned Playwright browser engines before the first cross-browser run:
corepack pnpm exec playwright install --with-deps chromium firefox webkit
Two gates intentionally need external evidence:
review:a11y-manual(release gate FE-GATE-028) needs a signed human keyboard/focus/screen-reader review of every registered route, one record per route atartifacts/tests/a11y-manual/<ROUTE_ID>.md. The routes areROUTE_REGISTRY;verify:documentationfails, naming the route ID, when a registered route has no record. The merge gate FE-GATE-009 runs onlyreview:a11y-manual -- --format-only, which checks that every route record keeps the template's fields, reviewed or still pending.collect:web-vitals-evidencestaysFAIL_UNVERIFIEDuntil a reviewed minimum eligible-sample threshold and 28 days of production data exist.
Live hosting verification (FE-GATE-019, production stage) requires
HOSTING_BASE_URL and the promoted release deployed by the workflow's
deployment job. That job is an empty slot until the project fills it
(docs/operations/ci-quality-gates.md);
until then the result is UNVERIFIED, not PASS. A host serving another
release fails.
CI and evidence
The gate registry is config/ci/gates.json; the Gitea workflow is
.gitea/workflows/quality-gates.yml. It follows:
MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY
DOCUMENTATION_READY is independent. No gate is downgraded to a warning.
The workflow runs on pull requests, pushes to main and develop, and v*
tags. The Git host of this repository may not have Actions enabled, so a pull
request can show no gate status at all; no status is not a pass. Until the
host runs the workflow and marks the merge gates as required checks, run the 13
merge gates locally before merging (FE-GATE-008 and 009 need Playwright
browsers):
for gate in 001 002 003 004 005 006 007 008 009 010 011 013 020; do
corepack pnpm ci:gate -- "FE-GATE-$gate" || break
done
Machine-readable evidence is written below artifacts/; generated evidence is
ignored by Git while .gitkeep files preserve the taxonomy.
Operational details are in docs/operations/, with incident procedures in
docs/runbooks/.
Updating a copied project
Template versions are Git tags vX.Y.Z. CHANGELOG.md lists
the changes between tags, marks security fixes [보안] and contract changes
[계약] (backend, deployment, CI or feature code must change too), and names
the affected paths.
Record where you started. Right after copying, commit a one-line
.template-origin file at the root of your project with the template tag (or
commit) you copied and the date, for example v0.2.0 2026-09-26.
Take a template fix with Git. cherry-pick works even when your repository
does not share the template's history, because it merges against the picked
commit's parent:
git remote add template <template repository URL>
git fetch template --tags
git log --oneline <your origin>..template/main # what changed since you copied
git cherry-pick -x <commit> # one fix; -x records its origin
When the files have moved or diverged too far for a clean pick, read the change as a diff and apply it by hand:
git diff <commit>^ <commit> -- <paths from CHANGELOG>
Afterwards run the local merge gates from "CI and evidence", apply the
backend or deployment change a [계약] row names, and update
.template-origin once you have caught up to a tag. git revert undoes a pick.
Defects: if a problem reproduces on an unmodified checkout of your
.template-origin commit, it is a template defect. Report it on the template
repository with that commit and the reproduction; the template maintainer
classifies it and ships the fix with a CHANGELOG entry. A problem that needs
your changes to reproduce belongs to your project, and applying a template fix
to your copy is your project's job.