문제: 프론트 문서 체계는 백엔드와 다르다. 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에서 돌렸다.
195 lines
14 KiB
Markdown
195 lines
14 KiB
Markdown
# Clean Architecture 계층 계약
|
|
|
|
의존성은 안쪽을 향한다: `presentation -> application -> contracts ->
|
|
platform`. 구체 adapter는 application이 소유한 port를 구현한다. 구체
|
|
adapter는 `src/bootstrap`에서만 조립된다.
|
|
|
|
## 최상위 폴더
|
|
|
|
`src/`에는 아래 아홉 폴더만 있다:
|
|
|
|
| 폴더 | 맡는 것 |
|
|
| --- | --- |
|
|
| `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 코드는 feature 안(`src/features/<id>/domain`)에 있다. 최상위 domain
|
|
폴더는 없다. 프로젝트가 그런 폴더를 더해도 `domain-is-framework-neutral`과
|
|
`concrete-adapters-compose-only-in-bootstrap`이 이미 그 폴더를 다룬다.
|
|
|
|
`src/adapters/platform`은 adapter kernel(아래 절)이다. `src/platform`과는
|
|
다른 폴더다.
|
|
|
|
공용 타입이나 기본 요소를 어디에 둘지는
|
|
[contract 소유권](./contract-ownership.md)에서 정한다.
|
|
|
|
## 규칙
|
|
|
|
각 행은 `.dependency-cruiser.json`의 `forbidden` 규칙 하나이고, 그 규칙의
|
|
`name`으로 적는다. 「금지」 칸은 「적용 대상」 칸의 코드가 import하면 안 되는
|
|
것이다.
|
|
|
|
| 규칙 | 적용 대상 | 금지 |
|
|
| --- | --- | --- |
|
|
| `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`. 단 `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, 모든 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` | `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가 아래쪽 패키지이고, 둘이 함께 읽는 어휘를 소유한다 |
|
|
| `contracts-do-not-know-presentation-or-bootstrap` | `src/contracts` | presentation, bootstrap |
|
|
| `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`가 있는 이유는 그래프가 간선을
|
|
하나씩만 검사하기 때문이다. presentation은 그 파일들을 import할 수 있다.
|
|
그래서 그 파일에서 adapter를 재수출하면, 다른 규칙이 모두 통과한 채로
|
|
adapter가 presentation까지 들어온다.
|
|
|
|
## adapter kernel
|
|
|
|
`adapters-do-not-know-other-concrete-adapters`는 adapter kernel을 예외로
|
|
둔다. kernel은 일부러 공유하는 코드다. adapter가 그룹을 넘어 가져다 쓸 수
|
|
있는 adapter 코드는 kernel뿐이다:
|
|
|
|
- `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`는 위 규칙을 모두 강제한다. kernel 예외도 포함한다.
|
|
`verify:documentation`은 다음 경우에 실패한다. 규칙 이름이나 최상위 `src`
|
|
폴더가 이 문서에서 빠졌을 때다. `README.md`, `overview.md`,
|
|
`frontend-application-foundation.md`가 폴더를 폴더 표와 다르게 설명할 때다.
|
|
그리고 그중 어느 문서든 없는 최상위 `src` 폴더를 적을 때다. 두 검사 모두 각
|
|
행이 규칙을 맞게 설명하는지는 보지 않는다.
|
|
|
|
모든 예외는 규칙 자체(`.dependency-cruiser.json`)에 적는다. 예외 경로는
|
|
`pathNot`에, 이유·owner·다시 볼 조건은 `comment`에 적는다(리뷰 12-07).
|
|
kernel 말고 예외는 다음과 같다:
|
|
|
|
- 지금 설치된 registry를 읽는 범용 presentation 모듈
|
|
(`generic-presentation-does-not-compose-the-product`). 목록은 파일을 정확히
|
|
적는다. 그래서 registry를 읽는 새 모듈은 gate에서 실패한다
|
|
- TanStack Query 바인딩인 `src/presentation/adapters/query`
|
|
(`presentation-does-not-know-adapters`)
|
|
- 앱을 import하는 `src/presentation/routes/app-router.tsx`
|
|
(`presentation-does-not-import-apps-or-contexts`)
|
|
- 디자인 시스템 facade(`design-system-is-reached-through-its-index`)
|
|
- 배포 단위 앱 타입을 읽는 `src/platform/routing`
|
|
(`platform-kernel-is-product-neutral`)
|
|
|
|
## 어댑터 그룹의 공개 경계
|
|
|
|
각 어댑터 그룹의 공개 표면은 그 그룹의 `index.ts`다. 그룹 바깥
|
|
(`bootstrap`, `features`, `presentation`)은 배럴만 import한다.
|
|
`adapter-groups-are-reached-through-their-barrel` 규칙이 이를 강제하고,
|
|
`tests/fixtures/architecture/dependency-graph/barrel`이 거부와 허용을
|
|
각각 고정한다 — 규칙을 지우면 그 회귀 검사가 먼저 깨진다.
|
|
|
|
두 가지 예외가 있고 둘 다 의도된 것이다.
|
|
|
|
- **그룹 내부 파일끼리**는 파일 경로로 직접 import한다. 배럴은 바깥을 위한
|
|
문이지 내부 규율이 아니다.
|
|
- **어댑터 → 커널(`platform/**`)** 간선도 파일 경로를 유지한다. 커널은
|
|
런타임 합성물이 아니라 프리미티브이고, `check:adapter-inventory`가 네
|
|
소비자에게 `platform/abortable-operation.ts`로 해석되는 specifier를
|
|
직접 요구한다. 커널 배럴(`platform/index.ts`)은 bootstrap과 테스트를
|
|
위한 것이다.
|
|
|
|
`storage`는 최상위 배럴이 `indexeddb/`·`opfs/` 서브배럴을 재수출하지
|
|
않는다. 두 폴더는 browser-file-storage 번들의 런타임이다. 제거 드릴
|
|
(`test:browser-file-storage-removal`)은 그 번들 전체(`browser-file-storage`,
|
|
`browser-files`, `browser-transfer`, `cache-storage`, `storage/indexeddb`,
|
|
`storage/opfs`)를 함께 지운다. 최상위 `storage` 배럴(Web Storage)은 그 뒤에도
|
|
남아야 하므로 두 폴더를 재수출하지 않고, 그래서 각 서브배럴이 그 런타임의 공개
|
|
경계다.
|
|
규칙의 도착점 정규식은 이 두 서브배럴만 배럴로 인정한다. 다른 그룹의 2단계
|
|
`index.ts`(예: `http/internals/index.ts`)는 공개 배럴이 아니고, 그룹 바깥에서
|
|
import하면 실패한다(리뷰 12-07, `dependency-graph/barrel` fixture).
|
|
|
|
`service-worker/index.ts`는 `tsconfig.service-worker.json`의 `exclude`에
|
|
들어 있다. 그 설정이 그룹 폴더를 통째로 WebWorker lib로 컴파일하면서 페이지
|
|
realm 파일만 빼는 구조라, 배럴이 그 파일을 다시 끌어들이면 워커 타입체크가
|
|
`document`를 찾지 못한다. 배럴의 타입 커버리지는 `tsconfig.app.json`이
|
|
담당하고, 워커 진입점은 배럴을 쓰지 않는다.
|
|
|
|
`bootstrap`에는 조립만 있다. 비즈니스 규칙과 페이지별 흐름 조정
|
|
(orchestration)은 `src/application`이나 feature의 domain·application에 둔다.
|
|
|
|
[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`는 TypeScript를 이해하는 아래 그래프를 출력한다. 규칙은
|
|
`.dependency-cruiser.json`에서 읽지만 dependency-cruiser를 돌리지는 않는다.
|
|
dependency-cruiser는 TypeScript 7을 파싱하지 못해 모듈을 하나도 검사하지
|
|
못했다(리뷰 12-05):
|
|
|
|
```json
|
|
{
|
|
"staticImportGraph": {
|
|
"analyzer": "babel-parser-node-resolver",
|
|
"modules": [],
|
|
"dependencies": [],
|
|
"unresolved": [],
|
|
"parseFailures": [],
|
|
"cycles": [],
|
|
"violations": [],
|
|
"summary": { "errors": 0 },
|
|
"fixtureChecks": { "passed": true, "checks": [], "failures": [] }
|
|
}
|
|
}
|
|
```
|
|
|
|
그래프는 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 경로와 거부
|
|
종류 하나하나를 증명한다.
|