# Complete Guide to Rust Crates in the Buzz Monorepo

> Discover the 29 Rust crates within the Buzz monorepo. Learn how this Cargo workspace streamlines builds and manages dependencies for efficient development.

- Repository: [Block Open Source/buzz](https://github.com/block/buzz)
- Tags: deep-dive
- Published: 2026-08-28

---

**The Buzz monorepo organizes its functionality into 29 independent Rust crates located in the `crates/` directory, all unified under a single Cargo workspace for shared builds and dependency management.**

The **block/buzz** repository implements a Nostr-based communication platform using a workspace-based architecture. Each Rust crate in the `crates/` directory maintains its own [`Cargo.toml`](https://github.com/block/buzz/blob/main/Cargo.toml) while participating in a unified build system that enables cross-crate dependencies and a shared lockfile. This guide maps the complete crate structure and provides entry points into the source code.

## Workspace Architecture and Build System

The Buzz project uses Cargo's **workspace** feature to manage dozens of related packages. Because all crates reside under a single workspace root, you can build the entire system with one command:

```bash
cargo build --workspace

```

Individual crates live in isolated subdirectories under `crates/`, with each containing its own manifest. This structure allows fine-grained dependency management—crates like `buzz-core` and `buzz-sdk` serve as foundational libraries, while `buzz-relay` and `buzz-cli` function as standalone binaries.

## Core Infrastructure Crates

These Rust crates provide the foundational data types, storage, and verification logic used throughout the Buzz monorepo.

- **buzz-core** — Defines core data types, event verification algorithms, filter matching, and the event kind registry. Key logic resides in [`crates/buzz-core/src/kind.rs`](https://github.com/block/buzz/blob/main/crates/buzz-core/src/kind.rs).
- **buzz-db** — Implements the Postgres-based event store and data-access layer. The public API surface is exported from [`crates/buzz-db/src/lib.rs`](https://github.com/block/buzz/blob/main/crates/buzz-db/src/lib.rs).
- **buzz-auth** — Handles authentication and authorization for the relay, including NIP-42 and JWT implementations.
- **buzz-audit** — Maintains an immutable, hash-chain audit log for event provenance tracking.
- **buzz-deletion** — Encapsulates soft-deletion logic while preserving audit trail integrity.
- **buzz-sdk** — Provides typed Nostr event builders for client applications. Reference implementation available in [`crates/buzz-sdk/src/event.rs`](https://github.com/block/buzz/blob/main/crates/buzz-sdk/src/event.rs).

## Relay and Networking Crates

These crates implement the WebSocket relay, mesh networking, and real-time communication infrastructure.

- **buzz-relay** — The central WebSocket relay server implementing NIP-29, hosting git repositories, huddle audio, and Nostr events. Entry point at [`crates/buzz-relay/src/main.rs`](https://github.com/block/buzz/blob/main/crates/buzz-relay/src/main.rs).
- **buzz-relay-mesh** — Mesh networking layer that connects multiple relay instances into a distributed topology.
- **buzz-pair-relay** — Ephemeral sidecar relay specifically for NIP-AB device pairing operations.
- **buzz-pubsub** — Redis-based pub/sub fan-out system handling presence indicators and typing notifications. Core implementation in [`crates/buzz-pubsub/src/lib.rs`](https://github.com/block/buzz/blob/main/crates/buzz-pubsub/src/lib.rs).
- **buzz-ws-client** — Shared WebSocket client library implementing NIP-42 authentication for client connections.
- **buzz-push-gateway** — HTTP push gateway that forwards inbound events to the relay infrastructure.

## Agent and Protocol Crates

The ACP (Agent-Control-Protocol) ecosystem enables AI agent integration and automation.

- **buzz-acp** — ACP harness that bridges Buzz events to AI agents following the Agent Control Protocol.
- **buzz-agent** — Minimal, non-streaming ACP-compliant agent reference implementation.
- **buzz-dev-mcp** — Developer MCP server providing shell access and file-edit tools for agent development.
- **buzz-persona** — Pre-defined agent personality packs for consistent agent behavior.
- **sprig** — All-in-one harness bundling ACP, agents, and dev-MCP for rapid prototyping. Entry point at [`crates/sprig/src/main.rs`](https://github.com/block/buzz/blob/main/crates/sprig/src/main.rs).
- **buzz-workflow** — YAML-as-code workflow engine using `evalexpr` for condition evaluation. Source in [`crates/buzz-workflow/src/lib.rs`](https://github.com/block/buzz/blob/main/crates/buzz-workflow/src/lib.rs).

## Client Applications and CLI Tools

End-user binaries and administrative utilities.

- **buzz-cli** — Primary user-facing command-line client designed for agent-first interactions. Main binary at [`crates/buzz-cli/src/main.rs`](https://github.com/block/buzz/blob/main/crates/buzz-cli/src/main.rs).
- **buzz-admin** — Operator-level CLI for relay administration, user management, and diagnostic operations.
- **buzz-pairing-cli** — Testing utility for NIP-AB device pairing interoperability.

## Storage, Search, and Media

Specialized data handling and content delivery.

- **buzz-search** — Full-text search implementation powered by Postgres FTS (NIP-50). Library root at [`crates/buzz-search/src/lib.rs`](https://github.com/block/buzz/blob/main/crates/buzz-search/src/lib.rs).
- **buzz-media** — Media upload and download integration with Blossom protocol and S3-compatible storage backends.
- **buzz-datastore-tracing** — OpenTelemetry tracing utilities for the datastore layer.

## Git Integration and Utilities

Native git tooling leveraging Nostr cryptographic primitives.

- **git-credential-nostr** — Git credential helper authenticating via Nostr keys instead of traditional passwords.
- **git-sign-nostr** — Tool for cryptographically signing git objects using Nostr keys.

## Testing and Platform Support

Development and deployment utilities.

- **buzz-test-client** — Integration test client and end-to-end test suite for the entire platform.
- **buzz-voice** — Voice-related utilities and future speech-to-text/text-to-text infrastructure.
- **buzz-back-end-kubernetes** — Kubernetes deployment helpers and manifests for the relay service.

## Adding Buzz Crates as Dependencies

Because all Rust crates in the Buzz monorepo belong to a single workspace, you can reference them using relative paths during local development:

```toml

# In your crate's Cargo.toml

[dependencies]
buzz-core = { path = "../buzz-core", version = "0.1" }
buzz-sdk = { path = "../buzz-sdk", version = "0.1" }

```

For published versions, omit the `path` attribute and rely on the registry version specified in the workspace root.

## Using the SDK to Create Events

The `buzz-sdk` crate provides ergonomic builders for constructing Nostr events:

```rust
use buzz_sdk::event::EventBuilder;
use buzz_sdk::kind::Kind;

// Build a simple text note (kind 1)
let ev = EventBuilder::new()
    .kind(Kind::TextNote)
    .content("Hello from Buzz!")
    .build()
    .sign(your_private_key)?;

```

## Running Components Locally

Launch the WebSocket relay server:

```bash
cargo run -p buzz-relay

```

This starts the relay at `ws://localhost:3000`. Alternatively, run the CLI client to interact with channels:

```bash
buzz --format compact channels list

```

## Key Source Files by Crate

For developers navigating the codebase, these files represent the primary entry points for each major component:

| Crate | Representative Source File |
|-------|-------------------------|
| buzz-core | [`crates/buzz-core/src/kind.rs`](https://github.com/block/buzz/blob/main/crates/buzz-core/src/kind.rs) |
| buzz-relay | [`crates/buzz-relay/src/main.rs`](https://github.com/block/buzz/blob/main/crates/buzz-relay/src/main.rs) |
| buzz-cli | [`crates/buzz-cli/src/main.rs`](https://github.com/block/buzz/blob/main/crates/buzz-cli/src/main.rs) |
| buzz-db | [`crates/buzz-db/src/lib.rs`](https://github.com/block/buzz/blob/main/crates/buzz-db/src/lib.rs) |
| buzz-pubsub | [`crates/buzz-pubsub/src/lib.rs`](https://github.com/block/buzz/blob/main/crates/buzz-pubsub/src/lib.rs) |
| buzz-search | [`crates/buzz-search/src/lib.rs`](https://github.com/block/buzz/blob/main/crates/buzz-search/src/lib.rs) |
| buzz-workflow | [`crates/buzz-workflow/src/lib.rs`](https://github.com/block/buzz/blob/main/crates/buzz-workflow/src/lib.rs) |
| buzz-sdk | [`crates/buzz-sdk/src/event.rs`](https://github.com/block/buzz/blob/main/crates/buzz-sdk/src/event.rs) |
| sprig | [`crates/sprig/src/main.rs`](https://github.com/block/buzz/blob/main/crates/sprig/src/main.rs) |

## Summary

- The Buzz monorepo contains **29 Rust crates** organized under a single Cargo workspace in the `crates/` directory.
- **buzz-core** and **buzz-sdk** provide foundational types and client builders used by other crates.
- **buzz-relay** serves as the central WebSocket server, while **buzz-relay-mesh** enables distributed topologies.
- **buzz-acp**, **buzz-agent**, and **sprig** implement the Agent Control Protocol for AI integration.
- All crates share a common lockfile and build configuration, supporting both independent development and unified deployment via `cargo build --workspace`.

## Frequently Asked Questions

### How do I build all Rust crates in the Buzz monorepo at once?

Run `cargo build --workspace` from the repository root. This command compiles all 29 crates while respecting the dependency graph defined in the workspace-level [`Cargo.toml`](https://github.com/block/buzz/blob/main/Cargo.toml), ensuring that foundational libraries like `buzz-core` build before dependent binaries like `buzz-relay` or `buzz-cli`.

### Which crate should I use for building a custom Buzz client?

Use **buzz-sdk** for client applications. Located in `crates/buzz-sdk`, it provides typed event builders (`EventBuilder`), kind definitions, and NIP-compatible structures. Import it as a dependency and reference [`src/event.rs`](https://github.com/block/buzz/blob/main/src/event.rs) for implementation patterns.

### How do the Buzz crates handle authentication across the relay?

The **buzz-auth** crate centralizes authentication logic, implementing NIP-42 for WebSocket authentication and JWT handling. The **buzz-ws-client** crate consumes these implementations to provide authenticated WebSocket connections for client applications.

### What is the difference between buzz-relay and buzz-pair-relay?

**buzz-relay** (`crates/buzz-relay`) is the persistent, production WebSocket server hosting git, audio, and Nostr events. **buzz-pair-relay** (`crates/buzz-pair-relay`) is an ephemeral sidecar process specifically for NIP-AB device pairing, designed to run temporarily during device onboarding rather than as a long-lived service.