chore: rename the imported template to memento

Takes over the identity the template left generic. The application name
becomes Memento in the browser title, the shell header and the home
page, in both the Korean and English catalogs.

The browser storage namespace moves from `ca-frontend` to `memento`,
which also moves the OPFS root directory, its mutation lock and the
journal metadata prefix. Nothing is migrated, because this repository
has never been deployed and so no origin holds data under the old
prefix. The tests that assert those key strings move with them.

Release provenance needs no edit here: the builder and verifier ids are
derived from the `name` in package.json upstream, so changing that one
line renames them too.

The template name is left alone in docs/, where it is part of the record
of work that actually happened in that repository, and in the secret
scan tool id, which is an internal identifier matched by a validator on
both sides rather than a product name.

README.md now describes this repository and, more importantly, records
how to merge from upstream and exactly which files carry a memento value
and will therefore be where conflicts land.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-20 13:52:24 +09:00
co-authored by Claude Opus 5
parent 6a30db2550
commit c7caeefd06
16 changed files with 59 additions and 171 deletions
+39 -151
View File
@@ -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` (`<title>`) | `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`를 참고하세요.
+1 -1
View File
@@ -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</title>
<title>Memento</title>
</head>
<body>
<div id="root"></div>
+1 -1
View File
@@ -1,5 +1,5 @@
{
"name": "clean-architecture-frontend-template",
"name": "memento-frontend",
"version": "0.1.0",
"private": true,
"type": "module",
@@ -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(
+2 -2
View File
@@ -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,
+1 -1
View File
@@ -1,4 +1,4 @@
const APP_NAMESPACE = "ca-frontend";
const APP_NAMESPACE = "memento";
export type StorageBackend =
| "memory"
+4 -4
View File
@@ -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",
+1 -1
View File
@@ -40,7 +40,7 @@ export default function HomePage() {
<section className="ui-page">
<PageHeader
eyebrow="프로젝트 시작점"
title="Clean Architecture Frontend"
title="Memento"
description="도메인을 추가하기 전에 실행 구조와 범용 사용자 경험을 확인할 수 있는 중립적인 스켈레톤입니다."
/>
<div className="readiness-grid" aria-label="구현 준비 상태">
@@ -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";
+1 -1
View File
@@ -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(
+1 -1
View File
@@ -62,7 +62,7 @@ describe("production runtime application tree", () => {
expect(
await screen.findByRole("heading", {
name: "Clean Architecture Frontend",
name: "Memento",
}),
).toBeVisible();
expect(
+1 -1
View File
@@ -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();
@@ -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();
});
+1 -1
View File
@@ -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[] = [];
+1 -1
View File
@@ -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({
+1 -1
View File
@@ -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:");
});