The unit test read README.md, which removal fixtures do not copy, so test:sample-removal failed. verify:documentation now requires README to name every build and deploy variable the generator and admission read. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
250 lines
12 KiB
Markdown
250 lines
12 KiB
Markdown
# 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/<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`; nothing checks that
|
|
yet.
|
|
|
|
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 profile value |
|
|
| `RUNTIME_TELEMETRY_ENDPOINT` | `TELEMETRY_ENDPOINT`, overriding the profile | 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 and non-HTTPS endpoints.
|
|
|
|
A production build and its admission check:
|
|
|
|
```bash
|
|
APP_PROFILE=production \
|
|
RUNTIME_API_BASE_URL=https://api.example.com/ \
|
|
RUNTIME_TELEMETRY_ENDPOINT=https://telemetry.example.com/v1/events \
|
|
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`](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, and a
|
|
persistent `system` / `light` / `dark` theme selector.
|
|
|
|
| Route | Purpose |
|
|
| --- | --- |
|
|
| `/` | implementation readiness and starter links |
|
|
| `/examples/ui` | buttons, fields, cards, alerts, badges, modal, and tokens |
|
|
| `/examples/states` | loading, refresh, empty, error, auth, forbidden, and not-found states |
|
|
| `/examples/auth` | reactive external-auth integration seam |
|
|
| `/examples/reference-resources` | removable, session-required reference feature |
|
|
|
|
`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.
|
|
|
|
## 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.
|
|
|
|
Dependencies point inward:
|
|
|
|
```text
|
|
presentation -> application -> domain
|
|
adapters -----^
|
|
bootstrap composes concrete adapters
|
|
feature use case -> feature port <- feature-owned capability binding
|
|
```
|
|
|
|
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](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.
|
|
|
|
## 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<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:
|
|
|
|
```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 for all ten registered routes: `APP_HOME`, `EXAMPLES_PLATFORM`,
|
|
`EXAMPLES_UI`, `EXAMPLES_STATES`, `EXAMPLES_AUTH`, `NOT_FOUND`,
|
|
`REFERENCE_RESOURCE_LIST`, `REFERENCE_RESOURCE_DETAIL`,
|
|
`REFERENCE_RESOURCE_FORM` and `REFERENCE_RESOURCE_STATUS`.
|
|
`verify:documentation` derives that list from the route registry and fails if
|
|
this paragraph falls behind it. 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 a deployed promoted release; without it the result is
|
|
`UNVERIFIED`, not `PASS`.
|
|
|
|
## CI and evidence
|
|
|
|
The 27-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 13
|
|
merge gates locally before merging (FE-GATE-008 and 009 need Playwright
|
|
browsers):
|
|
|
|
```bash
|
|
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/`.
|