Monorepo Workspace Structure
Relevant source files
The following files were used as context for generating this wiki page:
The chkpt project is organized as a monorepo using a Cargo workspace to manage multiple interconnected components written in Rust, along with specialized bindings and plugins for different environments. This structure allows for a shared core logic while providing diverse interfaces including a Command Line Interface (CLI), Node.js native bindings (NAPI), and Model Context Protocol (MCP) servers.
The workspace is designed to separate the low-level filesystem logic, content-addressable storage, and deduplication engine from the higher-level application logic and external integrations.
Sources: CLAUDE.md:7-13, Cargo.toml:1-4, README.md:83-91
Workspace Configuration
The project utilizes Cargo's workspace feature to manage dependencies and build processes across all internal crates. The root Cargo.toml defines the members of the workspace and provides a centralized dependency management section.
Member Packages
The following table describes the primary crates included in the workspace:
| Crate Name | Directory | Description |
|---|---|---|
chkpt-core | crates/chkpt-core | Core library: scanner, storage (blob/tree/pack), indexing, and operations. |
chkpt-cli | crates/chkpt-cli | Command-line interface binary using clap and dialoguer. |
chkpt-mcp | crates/chkpt-mcp | MCP server implementation using rmcp and stdio transport. |
chkpt-napi | crates/chkpt-napi | Node.js native bindings (NAPI-RS) for JavaScript integration. |
chkpt-plugin | crates/chkpt-plugin | Claude Code plugin containing MCP tools and automation skills. |
Sources: CLAUDE.md:15-21, Cargo.toml:1-4, README.md:83-91
Shared Dependency Management
The workspace utilizes resolver = "2" and centralizes common dependencies such as tokio, serde, rusqlite, and xxhash-rust. This ensures version consistency across all internal crates.
Sources: Cargo.toml:6-33
Internal Architecture & Component Flow
The monorepo is structured such that all interface crates depend on chkpt-core, which contains the fundamental logic for content-addressable snapshots.
The diagram above illustrates how various interface crates act as wrappers or consumers of the core library logic.
Sources: CLAUDE.md:15-21, README.md:83-91
Crate Responsibilities
chkpt-core
This is the foundational crate. It implements the content-addressable deduplication using XXH3-128 hashing and LZ4 compression. Key modules include:
- Scanner: Recursively walks the workspace while respecting
.chkptignore. - Store: Manages blobs, tree structures, and pack files.
- Index: Maintains a SQLite-based index for incremental change detection.
- Ops: Orchestrates
saveandrestoreworkflows.
Sources: CLAUDE.md:16-17, README.md:20-24, crates/chkpt-core/src/config.rs
chkpt-napi
This crate provides Node.js bindings, enabling the high-performance Rust core to be called from JavaScript/TypeScript. It targets multiple platforms including Darwin, Linux, and Windows.
- NAPI Configuration: Uses
@napi-rs/clito build native artifacts. - Distribution: Defines optional dependencies for platform-specific binary packages (e.g.,
@chkpt/platform-darwin-arm64).
Sources: crates/chkpt-napi/package.json:8-33
Filesystem Layout & Storage Structure
The workspace also defines the structure of the data it generates. Snapshots are stored outside the target workspace, typically in the user's home directory.
The diagram above shows the directory layout generated and managed by the StoreLayout module in chkpt-core.
Sources: crates/chkpt-core/src/config.rs:13-57, README.md:73-81
Store Configuration Details
| Path Component | File/Directory | Purpose |
|---|---|---|
catalog_path | catalog.sqlite | Central metadata storage for snapshots and blob locations. |
index_path | index.bin | Binary index for fast incremental save operations. |
trees_dir | trees/ | Stores directory tree structures. |
packs_dir | packs/ | Compressed blob storage files. |
locks_dir | locks/ | Concurrency control for multiple processes. |
Sources: crates/chkpt-core/src/config.rs:29-57
Development Workflow
The monorepo structure supports a unified development workflow using Cargo commands from the root directory:
- Build all:
cargo build - Test all:
cargo test --workspace - Lint:
cargo clippy --workspace - Formatting:
cargo fmt --all
For the Node.js bindings, the project requires additional steps within the crates/chkpt-napi directory using pnpm.
Sources: CLAUDE.md:23-38, CONTRIBUTING.md:44-59
Summary
The chkpt monorepo workspace structure is designed to isolate the highly optimized Rust core engine (chkpt-core) from its various presentation layers. By using a Cargo workspace, the project maintains high performance and safety across a CLI, a Node.js API, and a plugin ecosystem, all while ensuring a consistent storage format and shared metadata management through SQLite and binary indexing.