Architecture Navigation

Navigating the layered architecture

brepjs enforces a four-layer architecture where imports flow downward or sideways, never upward. The enforcement script is the source of truth for layer membership — CLAUDE.md and docs/architecture.md summaries lag behind it.

Layer table (source of truth: scripts/check-layer-boundaries.sh)

Rules and caveats:

• The rule is target_layer <= source_layer (the if (( target_layer > src_layer )) check in scripts/check-layer-boundaries.sh). Same-layer imports are always legal — e.g. src/topology/wrapperFns.ts imports @/operations/api.js and @/measurement/measureFns.js (both Layer 2).
• Files at the src/ root (index.ts, quick.ts, sub-path entries like topology.ts, core.ts, result.ts) are exempt — the script assigns them layer -1 and skips them. They exist to re-export everything.
• The script resolves both @/ alias and relative imports, but only greps from '...' statements — dynamic import() expressions without from are not checked. Do not rely on that gap.
• When adding a new top-level src/ directory, add it to the case statement in the get_layer() function in scripts/check-layer-boundaries.sh and to the error-message layer listing at the bottom of the same script, or its imports go entirely unchecked.

Decision procedure: where does new code belong?

Work through this list in order; stop at the first match.

1. A raw kernel/OCCT API call (anything touching oc.* or WASM objects) → a *Ops.ts file under src/kernel/occt/ (or src/kernel/brepkit/), exposed as a method on KernelAdapter in src/kernel/types.ts. Follow the /new-kernel-method command in .claude/commands/. See the kernel-abstraction skill.
2. A pure helper with no geometry dependency (string/array/math utilities) → src/utils/.
3. Shared types, Result, vectors, memory/disposal, branded shape types → src/core/ (e.g. src/core/result.ts, src/core/shapeTypes.ts, src/core/disposal.ts).
4. A shape operation (transform, boolean, modifier, query, measurement, I/O) → the matching Layer 2 module's *Fns.ts file, then climb the API ladder below. See the adding-operations skill for the full recipe.
5. High-level sugar composing Layer 2 operations (sketch DSL, text, projection, gear generators, namespace re-exports) → the matching Layer 3 module.
6. In doubt between two layers → put it in the lower layer that has everything it needs. Code can always be re-exported upward; it can never import upward.

The API ladder (Layer 2 shape operations)

New functionality goes in *Fns.ts first, then surfaces upward. The full chain (mermaid diagram in src/topology/README.md):

shape() fluent facade (wrapperFns.ts)
  → api.ts (functional public API)
    → *Fns.ts implementations
      → cast.ts / getKernel()

Checklist when adding an operation:

1. Implement in the module's *Fns.ts (e.g. src/topology/booleanFns.ts), taking/returning branded types from src/core/shapeTypes.ts, returning Result<T, E> for fallible operations (see the result-error-handling skill).

2. Add a short-named wrapper in src/topology/api.ts that accepts Shapeable<T> and delegates via resolve() (both from src/topology/apiTypes.ts), using an options object for optional parameters. Pattern:

   export function translate<T extends AnyShape<Dimension>>(shape: Shapeable<T>, v: Vec3): T {
     return transforms.translate(resolve(shape), v);
   }

3. Optionally add a chainable method on Wrapped<T> in src/topology/wrapperFns.ts — it must delegate to api.ts, never contain its own implementation.

4. Export from src/index.ts (organized by layer with // ── Layer N ── banners) and the matching sub-path entry at src/ root (topology.ts, operations.ts, etc. — table in docs/codebase-map.md).

5. Update the module's README.md if one exists (pre-commit prints a non-blocking reminder via scripts/check-readme-reminders.sh).

Import and naming rules

The @/ alias maps to ./src/* via tsconfig.json paths and vite.config.ts resolve.alias.