Boundaries

Import rules between packages. These are the load-bearing walls of the codebase; a change that violates them is wrong even if it works.

Enforcement

npm run check:boundaries (checkBoundaries.ts, run by npm run check and in CI) reads every import of every workspace package and fails on:

• a relative import that leaves its package;
• an import of a workspace package its layer may not use (the table below), or from a file that may not use it, or a static import of one that may only be loaded lazily;
• an import of any package its package.json does not declare — npm hoists every dependency to the root, so an undeclared import would otherwise resolve and pass the type check;
• a node-only import (node:*, n3, @solid-memo/turtle, any package's tooling/ or node/ entry) in code that runs in the browser.
• an import of @inrupt/solid-client's access control from any file but the release publisher's, tests aside (below).

Test files follow the same rules as their subject; they and the vitest configs may also use the shared test tooling of the root package.json.

An example

A screen in ui may use what the use cases give it, since ui may import application (the table below):

// packages/ui/src/ui/DeckListContainer.tsx
import type { UseCases } from "@solid-memo/application/useCases";

It may not reach for an adapter, such as the guest's pod in solid:

// packages/ui/src/ui/SomeScreen.tsx
import { createLocalPod } from "@solid-memo/solid/localPod";

The check names the file and the rule, once for each problem, and fails:

packages/ui/src/ui/SomeScreen.tsx: @solid-memo/ui may not import @solid-memo/solid.
packages/ui/src/ui/SomeScreen.tsx: imports @solid-memo/solid, which package.json does not declare.
2 boundary problem(s).

The fix is a use case: the screen calls one on UseCases, and composition wires the adapter behind its port. A package that may import another only from some files says which. Importing the composition root anywhere in apps/web but its entry point gives:

apps/web/src/App.tsx: only files matching /^src\/main\.tsx$/ may import @solid-memo/composition.

When every import keeps to the rules, the check prints "Every package keeps to its boundaries."

Layers

Browser code: src/ of markdown, vocab, domain, application, shacl, solid, browser, composition, ui, web and studio; vocab's and markdown's tooling/ are node-only.

Vendor libraries

Each is a dependency of only the packages listed (and so, by the check, used nowhere else):

Files without a vendor library

A deck saved as a file, or read from one (studio.md), needs no library of its own:

• solid writes Turtle with @inrupt/solid-client's solidDatasetAsTurtle, and reads Turtle and JSON-LD with its getTurtleParser and getJsonLdParser. JSON-LD is written by jsonLd.ts, a few lines over the triples. n3 and @solid-memo/turtle stay out of the browser.
• browser saves and opens files with what the browser has (fileExchange.ts): a Blob behind a link with download, and a hidden <input type="file">. It is the FileExchange port; the UI never touches a file itself.

Access control

The app changes who may read something in one place only: a release it publishes is made readable by everyone (studio.md). That write is confined to the ReleasePublisher port's adapter, solidReleasePublisher.ts, which calls @inrupt/solid-client's universalAccess.setPublicAccess for the release's document alone, asking read and nothing else. The library writes that document's own ACL (Web Access Control) or ACR (Access Control Policies). No other module imports universalAccess, or writes an ACL or an ACR; no folder's access control is changed. npm run check:boundaries enforces the imports (checkBoundaries.ts, VENDOR_ONLY_FROM): outside tests, only that file may import @inrupt/solid-client's access control (universalAccess, the acp_* modules, the ACL functions), or all of the library at once (import * as). That no module writes an ACL or an ACR with a plain request is for review: the check sees imports alone.

Further rules

• UI components never import ports or adapters. They receive UseCases as a prop.
• Generated files (packages/vocab/src/*.generated.ts) are never edited by hand: change the vocabulary or the shapes in ns/ and run npm run generate (shapes.md, vocab.md).
• Modules reachable from vite.config.ts spell out .ts on relative imports: Vite can load the config with Node's own loader, which needs them. Imports between packages go through exports and carry no extension.
• Only composition wires the layers together (appUseCases.ts). The site's apps/web/src/main.tsx calls @solid-memo/composition, with what is its own (its name, where it is served, the build's values), and renders its components.
• The Studio is loaded lazily: apps/web/src/main.tsx alone imports @solid-memo/studio, with import(), so the Studio stays a chunk of its own that learners never download (studio.md).
• The site's stylesheet is ui's src/style.css, which apps/web/src/main.tsx imports; it styles ui's components, and none that only the Studio shows. The Studio's own, apps/studio/src/ui/studio.css, is imported by its shell alone (shell/StudioShell.tsx, a relative import inside the package), so it ships with the Studio's chunk, and every rule in it holds only under :root[data-surface="studio"] (studio.md).

Adding a dependency

1. Decide which single package it belongs to, and add it to that package's package.json (npm install <lib> -w @solid-memo/<package>).
2. If it performs I/O, wrap it behind a port in packages/application/src/ports.ts and implement the port in an adapter package.
3. Add it to the vendor table above.