Add contributing architecture doc

docs/contributing-architecture.md

@@ -0,0 +1,68 @@
+# Architecture of Javy
+
+This document is intended to provide an overview of the crates and NPM packages in Javy.
+
+## Crates
+
+```mermaid
+flowchart TD
+  javy-cli --> wasm
+  subgraph wasm[javy_core.wasm / javy_quickjs_provider.wasm]
+  javy-core --> javy
+  javy-core --> javy-apis
+  javy-apis --> javy
+  javy --> quickjs-wasm-rs
+  quickjs-wasm-rs --> quickjs-wasm-sys
+  end
+```
+
+We anticipate most changes will be to the `javy`, `javy-apis`, and `quickjs-wasm-rs` crates.
+
+### `javy`
+
+The entrypoint for working with Javy as a library for third parties. This crate is intended to compile to `wasm32-wasi` and provide ergonomic APIs for configuring a QuickJS-based runtime. If there is a configuration option for QuickJS that would be helpful, this is the place to add it.
+
+#### Important concepts
+
+- `javy::Runtime` - a configurable QuickJS runtime.
+- `javy::Config` - a configuration for the runtime.
+
+### `javy-apis`
+
+Common JS APIs for use with a `javy::Runtime`. For example, `console`, `TextEncoder`, `TextDecoder`. If there is a standard JS API that seems like it would be useful to multiple users of Javy, it should be implemented in this crate. If this is an API specific to your use case, you should define it in a crate of your own and register the implementation using a similar approach to how the APIs in this crate define their implementations.
+
+#### Adding an API implementation
+
+1. Add a feature to the crate's `Cargo.toml` for your module.
+2. Create a directory under `src` with a `mod.rs` file.
+3. If your API implementation requires configuration, create a configuration struct for the configuration properties required in your module.
+4. In `mod.rs`, implement the `crate::JSApiSet` trait. If your API requires configuration, add the configuration struct defined earlier to the `crate::ApiConfig` struct under a `#[cfg(feature = "your feature name")]` attribute.
+5. If necessary, add any JS source files inside the module you're adding.
+6. Add the `mod` to the crate's `lib.rs` under a `#[cfg(feature = "your feature name")]` attribute.
+7. Add a call to your struct's `register` method under a `#[cfg(feature = "your feature name")]` in `lib.rs`'s `add_to_runtime` function.
+
+### `javy-cli`
+
+The CLI for compiling JS to Wasm. This isn't intended to be a CLI that accommodates all uses for all users but rather to provide a useful base of functionality. This is kind of similar to how Wasmtime ships with a crate and a CLI and doing non-generic things with Wasmtime requires writing your own CLI around the Wasmtime crate.
+
+### `javy-core`
+
+Gets compiled to `javy_core.wasm` and `javy_quickjs_provider.wasm` for use by the CLI and in environments for running dynamically linked modules. This isn't intended to be used as a code library by third parties. Contains logic for driving the `javy` crate for Wasm modules generated by `javy-cli`.
+
+### `quickjs-wasm-rs`
+
+Provides an ergonomic API around the `quickjs-wasm-sys` crate as well as a `serde` implementations for `JSValueRef`.
+
+### `quickjs-wasm-sys`
+
+A Rust wrapper around the QuickJS C library.
+
+## NPM packages
+
+### `javy`
+
+A JS library providing ergonomic helpers around the lower level APIs for I/O exposed by `javy-apis`.
+
+### `javy-cli`
+
+The package that enables using the `javy-cli` through NPM. You can use `npx javy-cli` to run various Javy commands.

docs/contributing.md

@@ -1,5 +1,9 @@
 # Contributing
 
+## Architecture
+
+See our [architecture document](contributing-architecture.md) for more information about how the project is organized.
+
 ## Adding additional JS APIs
 
 We will only add JS APIs or accept contributions that add JS APIs that are potentially useful across multiple environments and do not invoke non-[WASI](https://wasi.dev/) hostcalls. If you wish to add or use JS APIs that do not meet these criteria, please use the `quickjs-wasm-rs` crate directly. We may revisit how we support importing and exporting custom functionality from Javy once [the Component Model](https://github.com/WebAssembly/component-model) has stabilized.
@@ -15,3 +19,7 @@ The versions for `javy` and `javy-apis` must always be the same. So a version ch
 After publishing a release, immediately update the version number to the next patch version with an `-alpha.1` suffix. The first time an additive change is made, reset the patch version to `0` and increment the minor version and reset the suffix to `-alpha.1`. When making additional additive changes, increment the number in the suffix, for example `-alpha.2`. The first time a breaking change is made, reset the patch version and minor version to `0` and increment the major version and reset the suffix to `-alpha.1`. When making additional breaking changes, increment the number in the suffix, for example `-alpha.2`.
 
 When releasing, remove the suffix and then publish.
+
+## cargo vet
+
+We use [cargo vet](https://mozilla.github.io/cargo-vet/) to audit dependencies for the project. If you need to change or add dependencies, please try to use a dependency that has been audited by one one of the audits we import or is published by one of the authors we trust (sunfishcode, dtolnay, Amanieu, cuviper). This is preferable to adding new exemptions for the project. Do not add new audits for crates that are not in this project.