문제: 꼭 지킬 것 2의 kernel 규칙을 고정하는 fixture가 없어, pathNot을 넓히거나 규칙을 지워도 아무것도 실패하지 않는다(02-01). routing 예외가 금지 대상 일곱을 다 풀고, contribution 파일 예외가 adapter 값까지 푼다. 그래서 presentation이 HTTP adapter에 닿는 길이 규칙 밖에 있다(02-02). generic-presentation 예외 목록에 registry를 더는 읽지 않는 home-page가 남았다(02-03). 기능의 계층 밖 폴더가 자기 adapters/를 거쳐 src/adapters에 닿는 두 단계 길이 열려 있다(0929/12-03). application TelemetryPort가 플랫폼 TelemetryPort와 이름이 같고, 폐기 표시된 src/application/result.ts를 ports 셋이 상대 경로로 계속 읽는다(1101/16-05). 고른 방법(R9-D3 좁히기): - 그래프가 type-only import를 가르고, 규칙 to에 dependencyTypesNot ["type-only"]를 쓸 수 있다(산출물 모양은 그대로). - platform 규칙을 둘로 나눈다. routing도 features·adapters·bootstrap· presentation·application은 못 읽고, apps·contexts만 routing이 읽는다. - feature-adapter-contribution-reads-adapter-types-only: contribution 파일은 src/adapters를 타입으로만 읽는다. - feature-support-folders-do-not-reach-feature-adapters: 다섯 계층이 아닌 폴더는 자기 기능의 adapters/를 import하지 않는다. - home-page를 예외 목록에서 뺀다. 이름으로 적은 파일 예외가 더 쓰이지 않으면 check:architecture가 실패한다. - kernel·routing·type-only·두 단계 길 fixture와 assertion을 더한다. - ApplicationTelemetryPort로 이름을 나누고 옛 이름은 한 릴리스 동안 @deprecated 별칭으로 둔다. ports 셋이 Result를 src/contracts/result.ts에서 읽게 하고 src/application/result.ts를 지운다. 버린 대안: page-templates.tsx가 LinkButton을 design-system index에서 가져오기 — index가 page-templates를 다시 내보내 순환이 된다. 예외 이유에 그것을 적었다. 기능 경계 둘을 하나로 합치기 — 안쪽은 라우트 내용, 바깥은 라우트 틀(RouteLifecycle, 입력 해석)을 맡아 역할이 다르다. 두 자리에 역할을 적었다. 위험·한계: 이름 예외 검사는 pathNot 문자열에 파일 base name이 있는 경우만 이름 예외로 본다. 폴더·이름 패턴 예외는 보지 않는다. 검증: desktop 결과는 PR 본문. Refs: 1112/02-01, 1112/02-02, 1112/02-03, 0929/12-03, 1101/16-05
15 KiB
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 소유권에서 정한다.
규칙
각 행은 .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 |
feature-adapter-contribution-reads-adapter-types-only |
src/features/feature-adapter-contribution.ts |
src/adapters의 값. import type·export type만 된다 |
feature-support-folders-do-not-reach-feature-adapters |
feature 안에서 다섯 계층 폴더가 아닌 폴더(support/ 등) |
같은 feature의 adapters/. presentation → support/ → adapters/ → 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(routing/ 포함) |
features, adapters, bootstrap, presentation, application |
platform-kernel-does-not-know-apps-or-contexts |
src/platform. 단 app descriptor를 읽는 routing/은 제외 |
apps, contexts |
platform-routing-reads-app-types-only |
src/platform/routing |
apps·contexts의 값. import type만 된다 |
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/presentation/templates/page-templates.tsx도 뺀다. index가 이 파일을 다시 내보내므로 이 파일이 index를 import하면 순환이다. 그래서LinkButton과 index에 없는PaginationLandmarkContext를 primitive 파일에서 읽는다 - 배포 단위 앱 타입을 읽는
src/platform/routing(platform-kernel-does-not-know-apps-or-contexts). apps·contexts를 타입으로만 읽는다 (platform-routing-reads-app-types-only) - capability의 adapter 타입을 읽는
src/features/feature-adapter-contribution.ts(feature-and-app-roots-do-not-reach-adapters). 타입만이다 (feature-adapter-contribution-reads-adapter-types-only)
이름으로 적은 파일 예외는 쓰일 때만 남는다. 그 파일이 규칙이 막는 import를 더
하지 않으면 check:architecture가 목록에서 빼라고 실패한다. 그래프는 import type과
값 import를 가른다. 그래서 타입만 허용하는 예외가 값 재수출로 넓어지지 않는다.
어댑터 그룹의 공개 경계
각 어댑터 그룹의 공개 표면은 그 그룹의 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 경계 계약은
두 가지를 설명한다. 하나는 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):
{
"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 경로와 거부
종류 하나하나를 증명한다.