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:
+144
-78
@@ -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
@@ -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 경로와 거부
|
||||
종류 하나하나를 증명한다.
|
||||
|
||||
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user