Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-01~02-05 05-01~05-04 # Conflicts: # docs/manual/03-outside-feature-folder.md # src/bootstrap/product-composition-contract.ts # src/bootstrap/runtime-adapters.ts
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` | `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/**` — 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.
|