# 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. ```bash 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/.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/.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` for `local` and `development`; a `staging` or `production` build fails without it | | `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/.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: ```bash APP_PROFILE=production \ RUNTIME_API_BASE_URL=/ \ RUNTIME_TELEMETRY_ENDPOINT= \ VITE_BUILD_ID= 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`](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`](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`](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`](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/browser-data-capability-completion-ledger.md), [`docs/architecture/client-cache-and-storage.md`](docs/architecture/client-cache-and-storage.md) and [`docs/architecture/api-contract-schema-mapper-and-server-state.md`](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 declared feature the build or `FEATURE_OVERRIDES` left out. A sample directory that is no feature at all carries a `src/features//NOT_A_FEATURE` marker file instead | 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 mount - `src/apps` — deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces - `src/contexts` — bounded contexts: each `context-module.ts` declares its app, route root and feature budget - `src/features` — removable vertical slices (`src/features//{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 providers - `src/adapters` — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more - `src/application` — generic use cases, ports, policies and view-models - `src/contracts` — shared vocabulary and registries read by several layers, the workers and the build and release scripts - `src/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`: ```text 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 the reference sample, 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](docs/architecture/frontend-platform-capability-review.md) - [ports, adapters, and feature boundaries](docs/architecture/frontend-ports-adapters-and-boundaries.md) - [REST, GraphQL, Connect/gRPC-Web, Schema, Mapper, and Server State](docs/architecture/api-contract-schema-mapper-and-server-state.md) - [Protobuf browser transports and REST Gateway](docs/architecture/protobuf-browser-transport-and-rest-gateway.md) - [backend API and Server State handoff contract](docs/architecture/backend-api-and-server-state-contract.md) - [TypeScript, state ownership, and data flow](docs/architecture/typescript-state-and-data-flow.md) - [routing, page templates, and reusable patterns](docs/architecture/routing-pages-and-patterns.md) - [browser data capability completion ledger](docs/architecture/browser-data-capability-completion-ledger.md) - [browser file and origin-storage platform](docs/architecture/browser-file-and-origin-storage.md) - [client cache and storage](docs/architecture/client-cache-and-storage.md) - [realtime events, Web Push, and bounded polling](docs/architecture/realtime-events-web-push-and-bounded-polling.md) - [presigned transfer, resumable upload, streaming download, and Image CDN](docs/architecture/presigned-transfer-and-image-cdn.md) - [server file capability infrastructure](docs/architecture/server-file-capability-infrastructure.md) - [design-system platform](docs/styling/design-system-platform.md) - [frontend platform testing strategy](docs/testing/frontend-platform-testing-strategy.md) - [implementation roadmap](docs/architecture/frontend-platform-implementation-roadmap.md) 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`](docs/README.md) sorts the documents into current contracts, target designs and work history. [`docs/manual/`](docs/manual/README.md) is the step-by-step guide (Korean) for adding a feature, starting from `corepack pnpm create:feature `. ### 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: ```bash 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`](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`](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](docs/architecture/decisions/VD-01-typescript-lint-tooling.md)에 기록돼 있다. Application feature input은 module augmentation으로 닫힌 ID와 정확한 input shape를 제공하며, 공통 `Result`는 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: ```bash 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 at `artifacts/tests/a11y-manual/.md`. The routes are `ROUTE_REGISTRY`; `verify:documentation` fails, naming the route ID, when a registered route has no record. The merge gate FE-GATE-009 runs only `review:a11y-manual -- --format-only`, which checks that every route record keeps the template's fields, reviewed or still pending. - `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until 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 in `config/ci/product-gates.json` ([`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md)); until then the result is `UNVERIFIED`, not `PASS`. A host serving another release fails, and so does one without HTTP/2 or entry compression. ## CI and evidence The gate registry is `config/ci/gates.json`; the Gitea workflow is `.gitea/workflows/quality-gates.yml`. It follows: ```text 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 14 merge gates locally before merging (FE-GATE-008 and 009 need Playwright browsers; FE-GATE-012 builds the app first). Product checks listed in `config/ci/product-gates.json` (`PRODUCT-GATE-NNN`) run in the workflow's own `product_merge_gate` job: ```bash for gate in 001 002 003 004 005 006 007 008 009 010 011 012 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`](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. Its unreleased section summarizes one sync range (the section head names the base commit and the branch); take that range as a whole and do its "먼저 할 일" (BREAKING) steps in order before running the gates. 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: ```bash git remote add template