Architecture

Keep core domain behavior in ordinary Rust crates/modules. Keep JavaScript boundary concerns in a thin NAPI layer.
Treat the NAPI package as both a Rust crate and an npm package. Rust exports native functions with #[napi]; JavaScript files often wrap, patch, or select native/WASI/browser entrypoints.
Put reusable bridge helpers in a small shared Rust module/crate when multiple packages need the same diagnostics, option conversion, span conversion, or serialization logic.
Keep the public API shape as a cross-language contract: update Rust exports, generated .d.ts, JS wrappers, package tests, and docs together.
Avoid leaking internal Rust lifetimes, allocator ownership, or implementation-only types into the JS API. Convert at the boundary.

Directory Layout

Common monorepo layout: crates/core-* for Rust logic, napi/<package> or packages/<package> for NAPI crates/npm packages, and optional crates/*_napi or crates/node_bridge for shared bridge helpers.
Common single-package layout: src/lib.rs for NAPI exports, package.json for npm metadata and napi config, index.js for wrappers, index.d.ts or generated definitions for TypeScript, and test/ for JS-level tests.
Keep generated native artifacts, generated bindings, and platform packages separate from source files.
Check local conventions before adding new files; napi-rs projects vary between one package per crate and one crate exposing many JS APIs.

Avoid editing generated files unless the task is specifically to update generated artifacts.