문제 feature-and-app-roots-do-not-reach-adapters는 기능 루트 파일 (src/features/*.ts, src/features/<id>/*.ts), src/contexts, src/apps만 본다. 그래프는 간선 하나씩 검사하므로, 기능 안에 계층이 아닌 폴더(support/ 등)를 만들어 그 파일이 http adapter 배럴을 import하고 기능 presentation이 그 파일을 import하면 presentation이 구체 adapter에 닿는다. 1105 리뷰 12-R3 변이에서 check:architecture와 ESLint가 둘 다 통과했다. 고른 방법 - 규칙의 from을 "src/features 아래 모든 파일, 기능의 adapters/ 폴더 밖"으로 바꾼다(`^src/(features/|contexts/|apps/)`, pathNot `^src/features/([^/]+/adapters/|feature-adapter-contribution\.ts$)`). 규칙 주석이 이미 "기능 안에서는 adapters/ 폴더만 src/adapters에 닿는다"고 적고 있었고, 그 문장을 경로로 옮긴 것이다. 파일 단위 예외는 기존 하나 (feature-adapter-contribution.ts, type only) 그대로고 새로 더하지 않았다. - domain·application·presentation은 자기 규칙이 이미 src/adapters를 막는다. 이제 그 파일들이 src/adapters를 import하면 이 규칙도 같이 걸린다(위반 두 줄). 더 엄격해질 뿐 허용이 바뀌지는 않는다. - 지금 src/features에서 src/adapters를 import하는 곳은 reference-feature의 adapters/ 두 파일과 feature-adapter-contribution.ts뿐이라 새 위반은 없다. create:feature가 만드는 adapter import도 adapters/ 안이다. - 그래프 회귀 fixture에 support/ 재수출(거절), 그것을 읽는 presentation, 기능 adapters/ import(허용)를 더하고 check:architecture에 두 단언을 더했다. 규칙 경로를 check:architecture와 같은 방식으로 읽는 vitest 테스트를 더했다. - layers.md 표와 매뉴얼 01의 설명을 고쳤다. - 버린 대안: 계층 밖 폴더 자체를 금지(폴더 이름 목록 검사). 제품이 contracts/ 같은 다른 이름을 쓰면 계속 목록을 고쳐야 한다. 규칙마다 support/ 패턴 추가: 다음 폴더 이름에서 같은 틈이 난다. 위험·한계 - 다운스트림이 기능 안 adapters/ 밖에서 src/adapters를 import하고 있었다면 이제 check:architecture가 실패한다. 그 파일을 adapters/로 옮기면 된다. - ESLint는 여전히 간선 하나만 보므로 이 경로를 잡지 않는다. 그래프가 잡는다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/architecture/feature-adapter-reach.test.ts, corepack pnpm check:architecture(그래프 fixture 단언 2개 추가 PASS, 저장소 위반 0 기대). - RED 기대: "rejects a concrete adapter import from a feature folder that is not a layer", "leaves a feature's adapters folder and the type-only contribution file to reach adapters"(support/adapters/ 경로 단언). Refs: 0929/12-03
192 lines
13 KiB
Markdown
192 lines
13 KiB
Markdown
# 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](./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.
|
|
|
|
| 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` 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` |
|
|
| `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` | 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 |
|
|
|
|
`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/**` — 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
|
|
|
|
`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.tsx` importing the app
|
|
(`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
|
|
(`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](./frontend-ports-adapters-and-boundaries.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.
|
|
|
|
`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):
|
|
|
|
```json
|
|
{
|
|
"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.
|