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: Node 24 and Corepack. The repository pins pnpm in package.json.

corepack pnpm install --frozen-lockfile
corepack pnpm dev

Runtime-public settings live in public/config.json and are validated before the product tree mounts. Client secrets are forbidden.

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
`/sample/resources`	protected, domain-neutral integration route

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.

Architecture

Dependencies point inward:

presentation -> application -> domain
adapters -----^
bootstrap composes concrete adapters
contracts own cross-cutting registries

See docs/architecture/overview.md, docs/architecture/layers.md, and docs/architecture/starter-experience.md. The removable sample slice is under src/sample/contract-fixture; product code is not allowed to import it. The visible starter routes do not depend on that fixture and continue to build after it 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:

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:

corepack pnpm lint
corepack pnpm check:types
corepack pnpm check:architecture
corepack pnpm test:all
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

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 needs a signed human keyboard/focus/screen-reader review for all six registered routes.
collect:web-vitals-evidence stays FAIL_UNVERIFIED until a reviewed minimum eligible-sample threshold and 28 days of production data exist.

Live release verification additionally requires HOSTING_BASE_URL.

CI and evidence

The 26-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. 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/.

4.6 KiB Raw Blame History