139 lines
5.0 KiB
Markdown
139 lines
5.0 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: Node 24.11 or newer and Corepack. The repository pins pnpm in
|
|
`package.json`.
|
|
|
|
```bash
|
|
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`](docs/architecture/starter-experience.md).
|
|
The client route policy is user experience only; server authorization remains
|
|
authoritative.
|
|
|
|
## Architecture
|
|
|
|
Dependencies point inward:
|
|
|
|
```text
|
|
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:
|
|
|
|
- [platform capability review](docs/architecture/frontend-platform-capability-review.md)
|
|
- [ports, adapters, and feature boundaries](docs/architecture/frontend-ports-adapters-and-boundaries.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)
|
|
- [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: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
|
|
```
|
|
|
|
`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)에 기록돼
|
|
있다.
|
|
|
|
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` 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:
|
|
|
|
```text
|
|
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/`.
|