feat(docs): 문서 체계 검사를 verify:documentation에 더하고 입구 문서를 고친다

문제: 프론트 문서 체계는 백엔드와 다르다. docs/README.md는 "README와
입구 문서는 영어"라고 정해 두어 2026-11-07 소유자 결정(살아 있는
문서는 본문까지 한국어)과 반대이고, 기록의 머리 블록·언어·숫자 복사를
보는 검사가 없다. verify:documentation은 docs/README.md 1절이 링크한
문서의 경로만 본다.

고른 방법: 백엔드 scripts/check-docs.py의 규칙(language, head, number,
map, readme, style)을 같은 이름·문턱으로 TypeScript로 옮겨
scripts/lib/docs-system.ts에 두고 verify:documentation(FE-GATE-017)이
부르게 한다. 참조 검사는 지금 있는 것을 그대로 쓰고 대상만 살아 있는
문서 전부로 넓힌다. FE-GATE-017 job은 workflow_dispatch(documentation
단계)에서만 돌아서, PR에서 실패하도록 merge 단계 FE-GATE-005의
documentation-readiness 시험이 이 repo를 그대로 두고
verify:documentation을 한 번 돌린다.
- 버린 안: 새 게이트나 package script를 더하는 것. config/ci(정리
  3단계·CI 세션 범위)와 CI 계약의 개수·해시를 건드린다.
- 버린 안: check-docs.py를 그대로 복사하는 것. 프론트 CI 이미지와
  도구는 Node뿐이고, 참조 검사(짝 백엔드 pin, 지운 샘플, 생성 산출물)는
  이미 TS에 있다.
- 예외 목록 scripts/docs-system-exceptions.txt는 줄기만 한다(줄마다
  FROZEN 지문). 이 커밋의 줄은 아직 옮기지 않은 문서의 기준선이고 뒤
  번역 커밋들이 지운다.
- docs/README.md를 모든 문서 폴더를 덮는 지도와 수명·언어·머리 블록·
  검사 규칙으로 다시 쓰고, 루트 README.md를 docs-system.md 6.1절의 필수
  절 순서로 한국어로 다시 쓴다. README의 src 폴더 설명은 layers.md 표와
  글자가 같아야 하므로 layers.md·overview.md·foundation.md를 같이 옮긴다.
- README 「복사한 뒤 지워도 되는 것」을 읽는 정규식과, 문서를 바꿔 넣는
  테스트의 기대 문자열을 새 한국어 문장으로 고친다. 검사기는 기록
  폴더 이름을 적지만 지운 사본에서도 통과하므로
  deletable-history-documents 테스트의 검사 대상에서 뺀다(그 이유를
  테스트와 검사기 시험에 적었다).

위험: 파생 서비스가 이 변경을 받으면 자기 살아 있는 문서가 영어일 때
verify:documentation이 실패한다. CHANGELOG에 「먼저 할 일」로 적는다.
review-evidence.md는 다른 작업 공간의 경로를 적은 사본이라 참조·숫자
검사에서 뺐다(HISTORY_HOLDERS).

