# 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//{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//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//domain` | application, presentation, adapters, bootstrap, any feature's application, adapters and presentation, React, TanStack | | `feature-application-does-not-know-runtime` | `src/features//application` | presentation, adapters, bootstrap, any feature's adapters and presentation, React, TanStack | | `feature-presentation-does-not-know-outbound-adapters` | `src/features//presentation` | adapters, bootstrap, any feature's adapters, TanStack | | `feature-adapters-do-not-know-presentation` | `src/features//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//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.