DongHyeonkaandClaude Opus 5
3ea3397691
Three boundaries the layer contract declares had no executable rule behind them, so the code drifted across all three while every gate stayed green. `src/contracts` reached back up into `src/application` for the shared `Result` carrier and the compatibility predicate. Neither package owned the shared vocabulary and the dependency pointed both ways. Both now live in contracts — the lower package — and application re-exports them, so no caller moves. A concrete adapter was not supposed to depend on another concrete adapter, but only adapter-to-presentation was enforced, and `diagnostics` imported a guard out of `telemetry`. The guard belongs to neither, so it moved to the adapter kernel. Stating the rule needed the checker to resolve `$1` in a `to` pattern against the importing module's own directory; the alternative is one rule per adapter group, which silently stops covering a group the moment one is added. Product assembly leaks out of bootstrap: generic presentation reads the installed-feature registries. That is a real refactor, so the rule freezes the exact set of modules doing it today rather than pretending it is fixed — a new edge fails. The two remaining open edges are named in the config, not silent. Each rule was verified by introducing the violation it forbids and confirming the gate rejects it. The documentation drifted the same way. README and the manual accessibility checklist both said six routes while ten were registered, which left the platform overview and three reference-resource screens outside the declared manual review scope without anyone deciding they should be. The scope is now derived from the route registry by `verify:documentation`, so the sentence cannot outlive the registry again. The review ledger also named a canonical path that does not exist in this tree; it is upstream provenance, and it now says so instead of looking like a broken repository reference. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
82 lines
3.9 KiB
Markdown
82 lines
3.9 KiB
Markdown
# Clean Architecture layer contract
|
|
|
|
The import direction is `domain <- application <- presentation`; concrete
|
|
adapters implement application-owned ports and are assembled only in
|
|
`src/bootstrap`.
|
|
|
|
| Layer | Owns | May depend on |
|
|
| --- | --- | --- |
|
|
| `domain` | framework-neutral models and pure policies | domain siblings |
|
|
| `application` | use cases, ports, orchestration, view-models | domain and application siblings |
|
|
| `presentation` | routes, components, user interaction and view state | application public API and shared UI |
|
|
| `adapters` | browser and third-party implementations of application ports | application ports and limited domain values |
|
|
| `features/<id>` | removable vertical domain/application/contracts/adapters/presentation slice | the same inward rule plus platform public boundaries |
|
|
| `bootstrap` | runtime configuration, adapter construction and React mount | all selected runtime modules |
|
|
|
|
The following edges are forbidden:
|
|
|
|
- domain to application, presentation, adapters, bootstrap, React, or browser globals
|
|
- application to presentation, concrete adapters, bootstrap, React, or browser globals
|
|
- `contracts` to application or features: contracts is the lower package and
|
|
owns the shared vocabulary both of them read
|
|
- presentation to concrete adapters, raw DTO schemas, or storage implementations
|
|
- generic presentation to the installed-feature registries: which features exist
|
|
is a product decision owned by `bootstrap`
|
|
- an adapter to presentation, bootstrap internals, or another concrete adapter
|
|
- feature domain/application to its presentation or outbound adapter, and
|
|
feature presentation to its outbound adapter
|
|
|
|
## The adapter kernel
|
|
|
|
"Another concrete adapter" 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 guard
|
|
- `src/adapters/browser-file-storage/result.ts` — the browser-data result and
|
|
failure constructors
|
|
|
|
Each rule above is enforced by `check:architecture`, including the kernel
|
|
carve-out, so this table and the executable rules cannot drift apart. Two edges
|
|
are still open and are named explicitly in `.dependency-cruiser.json` rather
|
|
than left silent: the generic presentation modules that read the installed
|
|
registries today, and the two collaborator types `query-cache` reads from
|
|
`cross-context-invalidation`. Both lists are frozen — a new edge of either kind
|
|
fails the gate.
|
|
|
|
`bootstrap` contains composition only. Business rules and page-specific
|
|
orchestration belong to domain/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` keeps dependency-cruiser's report and adds the
|
|
authoritative TypeScript-aware graph below it:
|
|
|
|
```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. 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.
|