검증: tests/unit/docs-system.test.ts(조건마다 실패 입력),
documentation-readiness·template-feature-removal-documents·
deletable-history-documents 시험, verify:documentation을 desktop에서 돌렸다.
This commit is contained in:
DongHyeonka
2026-11-08 21:57:39 +09:00
parent 2b8a348c1f
commit 7a9aefdf25
13 changed files with 1916 additions and 798 deletions
+144 -78
View File
@@ -1,113 +1,179 @@
# 문서 색인
# docs
`docs/`의 문서를 세 묶음으로 나눈다.
저장소의 문서는 이 폴더 아래에 있다(루트 `README.md`, `CHANGELOG.md` 등 몇 개는 밖에 있다). 이 README는 두 가지를 정한다.
```text
1. 현재 계약 지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계 앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력 리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다
```
- 어떤 문서가 어느 폴더에 있나: 1절 「문서 지도」. 지금 있는 모든 문서 폴더를 덮는다.
- 문서의 수명에 따라 무엇을 어떤 언어로 어떻게 고치나: 2절부터.
문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는
문서 안의 상태 값(`COMPOSED`, `AVAILABLE_NOT_COMPOSED`, `DESIGNED_NOT_IMPLEMENTED` 등)으로
확인한다. 상태 값의 뜻은 `README.md`의 "Support scope" 절에 있다.
규칙의 정본은 design-docs 저장소의 `conventions/docs-system.md`다. 이 README는 그 규칙을 이 repo에 적용한 내용이고, 이 템플릿을 복사한 프로젝트도 이 README를 따른다.
파일 목록과 개수는 여기에 적지 않는다. 적으면 다음 문서가 더해지는 순간 틀린 글이 된다. 파일은 폴더를 직접 읽는다.
README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.
문서와 코드가 다르면 코드가 맞다.
## 1. 현재 계약
## 1. 문서 지도
처음 읽을 입구 문서 6개다.
- 표의 첫 칸이 폴더다(`docs/` 기준 경로).
- 새 문서 폴더를 만들면 같은 변경에서 이 지도에 행을 더한다. 폴더를 지우거나 옮기면 그 행도 고친다.
- 문서 검사의 `map`이 지도에 없는 폴더와, 지도에 있지만 없는 폴더를 막는다(5절).
### 처음 읽을 문서
| 문서 | 정하는 것 |
|---|---|
| [`README.md`](../README.md) | 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영 |
| --- | --- |
| [`README.md`](../README.md) | 프로젝트 구조, 시작하기, 런타임 설정과 배포 변수, 기능 켜고 끄기와 지원 범위, 검증과 CI, 새 서비스로 시작하기, 원본 업데이트 반영 |
| [`architecture/frontend-application-foundation.md`](architecture/frontend-application-foundation.md) | 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계 |
| [`architecture/layers.md`](architecture/layers.md), [`architecture/overview.md`](architecture/overview.md) | 계층과 import 방향. `check:architecture`가 검사한다 |
| [`architecture/starter-experience.md`](architecture/starter-experience.md) | 기본 라우트, 인증 모드, 기능 추가·제거 절차 |
| [`architecture/optional-adapter-recipes.md`](architecture/optional-adapter-recipes.md) | 선택 기능(recipe)을 넣고 빼는 절차 |
| [`manual/`](manual/README.md) | 새 기능을 더하는 순서와 판단 기준, `create:feature`, 완료 기준([`manual/reference/`](manual/reference/)) |
| [`operations/ci-quality-gates.md`](operations/ci-quality-gates.md), [`testing/taxonomy.md`](testing/taxonomy.md) | 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선 |
입구 문서가 가리키는 세부 규칙:
### 매뉴얼
- 새 기능 추가 매뉴얼(작업 순서, 단계별 판단 기준, `create:feature`): [`manual/`](manual/), [`manual/reference/`](manual/reference/). 한국어다
- 규모 설계(구조·소유·실행·트래픽·오류·검증·텔레메트리·릴리스 일관성)와 코드 주석 `scale-architecture.md §N`의 근거: [`architecture/scale-architecture.md`](architecture/scale-architecture.md). 절마다 현재 계약인지 기록만인지 머리말 표에 적었다
- 계약 소유와 호환성: [`architecture/contract-ownership.md`](architecture/contract-ownership.md), [`contracts/compatibility.md`](contracts/compatibility.md)
- 짝 백엔드 Envelope 판정과 쓰기 전 거절 표(지금 실행 규칙, `src/adapters/http/backend-envelope.ts`의 근거): [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md) 4.1·6·6.1절. 기준 커밋은 [`../config/contracts/backend-contract-pin.json`](../config/contracts/backend-contract-pin.json). 같은 문서의 나머지 절은 목표 설계다
- 정적 배포와 런타임 설정: [`architecture/static-delivery.md`](architecture/static-delivery.md)
- 기능 개발자가 알아야 하는 양: [`architecture/capability-consumer-experience.md`](architecture/capability-consumer-experience.md)
- 운영·복구: [`operations/`](operations/), [`runbooks/`](runbooks/)
- 보안과 공급망: [`security/browser-boundary.md`](security/browser-boundary.md), [`security/supply-chain.md`](security/supply-chain.md)
- 디자인 토큰과 수동 접근성 검토: [`styling/design-tokens.md`](styling/design-tokens.md), [`accessibility/manual-checklist.md`](accessibility/manual-checklist.md)
- 버전별 변경: [`../CHANGELOG.md`](../CHANGELOG.md)
일하는 순서와 판단 지점이다. 사람과 AI 세션이 같이 쓴다.
`verify:documentation`은 이 파일과 이 절에서 링크한 문서(폴더 링크는 그 안의 `.md` 전부)에
적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. 명령(인라인 코드와
셸 코드 블록) 안의 경로 인자도 본다. 짝 백엔드 템플릿(`clean-architecture-backend-template`)의
경로와 링크는 `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다.
이 checkout 옆에 있는 짝 checkout의 git 기록을 읽고, 그 작업 트리와 HEAD는 보지 않는다. 짝
checkout이 없거나 그 커밋이 없으면 실패 대신 확인하지 못한 것으로 출력과
`artifacts/quality/documentation-review.json`에 남긴다. repo 밖으로 나가는 링크가 짝 저장소를
가리키지 않으면(저장소 이름 오타 포함) 실패한다. `CHANGELOG.md`는
지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은
없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은
`scripts/verify-documentation-readiness.ts`다.
프로젝트가 지울 예정인 샘플 기능(목록은 `scripts/lib/removable-template-features.ts`, 템플릿은
비어 있다)의 경로와 script는 그 기능이 설치돼 있을 때(`src/features/<id>/feature-module.ts`가
있을 때) 검사하고, 지운 뒤에는 없어도 된다.
| 폴더 | 무엇 |
| --- | --- |
| `manual/` | 개발 매뉴얼: 새 기능 하나를 더하는 0~11단계, 결정표, 기능 폴더 밖 파일, 짝 백엔드에 붙이기. `manual/reference/`에 명령 인자, 전역 ID, 패턴, 오류 메시지, 완료 기준 |
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
### 현재 계약
지금 코드가 지키는 규칙이다. 코드와 같은 변경에서 고친다.
| 폴더 | 무엇 |
| --- | --- |
| `architecture/` | 계층과 import 규칙(`architecture/layers.md`), 플랫폼의 역할, 스타터, recipe 절차, 정적 배포, 계약 소유, 규모 설계(`architecture/scale-architecture.md`, 코드 주석의 `scale-architecture.md §N`이 가리킨다), 짝 백엔드 계약(`architecture/backend-api-and-server-state-contract.md` 4.1·6·6.1절이 실행 규칙. 기준 커밋은 `config/contracts/backend-contract-pin.json`), 2026-07-18 도식 리뷰 기록의 사본(`architecture/review-evidence.md`, `architecture/review-ledger.json`) |
| `contracts/` | 계약 호환 규칙(읽는 쪽을 먼저 배포한다) |
| `security/` | 브라우저 보안 경계와 공급망 |
| `styling/` | 디자인 토큰 |
| `accessibility/` | 수동 접근성 검토 체크리스트. 라우트별 기록은 repo 루트의 `artifacts/tests/a11y-manual/`에 있다 |
| `testing/` | 테스트 계층(taxonomy)과 새 프로젝트가 초기화할 기준선 |
### 운영
| 폴더 | 무엇 |
| --- | --- |
| `operations/` | CI 품질 게이트, capability별 복구 절차, 릴리스·캐시 롤백, 성능 증거, 2026-08-14 adapter 재검토의 처리 원장(`operations/adapter-remediation-ledger.md`) |
| `runbooks/` | 오류 code별 장애 대응 runbook(`FE-RB-00N`). 등록은 `config/runbooks/runbooks.json` |
### 결정 기록
| 폴더 | 무엇 |
| --- | --- |
| `adr/` | 결정 기록(VD). 번호는 옮기기 전과 같다(`VD-NN-<주제>.md`). 2026-11-08에 architecture 아래 decisions 폴더에서 옮겼다 |
### 설계와 기록
설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다.
| 폴더 | 무엇 |
| --- | --- |
| `design/` | 설계서. `YYYY-MM-DD-<주제>-design.md`. 2026-11-08에 옛 superpowers 폴더의 specs와 `architecture/`의 목표 설계를 옮겼다 |
| `history/plans/` | 계획서. 2026-09-25 리뷰 수정 라운드의 요구사항(`SPEC.md`)과 작업 목록도 여기 있다 |
| `history/evidence/` | 작업 단계의 증거·체크포인트 |
| `reviews/` | 리뷰 결과. 라운드마다 폴더 하나(README가 결정과 남은 것을 적는다) 또는 리뷰 문서 하나. 리뷰 가이드와 실행 체크리스트는 design-docs 저장소로 옮겼고, 여기에는 정본 위치를 알려 주는 포인터 둘이 있다 |
- 계획서 본문에는 그때 계획한 경로와 명령이 그대로 남아 있다. 계획서를 나중에 고치지 않는 이유는, 고치면 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 되기 때문이다.
- `history/`와 `reviews/`는 복사한 프로젝트가 지워도 된다(루트 `README.md` 「복사한 뒤 지워도 되는 것」). 예외는 `reviews/adapters/`다: `reviews/adapters/INVENTORY.md`는 `check:adapter-inventory`(FE-GATE-010)가 `src/adapters`와 대조하는 살아 있는 목록이다.
- `design/`과 `adr/`은 코드 주석이 근거로 가리키므로 지우지 않는다.
### 폴더 밖 문서
| 문서 | 무엇 |
| --- | --- |
| [`../README.md`](../README.md) | 루트 README. 6절의 필수 절을 가진다 |
| [`../CHANGELOG.md`](../CHANGELOG.md) | 템플릿 버전 사이의 변경. 지난 상태를 적는 문서라 문서 검사의 참조·숫자 검사는 보지 않는다 |
| [`../CLAUDE.md`](../CLAUDE.md) | 이 repo를 리뷰할 때의 기준 |
| [`../PRODUCT.md`](../PRODUCT.md) | 디자인 도구가 읽는 제품 맥락 |
| [`../src/adapters/browser-transfer/image-cdn/README.md`](../src/adapters/browser-transfer/image-cdn/README.md) | Image CDN adapter의 모듈 README |
### 게이트가 읽는 파일
지우거나 옮기면 게이트가 실패한다.
| 파일 | 읽는 명령 |
|---|---|
| --- | --- |
| 이 파일, `architecture/review-ledger.json`, `architecture/review-evidence.md` | `verify:documentation` (FE-GATE-017) |
| repo 루트의 `artifacts/tests/a11y-manual/` 라우트별 기록 | `verify:documentation` (FE-GATE-017), `review:a11y-manual` (FE-GATE-009, FE-GATE-028) |
| repo 루트의 라우트별 수동 접근성 기록(`artifacts/tests/a11y-manual/<ROUTE_ID>.md`) | `verify:documentation` (FE-GATE-017), `review:a11y-manual` (FE-GATE-009, FE-GATE-028) |
| `reviews/adapters/INVENTORY.md` | `check:adapter-inventory` (FE-GATE-010) |
| `operations/adapter-remediation-ledger.md`, `operations/adapter-remediation-dispositions.json` | `check:remediation-ledger` (게이트 밖. 이유는 `config/ci/ungated-scripts.json`) |
| `architecture/backend-api-and-server-state-contract.md` 6.1절 표 | `tests/unit/backend-contract-pin-document.test.ts` (FE-GATE-005) |
| `architecture/starter-experience.md`의 기능 폴더 밖 파일 표, `manual/03-outside-feature-folder.md` A절 | `tests/unit/feature-tracked-files.test.ts` (FE-GATE-005) |
| `manual/`의 표시한 코드 블록과 `manual/04-paired-backend-session.md` 3.2절 | `tests/unit/manual-code-blocks.test.ts`, `tests/unit/manual-paired-backend-settings.test.ts` (FE-GATE-005) |
## 2. 목표 설계
## 2. 문서 수명과 언어
설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.
| 수명 | 문서 | 위치 | 언어 | 고치는 법 |
| --- | --- | --- | --- | --- |
| 살아 있음 | README, `CLAUDE.md`, 매뉴얼(`manual/`), 현재 계약(`architecture/`, `contracts/`, `security/`, `styling/`, `accessibility/`, `testing/`), 운영(`operations/`, `runbooks/`), `reviews/adapters/INVENTORY.md`, 모듈 README, `CHANGELOG.md` | 제자리 | 한국어 | 코드와 같은 변경에서 고친다(4절) |
| 결정 | 결정 기록(VD) | `adr/` | 한국어 | 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 맨 아래에 날짜가 있는 「보완」 절을 덧붙인다. 크게 바뀌면 새 VD를 쓰고 옛 VD를 「대체됨」으로 한다 |
| 기록 | 설계서, 계획서, 증거, 리뷰 | `design/`, `history/`, `reviews/` | 머리 블록은 한국어, 본문은 쓴 때의 원문 | 머리 블록의 칸만 고친다 |
- 런타임 capability 결정의 정본: [`architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md`](design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)
- 상태 원장: [`architecture/browser-data-capability-completion-ledger.md`](design/2026-07-30-browser-data-capability-completion-ledger-design.md)
- 전체 검토와 로드맵: [`architecture/frontend-platform-capability-review.md`](design/2026-07-26-frontend-platform-capability-review-design.md), [`architecture/frontend-platform-implementation-roadmap.md`](design/2026-07-26-frontend-platform-implementation-roadmap-design.md)
- 포트·경계·데이터 흐름: [`architecture/frontend-ports-adapters-and-boundaries.md`](design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md), [`architecture/typescript-state-and-data-flow.md`](design/2026-07-26-typescript-state-and-data-flow-design.md), [`architecture/routing-pages-and-patterns.md`](design/2026-07-26-routing-pages-and-patterns-design.md)
- API와 서버 상태: [`architecture/api-contract-schema-mapper-and-server-state.md`](design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md), [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md), [`architecture/protobuf-browser-transport-and-rest-gateway.md`](design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
- 브라우저 데이터: [`architecture/client-cache-and-storage.md`](design/2026-07-28-client-cache-and-storage-design.md), [`architecture/browser-file-and-origin-storage.md`](design/2026-07-27-browser-file-and-origin-storage-design.md), [`architecture/presigned-transfer-and-image-cdn.md`](design/2026-07-30-presigned-transfer-and-image-cdn-design.md), [`architecture/server-file-capability-infrastructure.md`](design/2026-07-28-server-file-capability-infrastructure-design.md)
- 실시간: [`architecture/realtime-events-web-push-and-bounded-polling.md`](design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)
- 디자인 시스템과 테스트 전략: [`styling/design-system-platform.md`](design/2026-07-26-design-system-platform-design.md), [`testing/frontend-platform-testing-strategy.md`](design/2026-07-26-frontend-platform-testing-strategy-design.md)
- 결정 기록(ADR): [`architecture/decisions/`](adr/) `VD-*.md`
- 살아 있는 문서와 결정 기록의 본문은 한국어로 쓴다. 설정 파일의 사람이 읽는 설명 칸(recipe 카탈로그, runbook 등록)도 한국어다.
- 원문으로 두는 것: 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 외부 문서 인용, 제품 이름.
- 용어는 자연스러운 한국어 → 한국어(영어) → 영어 그대로 순으로 고른다. 처음 나올 때 한 번 병기한다. 이 repo가 영어로 쓰는 말(adapter, port, capability, recipe, feature, context, slice, registry, gate 등)은 영어로 둔다.
- 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
- 2026-11-08에 살아 있는 문서를 모두 한국어로 옮겼다. 문서 검사의 예외 목록은 비어 있다(5절).
- `artifacts/tests/a11y-manual/`의 라우트별 기록은 문서가 아니라 정해진 영어 키 형식의 게이트 입력이다(`scripts/lib/manual-a11y-evidence.ts`). 문서 검사가 보지 않는다.
## 3. 작업 이력·리뷰
## 3. 기록 문서의 머리 블록
템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다.
복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 `README.md`의
"Files you can delete after copying" 절에 있다.
| 경로 | 내용 |
|---|---|
| [`superpowers/`](superpowers/) | 과거 작업 계획과 스펙 |
| [`reviews/`](reviews/) | 리뷰 결과. 리뷰 가이드와 실행 체크리스트는 2026-11-06에 design-docs 저장소로 옮겼고, 여기에는 정본 위치를 알려 주는 포인터 두 개만 있다. `reviews/adapters/INVENTORY.md`만 게이트가 읽는다. `reviews/adapters/`는 지우지 않는다: INVENTORY의 행과 `operations/adapter-remediation-ledger.md`가 그 안의 리뷰로 링크한다 |
| [`history/`](history/) | 끝난 작업의 계획서(`history/plans/`)와 증거(`history/evidence/`). 파일마다 맨 위에 머리 블록이 있다(아래 4절). 2026-11-07에 루트에서 옮겼다: `tasks/` → `history/plans/2026-09-25-review-fix-round/`, `.superpowers/sdd/2026-08-01-runtime-correctness-remediation/` → `history/evidence/2026-08-01-runtime-correctness-remediation/`. 그때의 기록 문서(`superpowers/plans/`, `reviews/2026-09-25-maturity-review/`, 루트 `SPEC.md`)는 옛 경로로 가리킨다. 기록이라 고치지 않는다 |
| [`../SPEC.md`](../SPEC.md) | 2026-09-25 리뷰 수정 라운드의 요구사항. 그 라운드는 0.2.0(`CHANGELOG.md`)으로 끝났다. 27~37줄 「공통 완료 기준」을 작업 매뉴얼로 옮긴 뒤 같은 라운드의 계획서 옆(`history/plans/2026-09-25-review-fix-round/`)으로 옮긴다 |
## 4. 기록 문서의 머리 블록
`history/` 아래 `.md` 파일은 맨 위에 이 블록을 둔다. 블록을 빼면 쓴 때의 원문이다. 본문은
고치지 않고 블록의 칸만 고친다. 형식의 정본은 design-docs 저장소의
`conventions/docs-system.md` 4절이다.
`design/`, `history/`, `adr/`의 `.md` 파일은 맨 위에 이 블록을 둔다. 블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다).
```text
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 계획서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 끝남
- 작성일: 2026-09-25
- 상태: 구현됨
- 작성일: 2026-08-01
- 요약: 한국어 한 문장
- 현재 정본: 지금 동작을 설명하는 문서나 코드의 경로. 없으면 「없음 — 이유」
- 현재 정본: `docs/architecture/layers.md`
- 대체됨: `docs/design/<대체한 문서>.md`
<!-- 머리 블록 끝 -->
```
- 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: `history/plans/` 계획서, `history/evidence/` 증거.
- 상태: 계획서는 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함, 증거는 보관.
- 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: `design/` 설계서, `history/plans/` 계획서, `history/evidence/` 증거. 결정 기록(`adr/`)의 둘째 줄은 `> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.`다. VD는 처음부터 한국어로 썼고 번역하지 않았다. 나중에 본문을 번역하면 「원문이다」 대신 「내용이다(번역은 뜻을 바꾸지 않았다)」로 쓴다.
- 상태는 종류마다 고정 어휘다.
| 종류 | 상태 |
| --- | --- |
| 설계서 | 제안 · 채택 · 구현됨 · 보류 · 폐기 · 대체됨 · 확인 안 함 |
| 결정 기록 | 제안 · 채택 · 채택(보완) · 폐기 · 대체됨 |
| 계획서 | 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함 |
| 증거 | 보관 |
- 「현재 정본」은 지금 동작을 설명하는 살아 있는 문서나 코드의 경로다. 여럿이면 쉼표로 잇고, 없으면 「없음 — 이유」로 쓴다.
- 「대체됨」은 상태가 대체됨일 때 대체한 문서의 경로다. 이 문서가 다른 문서를 대체했으면 「대체」 칸에 그 경로를 쓴다.
- 상태는 그 결정을 바꾼 변경이 같이 바꾼다. 기능을 지우는 커밋이 그 기능의 설계서를 「폐기」나 「대체됨」으로 바꾼다. 새 설계서·결정 기록은 처음부터 블록을 달고 쓴다(보통 「제안」).
- 2026-11-08에 처음 단 상태는 원래 상태 줄을 기계로 바꾼 값이다: Accepted·Approved·확정·승인·정본 → 채택, Superseded → 대체됨, Proposed → 제안, implemented → 구현됨, 날짜가 붙은 보완 메모가 본문에 있는 VD → 채택(보완). 상태 줄이 없던 설계서와 체크 상자가 모두 표시되지 않은 계획서는 「확인 안 함」이다.
- `.md`가 아닌 파일(레인 준비 셸 스크립트)에는 달지 않는다. 같은 폴더 문서의 블록이 그 파일을 설명한다.
- 리뷰(`reviews/`)는 아직 머리 블록을 요구하지 않는다.
## 4. 문서와 코드를 같은 변경에서 고친다
- 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법: `git grep -n '<바꾼 이름>' -- '*.md'`.
- 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·명령은 `CHANGELOG.md`에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면 `> 이력` 으로 시작하는 인용 블록 안에 쓴다. 문서 검사는 그 블록의 문체를 보지 않는다.
- 숫자·버전을 복사하지 않는다. 프레임워크 버전은 `package.json`과 `.nvmrc`, 게이트 목록은 `config/ci/gates.json`, recipe 목록은 `config/recipes/frontend-capability-recipes.json`, adapter 파일 목록은 `reviews/adapters/INVENTORY.md`를 가리킨다.
- 루트 README는 「프로젝트 구조」와 「문서 지도」 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docs `conventions/docs-system.md` 6.1절이고, 문서 검사의 `readme`가 그 목록(`scripts/lib/docs-system.ts`의 `README_SECTIONS`)을 본다.
## 5. 문서 검사
`verify:documentation`(FE-GATE-017)이 위 규칙 중 기계로 볼 수 있는 것을 본다. 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 script를 지우는 변경이 그 변경과 상관없는 문서를 낡게 만든다.
- pull request에서 실패하게 하는 곳은 merge 단계 FE-GATE-005다. 그 안의 `tests/unit/documentation-readiness.test.ts`가 이 repo를 그대로 두고 `verify:documentation`을 한 번 돌린다. FE-GATE-017 job 자체는 documentation 단계를 고른 workflow_dispatch에서만 돈다(`config/ci/gates.json`의 `documentation_gate`).
| 검사 | 보는 것 |
| --- | --- |
| `language` | 살아 있는 문서와 결정 기록 본문이 한국어인가. 코드·명령·경로·링크·인용은 세지 않고, 영어 낱말 3개 이상이면서 한글 덩어리 비율 0.3 미만이면 영어다(보고 언어 훅 H11과 같은 판정) |
| `head` | 기록과 결정 기록 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 지금 있는지 |
| `document references` | 살아 있는 문서의 인라인 코드·셸 코드 블록 안 repo 경로, 마크다운 링크 대상, package script 이름, FE-GATE ID가 지금 있는가. 짝 백엔드 경로는 `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다 |
| `number` | 살아 있는 문서가 프레임워크 버전이나 게이트·recipe·adapter 개수를 복사했는가. 결정 기록, 기록, `CHANGELOG.md`는 보지 않는다 |
| `map` | 이 README의 1절 지도가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 |
| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 |
| `style` | 살아 있는 문서와 결정 기록의 문장 끝이 높임(「~합니다」「~하세요」)이 아닌가. 코드, 따옴표·낫표 안 인용, `> 이력` 블록은 보지 않는다 |
- 그 밖에 같은 명령이 루트 README의 런타임 변수 표, 입구 문서의 `src/` 폴더 설명(`architecture/layers.md` 표와 글자가 같아야 한다), 수동 접근성 기록의 범위, 2026-07-18 도식 리뷰 사본 둘의 일치를 본다.
- 규칙과 판정의 정본은 `scripts/lib/docs-system.ts`(검사 여섯)와 `scripts/verify-documentation-readiness.ts`(참조와 그 밖의 검사)다. 백엔드 템플릿의 문서 검사기(그 repo의 `check-docs.py`)를 같은 이름·문턱으로 옮긴 것이다.
- 검사 자신의 시험: `tests/unit/docs-system.test.ts`, `tests/unit/documentation-readiness.test.ts`.
- 예외 목록 `scripts/docs-system-exceptions.txt`는 비어 있고 줄기만 한다. 목록에 새 줄을 더하면 실패한다(줄마다 `scripts/lib/docs-system.ts`의 `FROZEN`에 지문이 있어야 하는데, `FROZEN`이 비어 있다). 기준선을 늘리는 것은 규칙을 바꾸는 일이라 소유자 결정이 필요하다.
- 복사한 프로젝트가 지운 기록(`history/`, `reviews/`)과 지운 샘플 기능의 경로는 없어도 된다. git이 무시하는 생성 산출물도 없어도 된다.
- 설명·수치가 코드와 맞는지는 검사하지 않는다. 리뷰가 표본으로 대조한다.
@@ -1,42 +1,44 @@
# Frontend Application Foundation
# 프론트엔드 애플리케이션 기반(Frontend Application Foundation)
This repository is not treated as a minimal React project template and it is not
an independent general-purpose SDK. Its architectural role is:
이 repo를 최소한의 React 프로젝트 템플릿으로 보지 않는다. 독립된 범용 SDK도
아니다.
아키텍처에서 맡는 역할은 다음과 같다:
> Frontend Application Foundation = Starter / Composition Skeleton + Reusable Capability Platform
> Frontend Application Foundation = 시작 골격(Starter / Composition Skeleton) + 재사용 capability 플랫폼(Reusable Capability Platform)
The starter side owns bootstrap, routing, providers, project conventions and
the `create:feature` command that writes a feature; it ships no sample feature. The capability side owns reusable technical
problems such as HTTP execution, Server State, authentication boundaries,
IndexedDB/OPFS, Cache Storage, realtime, browser RPC, transfer and diagnostics.
시작 골격 쪽은 bootstrap, 라우팅, provider, 프로젝트 규약, feature를 만들어
주는 `create:feature` 명령을 맡는다. 예시 feature는 싣지 않는다. capability
쪽은 재사용할 기술 문제를 맡는다. HTTP 실행, Server State, 인증 경계,
IndexedDB/OPFS, Cache Storage, realtime, 브라우저 RPC, 전송(transfer), 진단
같은 것이다.
The cost of a sophisticated capability is acceptable only when product features
do not have to understand that internal sophistication.
정교한 capability의 비용은 제품 feature가 그 내부의 정교함을 몰라도 될 때만
받아들일 수 있다.
## Hybrid architecture
## 하이브리드 아키텍처
`src/` has nine top-level folders. The descriptions match the table in
[the layer contract](./layers.md), which also names every import rule.
`src/`에는 최상위 폴더가 아홉 개 있다. 설명은 [계층 계약](./layers.md)의
표와 같다. 그 문서는 모든 import 규칙도 적는다.
Platform code is horizontal:
platform 코드는 가로(수평)로 놓인다:
- `src/bootstrap` — the composition root: runtime configuration, concrete adapter construction and the React mount
- `src/presentation` — generic UI and the inbound adapter: routes, layouts, the design system, pages and providers
- `src/adapters` — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more
- `src/application` — generic use cases, ports, policies and view-models
- `src/contracts` — shared vocabulary and registries read by several layers, the workers and the build and release scripts
- `src/platform` — product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence
- `src/bootstrap` — 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트
- `src/presentation` — 범용 UI와 inbound adapter: 라우트, 레이아웃, 디자인 시스템, 페이지, provider
- `src/adapters` — application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등
- `src/application` — 범용 use case, 포트, 정책, view-model
- `src/contracts` — 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registry
- `src/platform` — 어느 폴더든 쓸 수 있는 제품 중립 기본 요소: 예산, 실행 context, 복원력, telemetry 파이프라인, 오류 envelope, 릴리스 정합성
Ownership declarations group features into deployable units:
소유 선언이 feature를 배포 단위로 묶는다:
- `src/apps` — deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces
- `src/contexts` — bounded contexts: each `context-module.ts` declares its app, route root and feature budget
- `src/apps` — 배포 단위 앱: 각 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다
- `src/contexts` — bounded context: 각 `context-module.ts`가 소속 앱, 라우트 루트, 기능 예산을 선언한다
Product business code is vertical:
제품 비즈니스 코드는 세로(수직)로 놓인다:
- `src/features` — removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`)
- `src/features` — 지울 수 있는 수직 slice(`src/features/<id>/{domain,application,contracts,adapters,presentation}`)와 설치된 기능 목록(`src/features/*.ts`)
Inside one feature:
feature 하나 안에는 다음이 있다:
- `features/<feature>/domain`
- `features/<feature>/application`
@@ -44,7 +46,7 @@ Inside one feature:
- `features/<feature>/adapters`
- `features/<feature>/presentation`
The dependency model is:
의존성 모델은 다음과 같다:
Domain / Use case
|
@@ -63,143 +65,144 @@ The dependency model is:
v
Browser / network / native API
A use case never imports a platform adapter. Generic binding happens in the
feature adapter/composition seam.
use case는 platform adapter를 절대 import하지 않는다. 범용 바인딩은 feature의
adapter·조립 이음매(seam)에서 일어난다.
## Capability-specific typed bindings
## capability별 타입 바인딩
Do not introduce one universal `Repository<TKey, TValue>` abstraction for HTTP,
storage, realtime and transfer. Their lifecycle and failure semantics differ.
HTTP, storage, realtime, transfer를 하나의 범용 `Repository<TKey, TValue>`
추상화로 묶지 않는다. 넷은 lifecycle과 실패의 의미가 서로 다르다.
A reusable capability boundary is composed from:
재사용 capability 경계는 다음으로 조립한다:
- generic input/output types,
- feature-owned mapper or codec,
- feature-selected policy,
- one capability-specific runtime.
- 범용 입력·출력 타입,
- feature가 소유한 mapper 또는 codec,
- feature가 고른 정책,
- capability 전용 runtime 하나.
The HTTP path is the first concrete example.
`src/adapters/http/feature-http-binding.ts` owns transport/outcome
normalization. A feature `create:feature` writes contributes only:
HTTP 경로가 첫 구체 예다.
`src/adapters/http/feature-http-binding.ts`가 전송과 결과의 정규화를 맡는다.
`create:feature`가 만든 feature가 내놓는 것은 다음뿐이다:
- operation ID,
- route ID,
- exact request input type,
- exact success value type,
- wire-to-domain mapper.
- 정확한 요청 입력 타입,
- 정확한 성공 값 타입,
- wire 형식을 domain으로 바꾸는 mapper.
The feature gateway therefore does not reimplement timeout, cancellation,
transport failure, authentication failure or contract-violation projection.
그래서 feature gateway는 timeout, 취소, 전송 실패, 인증 실패, contract 위반
투영을 다시 구현하지 않는다.
Storage, realtime and transfer may gain their own typed binders only after
actual feature repetition demonstrates the need. They must not be forced
through the HTTP abstraction.
storage, realtime, transfer는 실제 feature에서 반복이 생겨 필요가 드러난
뒤에야 자기 타입 바인더를 가질 수 있다. 이 셋을 HTTP 추상화에 억지로
끼우면 안 된다.
## Custom adapter escape hatch
## 직접 만드는 adapter라는 탈출구
A product feature uses a reusable capability when the capability preserves the
business requirement.
제품 feature는 재사용 capability가 비즈니스 요구를 지켜 줄 때 그 capability를
쓴다.
If a platform contract would require changing or weakening the business model,
the feature implements a custom outbound adapter behind the same application
port. The architecture boundary remains stable; platform reuse is optional.
platform contract 때문에 비즈니스 모델을 바꾸거나 약하게 해야 한다면, feature는
같은 application port 뒤에 직접 만든 outbound adapter를 구현한다. 아키텍처
경계는 그대로다. platform 재사용은 선택이다.
## Feature installation
## feature 설치
A feature owns its contract, runtime and adapter contributions.
feature는 자기 contract, runtime, adapter contribution을 소유한다.
Central installed catalogs are aggregation points only:
중앙의 설치 목록(catalog)은 모으는 지점일 뿐이다:
- `installed-product-manifest.ts`: which product features are compiled/selected
- `installed-feature-contracts.ts`: boot-time contract aggregation (routes,
route runtime contracts, invalidation) from the feature declarations
- `installed-feature-adapters.ts`: application-input loaders, one per active
feature, run when the router enters the feature's routes (15-01)
- `installed-contract-contributions.ts`: declared contract packages and the
registry the HTTP executor resolves against, filled as features load
- `installed-feature-runtime-registries.ts`: loads every runtime half and
composes the contract contributions, the FE-REG-API rows projected from
them and the FE-REG-SCHEMA registry; the platform overview page calls it
after it draws its title (1103/15-01), the boot never does
- `loaded-feature-runtimes.ts`: the same registries as module constants (top-
level await) for Node scripts, tests and registry governance; nothing under
`src` may import it (`boot-does-not-load-every-feature-runtime`)
- `installed-product-manifest.ts`: 어떤 제품 feature를 컴파일하고 고르는지
- `installed-feature-contracts.ts`: feature 선언에서 boot 시점 contract(라우트,
라우트 runtime contract, 무효화)를 모은다
- `installed-feature-adapters.ts`: 활성 feature마다 하나씩 있는
application-input loader. router가 그 feature의 라우트에 들어갈 때
실행된다(15-01)
- `installed-contract-contributions.ts`: 선언된 contract 패키지와, HTTP
executor가 해석할 때 쓰는 registry. feature가 로드될 때 채워진다
- `installed-feature-runtime-registries.ts`: 모든 runtime 쪽 절반을 불러와
contract contribution, 거기서 투영한 FE-REG-API 행, FE-REG-SCHEMA registry를
조립한다. platform 개요 페이지가 제목을 그린 뒤 이 파일을 부른다
(1103/15-01). boot는 절대 부르지 않는다
- `loaded-feature-runtimes.ts`: 같은 registry를 모듈 상수(top-level await)로
둔 것. Node 스크립트, 테스트, registry 관리(governance)가 쓴다. `src` 아래
어떤 코드도 이 파일을 import하면 안 된다
(`boot-does-not-load-every-feature-runtime`)
Feature-specific composition belongs under the feature itself. Central
catalogs must not grow feature-specific branching logic.
feature 전용 조립은 그 feature 아래에 둔다. 중앙 목록에 feature별 분기 로직을
늘리면 안 된다.
Adapter contributions declare the platform capabilities they consume through
`needs`. The generic contribution seam in
`src/features/feature-adapter-contribution.ts` derives the context from that
list, so an HTTP-only feature cannot reach IndexedDB and an IndexedDB-only
feature does not receive the HTTP executor. It also binds
`featureId -> ApplicationFeatureInputs[featureId]` at the contribution
definition site instead of recovering that relationship with a final catalog
cast.
adapter contribution은 자기가 쓰는 platform capability를 `needs`로 선언한다.
`src/features/feature-adapter-contribution.ts`의 범용 contribution 이음매가 그
목록에서 context를 만든다. 그래서 HTTP만 쓰는 feature는 IndexedDB에 닿지
못한다. IndexedDB만 쓰는 feature는 HTTP executor를 받지 않는다. 이 이음매는
`featureId -> ApplicationFeatureInputs[featureId]` 관계도 contribution을
정의하는 자리에서 묶는다. 마지막에 목록을 타입 캐스트해서 그 관계를 되찾지
않는다.
A contribution becomes composable only through
`defineFeatureAdapterContribution()`. That factory adds the private
contribution brand required by `composeFeatureAdapterInputs()`; a raw object
with the same visible fields is rejected by TypeScript and checked again at
runtime. The negative type fixture
`invalid-direct-feature-composition.ts` is part of FE-GATE-003 so this
authority cannot be bypassed by calling the composer directly.
contribution은 `defineFeatureAdapterContribution()`을 거쳐야만 조립할 수
있다. 이 factory는 `composeFeatureAdapterInputs()`가 요구하는 비공개
contribution brand를 붙인다. 겉으로 보이는 필드가 같은 날 객체는 TypeScript가
거부하고, runtime에서도 다시 검사한다. 음성 타입 fixture
`invalid-direct-feature-composition.ts`가 FE-GATE-003에 들어 있다. 그래서
composer를 직접 불러 이 권한을 우회할 수 없다.
For IndexedDB-backed features, `createIndexedDbRepositoryProvider()` is the
composition helper that maps feature-owned repository identities to typed
`IndexedDbRepositoryPort` instances. It does not create a universal storage
repository or move dataset/migration/lifecycle policy into the feature.
IndexedDB를 쓰는 feature에서는 `createIndexedDbRepositoryProvider()`가 조립
헬퍼다. 이 헬퍼는 feature가 소유한 repository 식별자를 타입이 붙은
`IndexedDbRepositoryPort` 인스턴스에 연결한다. 범용 storage repository를
만들지 않는다. dataset·migration·lifecycle 정책을 feature로 옮기지도 않는다.
The repository now has two executable contribution shapes:
지금 repo에는 실행 가능한 contribution 모양이 둘 있다:
- A feature `create:feature` writes: `needs: ["http", "telemetry"]`
- The Local Draft consumer: `needs: ["indexedDb"]`
- `create:feature`가 만드는 feature: `needs: ["http", "telemetry"]`
- Local Draft consumer: `needs: ["indexedDb"]`
Local Draft is a test fixture (`tests/fixtures/indexeddb-consumer`) used to
prove the second capability shape; it is not a feature of the product. Its
browser-capability test composes the feature over the real
`createIndexedDbRuntime` and native IndexedDB, proving that this seam is not
limited to an in-memory contract fixture.
Local Draft는 두 번째 capability 모양을 증명하는 테스트
fixture(`tests/fixtures/indexeddb-consumer`)다. 제품의 feature가 아니다. 그
browser-capability 테스트는 실제 `createIndexedDbRuntime`과 브라우저 자체
IndexedDB 위에서 feature를 조립한다. 이 이음매가 메모리 안 contract fixture에만
묶이지 않는다는 것을 이 테스트가 증명한다.
The bootstrap does not build `indexedDb`: IndexedDB is an opt-in reference
runtime (`productionComposition: false` in
`config/recipes/frontend-capability-recipes.json`). The composition example is
`recipes/frontend-capabilities/indexeddb-feature-capability.ts`
(`createLocalDraftIndexedDbCapability`, exercised by
`tests/recipes/indexeddb-feature-capability.test.ts`). A product that installs a
feature with `needs: ["indexedDb"]` copies it and returns `indexedDb` from the
product-owned `src/bootstrap/product-composition.ts`. Until it does, the feature
capabilities in `src/bootstrap/runtime-adapters.ts` fail the app typecheck, and
`composeFeatureAdapterInputs()` rejects the composition with
`feature <id> needs indexedDb, which the host did not provide`.
bootstrap은 `indexedDb`를 만들지 않는다. IndexedDB는 골라야 켜지는(opt-in)
참조 runtime이다(`config/recipes/frontend-capability-recipes.json`의
`productionComposition: false`). 조립 예시는
`recipes/frontend-capabilities/indexeddb-feature-capability.ts`다
(`createLocalDraftIndexedDbCapability`. 이 함수는
`tests/recipes/indexeddb-feature-capability.test.ts`가 실행해 본다).
`needs: ["indexedDb"]`인 feature를 설치하는 제품은 이 예시를 복사한다. 그리고
제품이 소유한 `src/bootstrap/product-composition.ts`에서 `indexedDb`를
돌려준다. 그 전까지는 `src/bootstrap/runtime-adapters.ts`의 feature
capability가 앱 타입체크에서 실패한다. 그리고 `composeFeatureAdapterInputs()`가
`feature <id> needs indexedDb, which the host did not provide`로 조립을
거부한다.
The same file is where a product adds any other capability and the
credential provider for a product auth profile. The capability's type goes in
the product-owned `src/features/product-capabilities.ts`
(`ProductFeaturePlatformCapabilities`, which `FeaturePlatformCapabilities`
extends), so every typecheck program that sees a feature sees it
(`tests/unit/product-extension-typecheck.test.ts`). The composition root keeps the order: scope fence, `ANONYMOUS`
profile, product provider, session, scope fence again
(`tests/unit/runtime-adapters-credential-order.test.ts`). A product that owns
the session itself (a BFF whose session is an httpOnly cookie) returns its
session owner from `composeProductSessionOwner` in the same file. It is asked
first, before `http` exists, only when `AUTH_MODE` is `external`, and it comes
before the host's `__CA_FRONTEND_AUTH_OWNER__`; `null` leaves the session to
that global. Its context (`src/bootstrap/product-session-owner-context.ts`)
carries a `fetch` with one deadline over the whole exchange, the page for a
sign-in redirect, the page's session storage for that redirect only, and
`readCookie`. Product auth profiles, runtime-config keys and the keys'
FE-REG-ENV rows go in `src/contracts/product-contracts.ts`; each joins the
template's registry under the same checks
제품이 다른 capability를 더하는 곳도 같은 파일이다. 제품 인증 profile의
credential provider를 더하는 곳도 이 파일이다. capability의 타입은 제품이
소유한 `src/features/product-capabilities.ts`에 둔다
(`ProductFeaturePlatformCapabilities`. `FeaturePlatformCapabilities`가 이
타입을 확장한다). 그래서 feature를 보는 모든 타입체크 프로그램이 이 타입도
본다(`tests/unit/product-extension-typecheck.test.ts`). composition root는 다음
순서를 지킨다: scope fence, `ANONYMOUS` profile, 제품 provider, session, 다시
scope fence(`tests/unit/runtime-adapters-credential-order.test.ts`). session을
직접 소유하는 제품(session이 httpOnly 쿠키인 BFF)은 같은 파일의
`composeProductSessionOwner`에서 자기 session owner를 돌려준다. 이 함수는
`AUTH_MODE`가 `external`일 때만 불린다. 불릴 때는 `http`가 생기기 전에 가장
먼저 불리고, host의 `__CA_FRONTEND_AUTH_OWNER__`보다 앞선다. `null`을
돌려주면 session을 그 전역 값에 맡긴다. 이 함수의 context
(`src/bootstrap/product-session-owner-context.ts`)에는 다음이 들어 있다: 교환
전체에 deadline 하나를 거는 `fetch`, 로그인 redirect에 쓸 페이지, 그
redirect에만 쓰는 페이지의 session storage, `readCookie`. 제품 인증 profile,
runtime-config 키, 그 키의 FE-REG-ENV 행은 `src/contracts/product-contracts.ts`에
둔다. 각각 같은 검사를 거쳐 템플릿의 registry에 합류한다
(`tests/unit/product-composition-fixture.test.ts`).
## Presentation consumer surface
## presentation 소비 표면
`ApplicationProvider` remains the composition root for presentation, but new
consumers should not navigate a root `ApplicationApi` service locator.
`ApplicationProvider`는 계속 presentation의 composition root다. 하지만 새
소비 코드는 루트 `ApplicationApi` service locator를 뒤져서 기능을 찾아가면
안 된다.
Use the narrow hooks in
`src/presentation/providers/application-provider.tsx`:
`src/presentation/providers/application-provider.tsx`의 좁은 hook을 쓴다:
- `useApplicationSession`
- `useApplicationPreferences`
@@ -208,100 +211,96 @@ Use the narrow hooks in
- `useApplicationRecovery`
- `useApplicationFeature`
`useApplication` exists only as a deprecated compatibility escape hatch.
`useApplication`은 deprecated된 호환용 탈출구로만 남아 있다.
## Canonical imports
## 정식 import 경로
New feature code should use capability public entry points rather than deep
runtime modules. For HTTP the canonical path is
`src/adapters/http/index.ts`.
새 feature 코드는 깊은 runtime 모듈 대신 capability의 공개 진입점을 쓴다.
HTTP의 정식 경로는 `src/adapters/http/index.ts`다.
Compatibility re-exports may exist during a migration window, but they must be
marked as compatibility/deprecated paths and should not expand into an
unbounded public barrel.
옮기는 기간에는 호환용 재수출이 있을 수 있다. 하지만 그 경로에는 호환용·
deprecated 경로라는 표시를 해야 한다. 그리고 끝없이 커지는 공개 barrel로
늘어나면 안 된다.
## Policy ownership
## 정책 소유
Duplication is judged by ownership, not by syntax percentage.
중복은 문법이 겹치는 비율이 아니라 소유로 판단한다.
Small local validators can remain duplicated when locality improves auditing.
Business or concurrency policy must have one owner. For example the reference
create mutation keeps definition ID, idempotency requirement, duplicate policy
and invalidation policy in one feature-owned definition and binds only
`scope` and `execute` per usage site.
가까이 두는 편이 감사하기 쉬우면 작은 로컬 검증기는 중복으로 남겨도 된다.
비즈니스 정책이나 동시성 정책은 owner가 하나여야 한다. 예를 들어 참조 create
mutation은 정의 ID, 멱등성 요구, 중복 정책, 무효화 정책을 feature가 소유한
정의 하나에 둔다. 사용하는 자리마다 묶는 것은 `scope`와 `execute`뿐이다.
## Runtime decomposition rule
## runtime 분해 규칙
Large runtime files are not split by line count.
큰 runtime 파일을 줄 수로 나누지 않는다.
Extract a boundary when it has its own state machine, lifecycle owner, failure
model or compensation/recovery responsibility. Candidate seams include:
경계에 자기만의 상태 기계, lifecycle owner, 실패 모델, 보상·복구 책임이
있으면 그 경계를 떼어 낸다. 떼어 낼 후보 이음매는 다음과 같다:
- connection/open/upgrade lifecycle,
- transaction ownership,
- migration state machine,
- reconnect/backoff and heartbeat,
- subscription ownership,
- retry/deadline/cancellation ownership,
- settlement/reconciliation/cleanup.
- 연결·열기·업그레이드 lifecycle,
- 트랜잭션 소유,
- migration 상태 기계,
- 재연결·backoff와 heartbeat,
- 구독 소유,
- 재시도·deadline·취소 소유,
- 정산(settlement)·조정(reconciliation)·정리(cleanup).
A cohesive 2,000-line state machine can remain together. A 300-line file with
multiple lifecycle owners is a better extraction candidate.
응집된 2,000줄짜리 상태 기계는 한데 둬도 된다. lifecycle owner가 여럿인
300줄짜리 파일이 더 나은 분리 후보다.
### Current runtime boundary audit
### 지금 runtime 경계 점검
The current large-runtime inventory was reviewed using that rule.
지금 있는 큰 runtime 목록을 이 규칙으로 점검했다.
- IndexedDB remains large, but connection, transaction, migration, maintenance
and failure translation already have separate owners/modules.
- resumable upload already separates runtime policy, checkpoint persistence,
HTTP control-plane transport, part execution, cancellation and mutation
locking.
- realtime already separates reconnect policy/coordinator, event codec/consumer
and stream coordination.
- OPFS is separated into browser runtime, journal, byte-store, policy and worker
protocol/runtime responsibilities.
- HTTP V3 still owned retry eligibility/backoff inside the execution state
machine, so that responsibility moved to
`src/adapters/http/http-retry-lifecycle.ts`.
- IndexedDB는 여전히 크다. 하지만 연결, 트랜잭션, migration, 유지보수, 실패
변환은 이미 owner·모듈이 따로 있다.
- 이어 올리기(resumable upload)는 이미 runtime 정책, checkpoint 저장, HTTP
제어 평면 전송, 조각(part) 실행, 취소, mutation 잠금을 나눠 두었다.
- realtime은 이미 재연결 정책·조정자, 이벤트 codec·소비자, 스트림 조정을
나눠 두었다.
- OPFS는 브라우저 runtime, journal, byte-store, 정책, worker 프로토콜·runtime
책임으로 나뉘어 있다.
- HTTP V3는 재시도 가능 여부와 backoff를 실행 상태 기계 안에서 여전히 소유하고
있었다. 그래서 그 책임을 `src/adapters/http/http-retry-lifecycle.ts`로
옮겼다.
No other runtime is split merely because of its line count.
다른 runtime은 줄 수만 보고 나누지 않았다.
## Consumer quality metrics
## 소비 품질 지표
Before adding another abstraction, implement or model multiple real feature
uses and measure:
추상화를 하나 더 들이기 전에, 실제 feature 사용 사례 여럿을 구현하거나
모델링하고 다음을 잰다:
- feature-owned adapter LOC,
- repeated platform glue,
- number of platform-internal types exposed to the feature,
- central catalog edits,
- files changed for one normal query/command,
- whether native browser/network APIs leak into the feature.
- feature가 소유한 adapter LOC,
- 반복되는 platform 접착 코드(glue),
- feature에 드러나는 platform 내부 타입 수,
- 중앙 목록 수정 횟수,
- 평범한 query/command 하나에 바뀌는 파일 수,
- 브라우저·네트워크 기본 API가 feature로 새어 나오는지.
The target feature-development path is:
목표로 하는 feature 개발 경로는 다음과 같다:
1. domain type and invariant,
1. domain 타입과 불변식,
2. use case,
3. port,
4. transport/storage schema plus mapper/codec,
5. capability binding,
4. 전송·저장 schema와 mapper/codec,
5. capability 바인딩,
6. presentation controller/page.
A product feature should not need to know the retry scheduler, abort ownership,
effect-certainty machinery, transaction leases, reconnect coordinator, OPFS
journal or provider lifecycle.
제품 feature는 재시도 스케줄러, abort 소유, 효과 확실성(effect-certainty) 장치,
트랜잭션 lease, 재연결 조정자, OPFS journal, provider lifecycle을 몰라도 돼야
한다.
The executable REST and IndexedDB consumer baselines are recorded in
[`capability-consumer-experience.md`](./capability-consumer-experience.md).
Contract placement and the global-vs-owner-local audit are recorded in
[`contract-ownership.md`](./contract-ownership.md).
실행 가능한 REST·IndexedDB 소비 기준선은
[`capability-consumer-experience.md`](./capability-consumer-experience.md)에
적혀 있다. contract를 어디에 둘지와, 전역에 둘지 owner 가까이 둘지 점검한
결과는 [`contract-ownership.md`](./contract-ownership.md)에 적혀 있다.
## Verification paths
## 검증 경로
Product-development verification, capability verification and release assurance
are intentionally separate. See
[`docs/testing/taxonomy.md`](../testing/taxonomy.md).
제품 개발 검증, capability 검증, release 보증은 일부러 나눠 두었다.
[`docs/testing/taxonomy.md`](../testing/taxonomy.md)를 본다.
Host-level CI-runner tests belong to `tests/system`, not `tests/unit`.
Reusable capability consumer contracts belong to `tests/contract`.
host 수준 CI runner 테스트는 `tests/unit`이 아니라 `tests/system`에 둔다.
재사용 capability의 소비 contract는 `tests/contract`에 둔다.
+112 -109
View File
@@ -1,119 +1,120 @@
# Clean Architecture layer contract
# Clean Architecture 계층 계약
Dependencies point inward: `presentation -> application -> contracts ->
platform`. Concrete adapters implement application-owned ports and are
assembled only in `src/bootstrap`.
의존성은 안쪽을 향한다: `presentation -> application -> contracts ->
platform`. 구체 adapter는 application이 소유한 port를 구현한다. 구체
adapter는 `src/bootstrap`에서만 조립된다.
## Top-level folders
## 최상위 폴더
`src/` has these nine folders and no others:
`src/`에는 아래 아홉 폴더만 있다:
| Folder | Owns |
| 폴더 | 맡는 것 |
| --- | --- |
| `src/bootstrap` | the composition root: runtime configuration, concrete adapter construction and the React mount |
| `src/apps` | deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces |
| `src/contexts` | bounded contexts: each `context-module.ts` declares its app, route root and feature budget |
| `src/features` | removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`) |
| `src/presentation` | generic UI and the inbound adapter: routes, layouts, the design system, pages and providers |
| `src/adapters` | reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more |
| `src/application` | generic use cases, ports, policies and view-models |
| `src/contracts` | shared vocabulary and registries read by several layers, the workers and the build and release scripts |
| `src/platform` | product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence |
| `src/bootstrap` | 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트 |
| `src/apps` | 배포 단위 앱: 각 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다 |
| `src/contexts` | bounded context: 각 `context-module.ts`가 소속 앱, 라우트 루트, 기능 예산을 선언한다 |
| `src/features` | 지울 수 있는 수직 slice(`src/features/<id>/{domain,application,contracts,adapters,presentation}`)와 설치된 기능 목록(`src/features/*.ts`) |
| `src/presentation` | 범용 UI와 inbound adapter: 라우트, 레이아웃, 디자인 시스템, 페이지, provider |
| `src/adapters` | application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등 |
| `src/application` | 범용 use case, 포트, 정책, view-model |
| `src/contracts` | 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registry |
| `src/platform` | 어느 폴더든 쓸 수 있는 제품 중립 기본 요소: 예산, 실행 context, 복원력, telemetry 파이프라인, 오류 envelope, 릴리스 정합성 |
Domain code lives inside a feature (`src/features/<id>/domain`). There is no
top-level domain folder. If a project adds one, `domain-is-framework-neutral`
and `concrete-adapters-compose-only-in-bootstrap` already cover it.
domain 코드는 feature 안(`src/features/<id>/domain`)에 있다. 최상위 domain
폴더는 없다. 프로젝트가 그런 폴더를 더해도 `domain-is-framework-neutral`과
`concrete-adapters-compose-only-in-bootstrap`이 이미 그 폴더를 다룬다.
`src/adapters/platform` is the adapter kernel (below). It is not
`src/platform`.
`src/adapters/platform`은 adapter kernel(아래 절)이다. `src/platform`과는
다른 폴더다.
Where a shared type or primitive goes is decided in
[contract ownership](./contract-ownership.md).
공용 타입이나 기본 요소를 어디에 둘지는
[contract 소유권](./contract-ownership.md)에서 정한다.
## Rules
## 규칙
Each row is one `forbidden` rule in `.dependency-cruiser.json`, by its `name`.
"Forbids" lists what code under "Applies to" must not import.
각 행은 `.dependency-cruiser.json`의 `forbidden` 규칙 하나이고, 그 규칙의
`name`으로 적는다. 「금지」 칸은 「적용 대상」 칸의 코드가 import하면 안 되는
것이다.
| Rule | Applies to | Forbids |
| 규칙 | 적용 대상 | 금지 |
| --- | --- | --- |
| `domain-is-framework-neutral` | a top-level domain folder (none today) | application, presentation, adapters, bootstrap, React, TanStack |
| `domain-is-framework-neutral` | 최상위 domain 폴더(지금은 없다) | application, presentation, adapters, bootstrap, React, TanStack |
| `application-does-not-know-concrete-runtime` | `src/application` | presentation, adapters, bootstrap, React, TanStack |
| `presentation-does-not-know-adapters` | `src/presentation`, except `adapters/query` | adapters, bootstrap, TanStack |
| `page-templates-own-layout-only` | `src/presentation/templates` | application, adapters, bootstrap, the presentation query adapter, TanStack. Templates take data and actions as props |
| `icon-vendor-is-facade-only` | all of `src`, except the lucide vendor facade | `lucide-react` |
| `zod-is-reached-through-contracts-zod` | all of `src`, except `src/contracts/zod.ts` | `zod` and its subpaths (`zod/v4`) |
| `design-system-is-reached-through-its-index` | code outside the design system and its named facades | design-system files other than its `index.ts` |
| `presentation-does-not-know-adapters` | `src/presentation`. 단 `adapters/query`는 제외 | adapters, bootstrap, TanStack |
| `page-templates-own-layout-only` | `src/presentation/templates` | application, adapters, bootstrap, presentation query adapter, TanStack. template은 데이터와 action을 props로 받는다 |
| `icon-vendor-is-facade-only` | `src` 전체. 단 lucide vendor facade는 제외 | `lucide-react` |
| `zod-is-reached-through-contracts-zod` | `src` 전체. 단 `src/contracts/zod.ts`는 제외 | `zod`와 그 하위 경로(`zod/v4`) |
| `design-system-is-reached-through-its-index` | 디자인 시스템과 이름이 정해진 그 facade 밖의 코드 | 디자인 시스템의 `index.ts`가 아닌 디자인 시스템 파일 |
| `adapters-do-not-know-presentation` | `src/adapters` | presentation, bootstrap |
| `feature-domain-is-framework-neutral` | `src/features/<id>/domain` | application, presentation, adapters, bootstrap, any feature's application, adapters and presentation, React, TanStack |
| `feature-application-does-not-know-runtime` | `src/features/<id>/application` | presentation, adapters, bootstrap, any feature's adapters and presentation, React, TanStack |
| `feature-presentation-does-not-know-outbound-adapters` | `src/features/<id>/presentation` | adapters, bootstrap, any feature's adapters, TanStack |
| `feature-adapters-do-not-know-presentation` | `src/features/<id>/adapters` | presentation, bootstrap, any feature's presentation |
| `feature-domain-is-framework-neutral` | `src/features/<id>/domain` | application, presentation, adapters, bootstrap, 모든 feature의 application·adapters·presentation, React, TanStack |
| `feature-application-does-not-know-runtime` | `src/features/<id>/application` | presentation, adapters, bootstrap, 모든 feature의 adapters·presentation, React, TanStack |
| `feature-presentation-does-not-know-outbound-adapters` | `src/features/<id>/presentation` | adapters, bootstrap, 모든 feature의 adapters, TanStack |
| `feature-adapters-do-not-know-presentation` | `src/features/<id>/adapters` | presentation, bootstrap, 모든 feature의 presentation |
| `concrete-adapters-compose-only-in-bootstrap` | `src/application`, `src/presentation`, `src/contracts` | `src/adapters` |
| `external-contract-package-single-import-path` | all of `src`, except `src/features/<id>/contracts/*-contract-contribution.ts` | the generated `@org-contracts/*` service packages |
| `presentation-does-not-fetch-directly` | generic and feature presentation | the HTTP, realtime, service-worker, web-worker and storage adapters |
| `unselected-realtime-runtime-is-not-composed` | `src/bootstrap`, `src/features/installed-feature-*` | the realtime and Web Push adapters, which the template does not select |
| `generic-worker-has-no-network-or-credentials` | `src/adapters/web-worker` | the HTTP, realtime, auth and Web Push adapters |
| `external-contract-package-single-import-path` | `src` 전체. 단 `src/features/<id>/contracts/*-contract-contribution.ts`는 제외 | 생성된 `@org-contracts/*` 서비스 패키지 |
| `presentation-does-not-fetch-directly` | 범용 presentation과 feature presentation | HTTP, realtime, service-worker, web-worker, storage adapter |
| `unselected-realtime-runtime-is-not-composed` | `src/bootstrap`, `src/features/installed-feature-*` | 템플릿이 고르지 않은 realtime adapter와 Web Push adapter |
| `generic-worker-has-no-network-or-credentials` | `src/adapters/web-worker` | HTTP, realtime, auth, Web Push adapter |
| `service-worker-entry-is-not-page-code` | `src/adapters/service-worker` | presentation, bootstrap, React, TanStack |
| `contracts-do-not-know-application` | `src/contracts` | application, features. Contracts is the lower package and owns the vocabulary both read |
| `contracts-do-not-know-application` | `src/contracts` | application, features. contracts가 아래쪽 패키지이고, 둘이 함께 읽는 어휘를 소유한다 |
| `contracts-do-not-know-presentation-or-bootstrap` | `src/contracts` | presentation, bootstrap |
| `generic-presentation-does-not-compose-the-product` | `src/presentation`, except the files the rule lists | the installed-feature registries. Which features exist is a product decision owned by `src/bootstrap` |
| `boot-does-not-load-every-feature-runtime` | all of `src`, except the module itself | `src/features/loaded-feature-runtimes.ts` |
| `adapters-do-not-know-other-concrete-adapters` | each adapter group | another adapter group, except the adapter kernel |
| `adapter-groups-are-reached-through-their-barrel` | code outside `src/adapters` | adapter files other than a group's `index.ts` and the `storage/indexeddb` and `storage/opfs` sub-barrels |
| `features-do-not-import-other-features` | each feature | another feature |
| `contexts-do-not-import-other-contexts` | each context | another context |
| `feature-and-app-roots-do-not-reach-adapters` | every file in `src/features` outside a feature's `adapters/` folder (the root files and any folder that is not a layer, such as `support/`), `src/contexts`, `src/apps`, except the type-only `src/features/feature-adapter-contribution.ts` | `src/adapters` |
| `presentation-does-not-import-apps-or-contexts` | generic and feature presentation, except `src/presentation/routes/app-router.tsx`, which mounts the app's route tree | `src/apps`, `src/contexts` |
| `observability-vendors-live-behind-adapters` | code outside `src/adapters` | vendor telemetry SDKs |
| `platform-kernel-is-product-neutral` | `src/platform`, except `routing/`, which reads app descriptors by type | features, contexts, apps, adapters, bootstrap, presentation, application |
| `no-circular-dependencies` | all of `src` | import cycles |
| `generic-presentation-does-not-compose-the-product` | `src/presentation`. 단 규칙에 적힌 파일은 제외 | 설치된 feature registry. 어떤 feature가 있는지는 제품 결정이고 `src/bootstrap`이 소유한다 |
| `boot-does-not-load-every-feature-runtime` | `src` 전체. 단 그 모듈 자신은 제외 | `src/features/loaded-feature-runtimes.ts` |
| `adapters-do-not-know-other-concrete-adapters` | 각 adapter 그룹 | 다른 adapter 그룹. 단 adapter kernel은 제외 |
| `adapter-groups-are-reached-through-their-barrel` | `src/adapters` 밖의 코드 | 그룹의 `index.ts`와 `storage/indexeddb`·`storage/opfs` 하위 barrel이 아닌 adapter 파일 |
| `features-do-not-import-other-features` | 각 feature | 다른 feature |
| `contexts-do-not-import-other-contexts` | 각 context | 다른 context |
| `feature-and-app-roots-do-not-reach-adapters` | `src/features` 안에서 feature의 `adapters/` 폴더 밖에 있는 모든 파일(루트 파일과, `support/`처럼 계층이 아닌 모든 폴더), `src/contexts`, `src/apps`. 단 타입 전용인 `src/features/feature-adapter-contribution.ts`는 제외 | `src/adapters` |
| `presentation-does-not-import-apps-or-contexts` | 범용 presentation과 feature presentation. 단 앱의 라우트 트리를 마운트하는 `src/presentation/routes/app-router.tsx`는 제외 | `src/apps`, `src/contexts` |
| `observability-vendors-live-behind-adapters` | `src/adapters` 밖의 코드 | vendor telemetry SDK |
| `platform-kernel-is-product-neutral` | `src/platform`. 단 app descriptor를 타입으로 읽는 `routing/`은 제외 | features, contexts, apps, adapters, bootstrap, presentation, application |
| `no-circular-dependencies` | `src` 전체 | import 순환 |
`feature-and-app-roots-do-not-reach-adapters` exists because the graph checks
one edge at a time. Presentation may import those files, so a re-export of an
adapter there would carry the adapter into presentation with every other rule
passing.
`feature-and-app-roots-do-not-reach-adapters`가 있는 이유는 그래프가 간선을
하나씩만 검사하기 때문이다. presentation은 그 파일들을 import할 수 있다.
그래서 그 파일에서 adapter를 재수출하면, 다른 규칙이 모두 통과한 채로
adapter가 presentation까지 들어온다.
## The adapter kernel
## adapter kernel
`adapters-do-not-know-other-concrete-adapters` excludes the adapter kernel,
which is shared on purpose and is the only adapter code an adapter may reach
across a group for:
`adapters-do-not-know-other-concrete-adapters`는 adapter kernel을 예외로
둔다. kernel은 일부러 공유하는 코드다. adapter가 그룹을 넘어 가져다 쓸 수
있는 adapter 코드는 kernel뿐이다:
- `src/adapters/platform/**` — mechanisms more than one adapter group shares:
the system clock, the shared abort primitive, the bounded-capacity guard,
the IndexedDB connection and transaction helpers, `Retry-After` parsing and
the JSON member scanner. Two bootstrap-only platform services live there
too: the browser lifecycle runtime and the mutation intent factory (no
adapter imports them). A kernel file owns mechanics only, never names,
schemas, failure codes or observation shapes; the full list of what it must
never own is at the top of `indexeddb-connection.ts`
- `src/adapters/browser-file-storage/result.ts` — the browser-data result and
failure constructors
- `src/adapters/cross-context-invalidation/index.ts` — the cross-context
invalidation transport and its types. Any adapter may import it; today
`query-cache` does
- `src/adapters/platform/**` — 여러 adapter 그룹이 함께 쓰는 동작 장치:
시스템 시계, 공용 abort 기본 요소, 용량 상한 가드, IndexedDB 연결·트랜잭션
헬퍼, `Retry-After` 파싱, JSON 멤버 스캐너. bootstrap만 쓰는 platform
서비스 두 개도 여기 있다: 브라우저 lifecycle runtime과 mutation intent
factory다(adapter는 이 둘을 import하지 않는다). kernel 파일은 동작 방식만
소유한다. 이름, schema, 실패 코드, 관측 모양은 절대 소유하지 않는다.
kernel이 절대 소유하면 안 되는 것의 전체 목록은 `indexeddb-connection.ts`
맨 위에 있다
- `src/adapters/browser-file-storage/result.ts` — 브라우저 데이터의 결과 값과
실패 값을 만드는 생성 함수
- `src/adapters/cross-context-invalidation/index.ts` — context 사이 무효화
(invalidation) 전송과 그 타입. 어떤 adapter든 import할 수 있다. 지금은
`query-cache`가 import한다
`check:architecture` enforces every rule above, including the kernel carve-out.
`verify:documentation` fails when a rule name or a top-level `src` folder is
missing from this page, when `README.md`, `overview.md` or
`frontend-application-foundation.md` describe a folder differently from the
folder table, and when any of them names a top-level `src` folder that does not
exist. Neither checks that a row describes its rule correctly.
`check:architecture`는 위 규칙을 모두 강제한다. kernel 예외도 포함한다.
`verify:documentation`은 다음 경우에 실패한다. 규칙 이름이나 최상위 `src`
폴더가 이 문서에서 빠졌을 때다. `README.md`, `overview.md`,
`frontend-application-foundation.md`가 폴더를 폴더 표와 다르게 설명할 때다.
그리고 그중 어느 문서든 없는 최상위 `src` 폴더를 적을 때다. 두 검사 모두 각
행이 규칙을 맞게 설명하는지는 보지 않는다.
Every exception is written in the rule itself (`.dependency-cruiser.json`): the
exempted path in `pathNot`, and the reason, owner and revisit condition in
`comment` (review 12-07). Besides the kernel, the exceptions are:
모든 예외는 규칙 자체(`.dependency-cruiser.json`)에 적는다. 예외 경로는
`pathNot`에, 이유·owner·다시 볼 조건은 `comment`에 적는다(리뷰 12-07).
kernel 말고 예외는 다음과 같다:
- the generic presentation modules that read the installed registries today
(`generic-presentation-does-not-compose-the-product`). The list names exact
files, so a new module that reads a registry fails the gate
- `src/presentation/adapters/query`, the TanStack Query binding
- 지금 설치된 registry를 읽는 범용 presentation 모듈
(`generic-presentation-does-not-compose-the-product`). 목록은 파일을 정확히
적는다. 그래서 registry를 읽는 새 모듈은 gate에서 실패한다
- TanStack Query 바인딩인 `src/presentation/adapters/query`
(`presentation-does-not-know-adapters`)
- `src/presentation/routes/app-router.tsx` importing the app
- 앱을 import하는 `src/presentation/routes/app-router.tsx`
(`presentation-does-not-import-apps-or-contexts`)
- the design-system facades (`design-system-is-reached-through-its-index`)
- `src/platform/routing` reading deployable-app types
- 디자인 시스템 facade(`design-system-is-reached-through-its-index`)
- 배포 단위 앱 타입을 읽는 `src/platform/routing`
(`platform-kernel-is-product-neutral`)
## 어댑터 그룹의 공개 경계
@@ -151,19 +152,20 @@ realm 파일만 빼는 구조라, 배럴이 그 파일을 다시 끌어들이면
`document`를 찾지 못한다. 배럴의 타입 커버리지는 `tsconfig.app.json`이
담당하고, 워커 진입점은 배럴을 쓰지 않는다.
`bootstrap` contains composition only. Business rules and page-specific
orchestration belong to `src/application` or to a feature's domain and
application.
`bootstrap`에는 조립만 있다. 비즈니스 규칙과 페이지별 흐름 조정
(orchestration)은 `src/application`이나 feature의 domain·application에 둔다.
The [ports, adapters, and feature-boundary contract](../design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
explains how `presentation` acts as the inbound adapter and how feature
application APIs augment the generic typed input registry. Concrete output
ports are composed in bootstrap and stay hidden behind the application facade.
Project-selected capabilities still implement the same output boundaries.
[port, adapter, feature 경계 계약](../design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md)은
두 가지를 설명한다. 하나는 `presentation`이 inbound adapter로 동작하는
방식이다. 다른 하나는 feature application API가 타입이 붙은 범용 입력
registry를 확장(augment)하는 방식이다. 구체 output port는 bootstrap에서
조립되고 application facade 뒤에 숨는다. 프로젝트가 고른 capability도 같은
output 경계를 구현한다.
`check:architecture` writes the TypeScript-aware graph below. It reads the rules
from `.dependency-cruiser.json` but does not run dependency-cruiser, which cannot
parse TypeScript 7 and checked zero modules (review 12-05):
`check:architecture`는 TypeScript를 이해하는 아래 그래프를 출력한다. 규칙은
`.dependency-cruiser.json`에서 읽지만 dependency-cruiser를 돌리지는 않는다.
dependency-cruiser는 TypeScript 7을 파싱하지 못해 모듈을 하나도 검사하지
못했다(리뷰 12-05):
```json
{
@@ -181,11 +183,12 @@ parse TypeScript 7 and checked zero modules (review 12-05):
}
```
The graph scans TypeScript and TSX, including static, dynamic, type, CommonJS
and JSDoc import references. `import.meta.glob` is a parse failure: it loads
modules without naming one, so no edge rule could see them (review 12-06). It applies the path rules from
`.dependency-cruiser.json`, requires explicit TypeScript extensions for local
source imports, and fails closed on JavaScript-family source/specifiers,
unsupported rule shapes, unresolved imports, parse failures, error-severity
layer violations, or cycles. Regression fixtures prove the allowed resolver
path and each rejection class.
그래프는 TypeScript와 TSX를 읽는다. static, dynamic, type, CommonJS, JSDoc
import 참조를 모두 포함한다. `import.meta.glob`은 파싱 실패로 처리한다.
모듈 이름을 적지 않고 모듈을 불러오므로 어떤 간선 규칙도 그 모듈을 볼 수
없기 때문이다(리뷰 12-06). 그래프는 `.dependency-cruiser.json`의 경로 규칙을
적용한다. 로컬 소스 import에는 TypeScript 확장자를 명시하도록 요구한다. 다음
중 하나라도 있으면 통과시키지 않고 실패한다(fail closed): JavaScript 계열
소스·specifier, 지원하지 않는 규칙 모양, 해석되지 않은 import, 파싱 실패,
error 심각도의 계층 위반, 순환. 회귀 fixture가 허용되는 resolver 경로와 거부
종류 하나하나를 증명한다.
+60 -63
View File
@@ -1,24 +1,24 @@
# Architecture overview
# 아키텍처 개요
This Mermaid view is a repository-local implementation projection. The
`PASS_SCOPED` reviewer evidence applies to the canonical draw.io diagram named
in `review-ledger.json`, not automatically to edits in this file.
이 Mermaid 그림은 repo 안에서 구현을 옮겨 그린 투영(projection)이다.
`PASS_SCOPED` 리뷰 증거는 `review-ledger.json`이 가리키는 정본 draw.io
도식에 적용된다. 이 파일을 고친 내용에 저절로 적용되지는 않는다.
`src/` has nine top-level folders. The descriptions match the table in
[the layer contract](./layers.md), which also names every import rule:
`src/`에는 최상위 폴더가 아홉 개 있다. 설명은 [계층 계약](./layers.md)의
표와 같다. 그 문서는 모든 import 규칙도 적는다:
- `src/bootstrap` — the composition root: runtime configuration, concrete adapter construction and the React mount
- `src/apps` — deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces
- `src/contexts` — bounded contexts: each `context-module.ts` declares its app, route root and feature budget
- `src/features` — removable vertical slices (`src/features/<id>/{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`)
- `src/presentation` — generic UI and the inbound adapter: routes, layouts, the design system, pages and providers
- `src/adapters` — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more
- `src/application` — generic use cases, ports, policies and view-models
- `src/contracts` — shared vocabulary and registries read by several layers, the workers and the build and release scripts
- `src/platform` — product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence
- `src/bootstrap` — 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트
- `src/apps` — 배포 단위 앱: 각 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다
- `src/contexts` — bounded context: 각 `context-module.ts`가 소속 앱, 라우트 루트, 기능 예산을 선언한다
- `src/features` — 지울 수 있는 수직 slice(`src/features/<id>/{domain,application,contracts,adapters,presentation}`)와 설치된 기능 목록(`src/features/*.ts`)
- `src/presentation` — 범용 UI와 inbound adapter: 라우트, 레이아웃, 디자인 시스템, 페이지, provider
- `src/adapters` — application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등
- `src/application` — 범용 use case, 포트, 정책, view-model
- `src/contracts` — 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registry
- `src/platform` — 어느 폴더든 쓸 수 있는 제품 중립 기본 요소: 예산, 실행 context, 복원력, telemetry 파이프라인, 오류 envelope, 릴리스 정합성
Arrows point from the importing folder to the imported one. Every folder may
also import `contracts` and `platform`; only the main path is drawn.
화살표는 import하는 폴더에서 import되는 폴더로 향한다. 모든 폴더는
`contracts`와 `platform`도 import할 수 있다. 그림에는 주 경로만 그렸다.
```mermaid
flowchart LR
@@ -37,19 +37,18 @@ flowchart LR
Contracts --> Platform[platform]
```
The enforced dependency rule points inward: presentation calls application use
cases, adapters implement application ports, and only the composition root
selects concrete adapters. Domain code lives inside each feature. Contract
registries are the named source for routes,
API operations, environment values, storage keys, errors, queries, telemetry,
and release tokens. Installed feature contributions extend those registries
without making the generic application or router import a concrete feature
implementation.
강제되는 의존성 규칙은 안쪽을 향한다. presentation은 application use case를
부른다. adapter는 application port를 구현한다. 구체 adapter는 composition
root만 고른다. domain 코드는 각 feature 안에 있다. contract registry는
라우트, API operation, 환경 값, 저장소 키, 오류, query, telemetry, release
토큰의 이름을 정하는 출처다. 설치된 feature contribution이 이 registry를
확장한다. 그래도 범용 application이나 router가 구체 feature 구현을
import하게 되지는 않는다.
In ports-and-adapters terms, `presentation` is the current inbound adapter and
`adapters` contains the current outbound implementations. The production
composition exposes an application input API to React while keeping concrete
output ports inside application closures:
ports-and-adapters 용어로 말하면 `presentation`이 지금의 inbound adapter이고,
`adapters`에 지금의 outbound 구현이 있다. 운영 조립(production composition)은
React에 application input API를 내보인다. 구체 output port는 application
closure 안에 둔다:
```mermaid
flowchart LR
@@ -62,39 +61,37 @@ flowchart LR
Bootstrap2 -. selects and injects .-> Outbound
```
The executable route tree is mounted only after runtime configuration and
release-manifest coherence pass. `ApplicationProvider` receives the composed
application API; concrete session, storage, telemetry, diagnostics, and release
ports are not returned to feature pages. TanStack Query is isolated behind the
presentation query adapter, while its provider remains React infrastructure.
The module-augmented feature registry gives each installed feature a closed ID
and exact input type.
실행할 라우트 트리는 runtime 설정 검사와 release manifest 정합성 검사가
통과한 뒤에만 마운트된다. `ApplicationProvider`는 조립된 application API를
받는다. 구체 session·storage·telemetry·진단·release port는 feature 페이지에
돌려주지 않는다. TanStack Query는 presentation query adapter 뒤에 격리된다.
다만 그 provider는 React 인프라로 남는다. module augmentation으로 확장한
feature registry가 설치된 feature마다 닫힌 ID와 정확한 입력 타입을 준다.
Route contracts/codecs, the route-input provider, and lazy runtime modules are
separate modules so feature pages do not import the router that loads them.
Expected application failures use the shared `Result`/`AppFailure` contract.
The architecture gate analyzes TS/TSX imports with its own graph (the rules
live in `.dependency-cruiser.json`; dependency-cruiser itself cannot parse
TypeScript 7 and does not run), rejects local JavaScript-family specifiers and executable
JavaScript-family files, and fails on unresolved imports, parse failures,
forbidden layer edges, or cycles. The remaining project-owned work includes
selecting and verifying real hosting, identity, telemetry, vulnerability and
signing providers, plus backend/provider/browser/operations evidence for each
selected optional capability; the repository does not fabricate that evidence.
Use the following
documents for implementation details and project integration work:
라우트 contract·codec, route-input provider, lazy runtime 모듈은 서로 다른
모듈이다. 그래서 feature 페이지는 자신을 불러오는 router를 import하지 않는다.
예상된 application 실패는 공용 `Result`/`AppFailure` contract를 쓴다.
architecture gate는 자체 그래프로 TS/TSX import를 분석한다(규칙은
`.dependency-cruiser.json`에 있다. dependency-cruiser 자체는 TypeScript 7을
파싱하지 못해 돌리지 않는다). gate는 로컬 JavaScript 계열 specifier와 실행
가능한 JavaScript 계열 파일을 거부한다. 해석되지 않은 import, 파싱 실패,
금지된 계층 간선, 순환이 있으면 실패한다. 프로젝트가 맡을 일이 남아 있다.
실제 hosting, identity, telemetry, 취약점 점검, 서명 provider를 고르고
검증하는 일이다. 그리고 고른 선택 capability마다 백엔드·provider·브라우저·운영
증거를 갖추는 일이다. 이 repo는 그 증거를 지어내지 않는다. 구현 세부와
프로젝트 통합 작업은 아래 문서를 본다:
- [Frontend platform capability review](../design/2026-07-26-frontend-platform-capability-review-design.md)
- [Frontend ports, adapters, and boundaries](../design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
- [API contract, Schema, Mapper, and Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
- [Protobuf browser transports and REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
- [Backend API and Server State handoff contract](./backend-api-and-server-state-contract.md)
- [TypeScript, state, and data flow](../design/2026-07-26-typescript-state-and-data-flow-design.md)
- [Routing, pages, and patterns](../design/2026-07-26-routing-pages-and-patterns-design.md)
- [Browser data capability completion ledger](../design/2026-07-30-browser-data-capability-completion-ledger-design.md)
- [Browser file and origin storage](../design/2026-07-27-browser-file-and-origin-storage-design.md)
- [Client cache and storage](../design/2026-07-28-client-cache-and-storage-design.md)
- [Realtime events, Web Push, and bounded polling](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)
- [Presigned transfer and Image CDN](../design/2026-07-30-presigned-transfer-and-image-cdn-design.md)
- [Server file capability infrastructure](../design/2026-07-28-server-file-capability-infrastructure-design.md)
- [Frontend platform implementation roadmap](../design/2026-07-26-frontend-platform-implementation-roadmap-design.md)
- [프론트엔드 platform capability 리뷰](../design/2026-07-26-frontend-platform-capability-review-design.md)
- [프론트엔드 port, adapter, 경계](../design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md)
- [API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)
- [Protobuf 브라우저 전송과 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)
- [백엔드 API와 Server State 인계 계약](./backend-api-and-server-state-contract.md)
- [TypeScript, 상태, 데이터 흐름](../design/2026-07-26-typescript-state-and-data-flow-design.md)
- [라우팅, 페이지, 패턴](../design/2026-07-26-routing-pages-and-patterns-design.md)
- [브라우저 데이터 capability 완료 장부(ledger)](../design/2026-07-30-browser-data-capability-completion-ledger-design.md)
- [브라우저 파일과 origin 저장소](../design/2026-07-27-browser-file-and-origin-storage-design.md)
- [클라이언트 캐시와 저장소](../design/2026-07-28-client-cache-and-storage-design.md)
- [Realtime 이벤트, Web Push, 상한을 둔 polling](../design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md)
- [Presigned 전송과 Image CDN](../design/2026-07-30-presigned-transfer-and-image-cdn-design.md)
- [서버 파일 capability 인프라](../design/2026-07-28-server-file-capability-infrastructure-design.md)
- [프론트엔드 platform 구현 로드맵](../design/2026-07-26-frontend-platform-implementation-roadmap-design.md)