Files
clean-architecture-frontend…/README.md
T
DongHyeonkaandClaude Opus 5.5 5810461256 fix(docs): check README runtime variables in verify:documentation (13-15)
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>
2026-09-25 23:35:11 +09:00

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/`.