diff --git a/README.md b/README.md index 7ccb063..3f7b6c4 100644 --- a/README.md +++ b/README.md @@ -1,181 +1,69 @@ -# Clean Architecture Frontend Template +# memento-frontend -A React/Vite reference implementation where architecture boundaries, -integration behavior, release coherence, accessibility, performance, and -operations are executable contracts rather than conventions. +`clean-architecture-frontend-template`에서 파생된 프론트엔드입니다. 아키텍처 경계, +통합 동작, 릴리스 일관성, 접근성, 성능, 운영이 관례가 아니라 실행 가능한 계약으로 +강제됩니다. 그 계약들의 설계 문서는 `docs/` 아래에 그대로 승계되어 있습니다. -## 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. +`.nvmrc`의 Node 버전(현재 24.14.0)과 Corepack이 필요합니다. pnpm 버전은 +`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. +런타임 공개 설정은 `public/config.json`에 있고 제품 트리가 마운트되기 전에 검증됩니다. +클라이언트 시크릿은 금지입니다. -## 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. +이 레포는 템플릿을 `upstream` 원격으로 추적합니다. 템플릿이 개선되면 머지로 받아옵니다. -| 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 +```bash +git fetch upstream +git merge upstream/main ``` -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. +`upstream`이 없으면 한 번 등록합니다. -### Platform capability review +```bash +git remote add upstream https://git.learn.hyeonworks.com/donghyeon.kang/clean-architecture-frontend-template +``` -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) +머지 충돌은 아래 파일에서만 날 수 있습니다. 충돌이 나면 memento 쪽 값을 유지하고 +나머지 변경은 템플릿 쪽을 받으면 됩니다. -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. +| 파일 | memento 값 | +| --- | --- | +| `package.json` (`name`) | `memento-frontend` | +| `index.html` (``) | `Memento` | +| `src/presentation/i18n/catalog.ts` (`common.appName`, `route.APP_HOME.title`, ko/en) | `Memento` | +| `src/presentation/pages/home-page.tsx` | `Memento` | +| `src/contracts/storage-keys.ts` (`APP_NAMESPACE`) | `memento` | +| `src/adapters/storage/opfs/opfs-policy.ts` | `memento-opfs-v1` | +| `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | `memento-opfs-metadata-v1` | +| `README.md` | 이 파일 | -## Verification +릴리스 증적에 박히는 builder/verifier ID는 `package.json`의 `name`에서 파생되므로 +따로 고칠 것이 없습니다. -Common local checks: +`docs/` 아래 설계·리뷰 문서에 남아 있는 템플릿 이름은 템플릿에서 실제로 일어난 작업의 +기록이므로 바꾸지 않습니다. + +## 검증 ```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 check:adapter-inventory 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 ``` -`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` 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. -- `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 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. -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/`. +전체 게이트 목록과 의미는 `docs/operations/ci-quality-gates.md`를 참고하세요. diff --git a/index.html b/index.html index 047e363..71e523e 100644 --- a/index.html +++ b/index.html @@ -4,7 +4,7 @@ <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="description" content="Clean Architecture frontend template" /> - <title>Clean Architecture Frontend + Memento
diff --git a/package.json b/package.json index ab51ed9..c59104d 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "clean-architecture-frontend-template", + "name": "memento-frontend", "version": "0.1.0", "private": true, "type": "module", diff --git a/src/adapters/storage/opfs/indexeddb-opfs-journal.ts b/src/adapters/storage/opfs/indexeddb-opfs-journal.ts index a578f53..e39693f 100644 --- a/src/adapters/storage/opfs/indexeddb-opfs-journal.ts +++ b/src/adapters/storage/opfs/indexeddb-opfs-journal.ts @@ -130,7 +130,7 @@ export function opfsJournalDatabaseName( if (!SAFE_BOUNDARY_ID.test(authorityToken)) { throw new TypeError("OPFS authority token is invalid."); } - return `ca-frontend-opfs-metadata-v1:${authorityToken}`; + return `memento-opfs-metadata-v1:${authorityToken}`; } export function createIndexedDbOpfsJournal( diff --git a/src/adapters/storage/opfs/opfs-policy.ts b/src/adapters/storage/opfs/opfs-policy.ts index 6787661..c8b8726 100644 --- a/src/adapters/storage/opfs/opfs-policy.ts +++ b/src/adapters/storage/opfs/opfs-policy.ts @@ -43,8 +43,8 @@ const OPAQUE_OBJECT_ID = /^[A-Za-z0-9_-]{8,128}$/u; const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+(?:\s*;.*)?$/iu; export const DEFAULT_OPFS_RUNTIME_POLICY: OpfsRuntimePolicy = Object.freeze({ - rootDirectoryName: "ca-frontend-opfs-v1", - mutationLockName: "ca-frontend-opfs-v1:mutation", + rootDirectoryName: "memento-opfs-v1", + mutationLockName: "memento-opfs-v1:mutation", chunkSizeBytes: 4 * 1024 * 1024, maxObjectBytes: 2 * 1024 * 1024 * 1024, maxChunkCount: 512, diff --git a/src/contracts/storage-keys.ts b/src/contracts/storage-keys.ts index bb726c1..14578a1 100644 --- a/src/contracts/storage-keys.ts +++ b/src/contracts/storage-keys.ts @@ -1,4 +1,4 @@ -const APP_NAMESPACE = "ca-frontend"; +const APP_NAMESPACE = "memento"; export type StorageBackend = | "memory" diff --git a/src/presentation/i18n/catalog.ts b/src/presentation/i18n/catalog.ts index 9bf90c7..072e424 100644 --- a/src/presentation/i18n/catalog.ts +++ b/src/presentation/i18n/catalog.ts @@ -3,7 +3,7 @@ import { INSTALLED_MESSAGE_CATALOGS } from "../../features/installed-feature-mes const PLATFORM_KO_MESSAGES = { "common.unavailable": "요청한 문구를 표시할 수 없습니다.", "common.processing": "처리 중…", - "common.appName": "Frontend Skeleton", + "common.appName": "Memento", "common.noDisplayValue": "표시 정보 없음", "action.retry": "다시 시도", "action.reauth": "로그인", @@ -41,7 +41,7 @@ const PLATFORM_KO_MESSAGES = { "shell.session.integrationFailed": "연동 필요", "shell.session.actionFailed": "세션 작업을 완료하지 못했습니다.", "route.APP_HOME.navigation": "홈", - "route.APP_HOME.title": "Clean Architecture Frontend", + "route.APP_HOME.title": "Memento", "route.EXAMPLES_PLATFORM.navigation": "플랫폼 구성", "route.EXAMPLES_PLATFORM.title": "플랫폼 구성", "route.EXAMPLES_UI.navigation": "UI 구성요소", @@ -162,7 +162,7 @@ export type MessageKey = keyof typeof KO_MESSAGES; const PLATFORM_EN_MESSAGES = { "common.unavailable": "This message is unavailable.", "common.processing": "Processing…", - "common.appName": "Frontend Skeleton", + "common.appName": "Memento", "common.noDisplayValue": "No display value", "action.retry": "Try again", "action.reauth": "Sign in", @@ -200,7 +200,7 @@ const PLATFORM_EN_MESSAGES = { "shell.session.integrationFailed": "Integration required", "shell.session.actionFailed": "The session action could not be completed.", "route.APP_HOME.navigation": "Home", - "route.APP_HOME.title": "Clean Architecture Frontend", + "route.APP_HOME.title": "Memento", "route.EXAMPLES_PLATFORM.navigation": "Platform composition", "route.EXAMPLES_PLATFORM.title": "Platform composition", "route.EXAMPLES_UI.navigation": "UI components", diff --git a/src/presentation/pages/home-page.tsx b/src/presentation/pages/home-page.tsx index 6dfeab7..ec595e5 100644 --- a/src/presentation/pages/home-page.tsx +++ b/src/presentation/pages/home-page.tsx @@ -40,7 +40,7 @@ export default function HomePage() {
diff --git a/tests/browser-capabilities/cross-context-invalidation.spec.ts b/tests/browser-capabilities/cross-context-invalidation.spec.ts index bdead72..8320633 100644 --- a/tests/browser-capabilities/cross-context-invalidation.spec.ts +++ b/tests/browser-capabilities/cross-context-invalidation.spec.ts @@ -8,7 +8,7 @@ const TOPIC = "sample-topic-alpha"; const TOPIC_VERSION = 1; const STATE_KEY = "__crossContextInvalidationCapability"; const STORAGE_PULSE_KEY = - "ca-frontend:cache-invalidation:v1:pulse"; + "memento:cache-invalidation:v1:pulse"; type BrowserTransportMode = "BROADCAST" | "STORAGE"; diff --git a/tests/component/router.test.tsx b/tests/component/router.test.tsx index ef18378..26e4206 100644 --- a/tests/component/router.test.tsx +++ b/tests/component/router.test.tsx @@ -72,7 +72,7 @@ describe("generic application router", () => { ).toBeVisible(); expect(window.location.pathname).toBe("/examples/ui"); await waitFor(() => - expect(document.title).toBe("UI 구성요소 · Frontend Skeleton"), + expect(document.title).toBe("UI 구성요소 · Memento"), ); await waitFor(() => expect( diff --git a/tests/component/runtime-application.test.tsx b/tests/component/runtime-application.test.tsx index 1da675a..b91dfe3 100644 --- a/tests/component/runtime-application.test.tsx +++ b/tests/component/runtime-application.test.tsx @@ -62,7 +62,7 @@ describe("production runtime application tree", () => { expect( await screen.findByRole("heading", { - name: "Clean Architecture Frontend", + name: "Memento", }), ).toBeVisible(); expect( diff --git a/tests/e2e/app-shell.spec.ts b/tests/e2e/app-shell.spec.ts index 3a96072..62df8b1 100644 --- a/tests/e2e/app-shell.spec.ts +++ b/tests/e2e/app-shell.spec.ts @@ -3,7 +3,7 @@ import { expect, test } from "../support/browser/strict-browser-test.ts"; test("boots the public app shell", async ({ page }) => { await page.goto("/"); await expect(page.getByRole("heading", { level: 1 })).toHaveText( - "Clean Architecture Frontend", + "Memento", ); await expect(page.getByRole("navigation", { name: "주요 탐색" })).toBeVisible(); await expect(page.getByRole("main")).toBeVisible(); diff --git a/tests/features/reference-feature/reference-page.test.tsx b/tests/features/reference-feature/reference-page.test.tsx index f4c7299..e8c089f 100644 --- a/tests/features/reference-feature/reference-page.test.tsx +++ b/tests/features/reference-feature/reference-page.test.tsx @@ -228,7 +228,7 @@ describe("reference feature page states", () => { expect( await screen.findByRole("heading", { level: 1, - name: "Clean Architecture Frontend", + name: "Memento", }), ).toBeVisible(); }); @@ -284,7 +284,7 @@ describe("reference feature page states", () => { expect( await screen.findByRole("heading", { level: 1, - name: "Clean Architecture Frontend", + name: "Memento", }), ).toBeVisible(); }); diff --git a/tests/unit/cross-tab-invalidation.test.ts b/tests/unit/cross-tab-invalidation.test.ts index 49df90b..87e6d02 100644 --- a/tests/unit/cross-tab-invalidation.test.ts +++ b/tests/unit/cross-tab-invalidation.test.ts @@ -24,7 +24,7 @@ const NOW = 1_000_000; const CACHE_EPOCH = "cache-epoch-0001"; const TOPIC = "sample-topic-alpha"; const CHANNEL_NAME = "cache-invalidation-v1"; -const STORAGE_PULSE_KEY = "ca-frontend:cache-invalidation:v1:pulse"; +const STORAGE_PULSE_KEY = "memento:cache-invalidation:v1:pulse"; class FakeBroadcastNetwork { readonly channels: FakeBroadcastChannel[] = []; diff --git a/tests/unit/indexeddb-opfs-journal.test.ts b/tests/unit/indexeddb-opfs-journal.test.ts index 14217ca..d557dff 100644 --- a/tests/unit/indexeddb-opfs-journal.test.ts +++ b/tests/unit/indexeddb-opfs-journal.test.ts @@ -347,7 +347,7 @@ describe("IndexedDB OPFS journal", () => { it("binds one opaque physical authority to one deterministic database", async () => { expect(opfsJournalDatabaseName(authorityToken)).toBe( - `ca-frontend-opfs-metadata-v1:${authorityToken}`, + `memento-opfs-metadata-v1:${authorityToken}`, ); expect(() => createIndexedDbOpfsJournal({ diff --git a/tests/unit/storage-registry.test.ts b/tests/unit/storage-registry.test.ts index 2942d53..1e25852 100644 --- a/tests/unit/storage-registry.test.ts +++ b/tests/unit/storage-registry.test.ts @@ -83,7 +83,7 @@ function definitionResolver( describe("storage registry", () => { it("builds namespace and schema-versioned physical keys", () => { expect(buildPhysicalKey("preference", 2, "theme")).toBe( - "ca-frontend:preference:v2:theme", + "memento:preference:v2:theme", ); expect(STORAGE_REGISTRY.COLOR_SCHEME.physicalKey).toContain(":v1:"); });