문제: src/ 최상위 폴더는 adapters application apps bootstrap contexts
contracts features platform presentation 9개다. layers.md 표,
frontend-application-foundation.md 목록, overview.md 그림, README 구조
그림은 src/platform을 한 번도 적지 않았고 apps·contexts는 금지 간선
설명에만 나왔다. 대신 없는 최상위 domain을 계층으로 그렸다.
contract-ownership.md의 배치 규칙에는 src/platform 선택지가 없었다.
layers.md는 "표와 규칙이 어긋날 수 없다"고 적었지만
.dependency-cruiser.json 규칙 31개 중 25개의 이름이 없었다.
게이트는 금지 간선만 막으므로, 허용되지만 틀린 자리(최상위 domain 신설,
제품 중립 primitive를 contracts에 두기)를 문서로 막을 수 없었다.
고른 방법: 리뷰의 (B)안. 문서를 코드에 맞추고 verify:documentation에
대조 검사를 더한다.
- layers.md: 9개 폴더 표(폴더 | 소유)를 정본으로 두고, 금지 간선 글머리
목록을 규칙 31개 표(규칙 이름 | 적용 대상 | 금지)로 바꾼다. domain은
기능 안의 계층으로 옮기고 "최상위 domain 폴더는 지금 없고, 만들면
domain-is-framework-neutral이 이미 적용된다"고 적는다. 보증 문장은
실제로 검사하는 범위로 줄인다. kernel 절과 배럴 절은 그대로 둔다.
- README·overview·foundation: layers.md 표의 설명을 한 글자도 바꾸지
않고 "`src/<폴더>` — <설명>" 목록으로 싣는다. 그림은 실제 import
방향(presentation -> application -> contracts -> platform,
apps -> contexts -> features)으로 다시 그린다.
- contract-ownership.md: src/platform 선택지와 contracts와의 차이,
platform-kernel-is-product-neutral을 적는다.
- verify-documentation-readiness.ts: 폴더 목록은 src/를 읽고, 규칙 목록은
.dependency-cruiser.json을 읽는다. layers.md 표에 행이 없는 폴더,
나머지 세 문서에서 설명이 다른 폴더, 네 문서가 적은 없는 최상위
src 폴더, layers.md에 없는 규칙 이름이 있으면 실패한다. 결과는
documentation-review.json의 sourceStructure로 남긴다(스키마는 필드
하나를 더한다).
버린 대안: (A) 문서만 고치기 — 규칙이나 폴더가 늘면 다시 어긋난다.
(C) layers.md를 .dependency-cruiser.json에서 생성 — 사람이 읽는 설명을
넣기 어렵다. 네 문서 모두에 규칙 31개를 싣는 것 — 같은 목록이 네 벌이
되어 어긋날 곳만 늘어난다. 규칙 표는 layers.md 한 곳에 둔다.
위험·한계:
- 검사는 규칙 이름이 있는지만 본다. 행의 설명이 규칙과 맞는지는 보지
않는다(문서에도 그렇게 적었다).
- 없는 폴더 검사는 "src/<이름>" 꼴만 잡는다. "domain"처럼 src/ 없이
계층 이름만 쓰는 것은 잡지 못한다.
- README·overview·foundation에는 같은 9줄이 복사되어 있다. 설명을 바꾸면
네 곳을 함께 고쳐야 하고, 검사가 그것을 강제한다.
- .dependency-cruiser.json 주석의 "like src/domain"(feature-domain 규칙)은
코드 주석이라 이번 범위 밖이다.
- 문서 drift 전반(경로·줄 번호, 14-05)은 다루지 않는다.
검증:
- RED: 새 검사를 기준 커밋(7a70cea)의 문서에 돌리면 FAIL_UNVERIFIED
(failed: source structure). layers.md는 규칙 25개가 없고, 네 문서
모두 9개 폴더를 설명하지 않는다고 나온다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
tests/unit/documentation-readiness.test.ts 6개 통과. 새 변이 3개:
규칙 이름 하나를 바꾸면, README에 `src/domain`을 넣으면, overview의
platform 설명을 바꾸면 각각 실패하고 원인 문서와 이름을 적는다.
- 회귀: tests/unit 전체(fixture-node-modules 제외, pnpm 설치를 띄운다)
173파일 2494개 통과. ci-artifact-contract의 "semantically invalid"
16개 통과. tsc(node, test) 통과, 바꾼 ts 파일 eslint 통과.
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-03
12 KiB
Clean Architecture layer contract
Dependencies point inward: presentation -> application -> contracts -> platform. Concrete adapters implement application-owned ports and are
assembled only in src/bootstrap.
Top-level folders
src/ has these nine folders and no others:
| 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 |
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.
src/adapters/platform is the adapter kernel (below). It is not
src/platform.
Where a shared type or primitive goes is decided in contract ownership.
Rules
Each row is one forbidden rule in .dependency-cruiser.json, by its name.
"Forbids" lists what code under "Applies to" must not import.
| Rule | Applies to | Forbids |
|---|---|---|
domain-is-framework-neutral |
a top-level domain folder (none today) | 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 |
design-system-is-reached-through-its-index |
code outside the design system and its named facades | design-system files other than its 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 |
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 |
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-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 |
src/features/*.ts, src/features/<id>/*.ts, 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 |
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.
The 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:
src/adapters/platform/**— the system clock, the shared abort primitive and the bounded-capacity guardsrc/adapters/browser-file-storage/result.ts— the browser-data result and failure constructorssrc/adapters/cross-context-invalidation/index.ts— the cross-context invalidation transport and its types. Any adapter may import it; todayquery-cachedoes
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.
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:
- 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 (presentation-does-not-know-adapters)src/presentation/routes/app-router.tsximporting the app (presentation-does-not-import-apps-or-contexts)- the design-system facades (
design-system-is-reached-through-its-index) src/platform/routingreading deployable-app types (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 contains composition only. Business rules and page-specific
orchestration belong to src/application or to a feature's domain and
application.
The ports, adapters, and feature-boundary contract
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.
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):
{
"staticImportGraph": {
"analyzer": "babel-parser-node-resolver",
"modules": [],
"dependencies": [],
"unresolved": [],
"parseFailures": [],
"cycles": [],
"violations": [],
"summary": { "errors": 0 },
"fixtureChecks": { "passed": true, "checks": [], "failures": [] }
}
}
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.