2026-11-07~08의 정리(문서 이동, 참조 기능 삭제, CI 재편) 뒤 살아 있는 문서가 지금 코드와 다른 말을 한다. - 현재 계약 문서 둘과 스타터 문서가 기록(docs/design/)을 정본으로 가리킨다. 정본을 frontend-application-foundation.md·src/bootstrap/, 패턴 표·계층 규칙으로 바꾸고 설계서는 배경으로 둔다(1112/02-06). - 실시간 대응표 둘(짝 백엔드 출구, poll attempt 결과)이 기록에만 있었다. optional-adapter-recipes.md로 옮기고 코드 주석·매뉴얼 03·설계서 머리 블록이 옮긴 곳을 가리킨다(1112/09-02). - 실행 격리 변수 목록을 설계 기록이 아니라 scripts/lib/run-isolation.ts로 가리킨다(1112/08-17). - 계약 소유 절 이름(「판단 규칙」), pin 대조 시험의 게이트(005·007), drift 검사 범위(1112/02-07). INVENTORY 머리의 손 숫자와 지킬 수 없는 꼬리 문장(1112/02-08). - 검증 안내: 검사기를 바꾸면 FE-GATE-029, 문서면 desktop verify:documentation(1112/08-05, 08-04). FE-GATE-012는 merge 단계다 (08-16). N6이 알리는 파일을 좁혀 적는다(08-10). 한 파일 시험은 verify.sh exec(08-11). 문서 검사 범위의 손 사본을 정본 한 곳으로(08-07). - create:feature 참조의 Next: 3과 되돌리기(08-08), 손으로 옮긴 숫자 (08-19), 라운드 없는 리뷰 ID 17곳에 0925를 붙인다(08-15). - secret scan 범위 설명(1112/07-03), lab이 기능 라우트를 읽는 문장 (1103/16-06), README 동기화 기준점·제품 소유 파일·선택 기능 결함 몫 (0929/14-02, 14-03, 13-10), 커밋을 다시 지은 모든 통합의 해시 대조 (1106/14-02). 고른 방법: 문장을 코드에 맞춘다. 표는 옮기고 숫자는 정본을 가리킨다. 버린 대안: 기록 문서 본문 고치기(기록은 머리 블록만 고친다). 위험·한계: 문서 검사 범위 목록을 지운 ci-quality-gates.md는 이제 docs/README.md 5절과 gates.md 7절을 읽어야 한다. 매뉴얼 02 7절 업로드 예의 declare module 문제(1112/09-01)는 고치는 방향이 check:architecture 규칙과 부딪쳐 결정 대기로 남긴다. 검증: scripts/verify.sh docs(노트북) 통과. desktop verify:documentation과 FE-GATE-005(문서를 읽는 시험)는 PR 본문에 적는다. Refs: 1112/02-06, 1112/02-07, 1112/02-08, 1112/07-03, 1112/08-04, 1112/08-05, 1112/08-07, 1112/08-08, 1112/08-10, 1112/08-11, 1112/08-15, 1112/08-16, 1112/08-17, 1112/08-19, 1112/09-02, 1103/16-06, 0929/14-02, 0929/14-03, 0929/13-10, 1106/14-02
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`에 적는다(리뷰 0925/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하면 실패한다(리뷰 0925/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을 파싱하지 못해 모듈을 하나도 검사하지
|
|
못했다(리뷰 0925/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`은 파싱 실패로 처리한다.
|
|
모듈 이름을 적지 않고 모듈을 불러오므로 어떤 간선 규칙도 그 모듈을 볼 수
|
|
없기 때문이다(리뷰 0925/12-06). 그래프는 `.dependency-cruiser.json`의 경로 규칙을
|
|
적용한다. 로컬 소스 import에는 TypeScript 확장자를 명시하도록 요구한다. 다음
|
|
중 하나라도 있으면 통과시키지 않고 실패한다(fail closed): JavaScript 계열
|
|
소스·specifier, 지원하지 않는 규칙 모양, 해석되지 않은 import, 파싱 실패,
|
|
error 심각도의 계층 위반, 순환. 회귀 fixture가 허용되는 resolver 경로와 거부
|
|
종류 하나하나를 증명한다.
|