Complete Guide to Rust Crates in the Buzz Monorepo

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 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:

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.
• 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.
• 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.

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.
• 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.
• 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.
• buzz-workflow — YAML-as-code workflow engine using evalexpr for condition evaluation. Source in 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.
• 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.
• 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:

# 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:

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:

cargo run -p buzz-relay

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

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
buzz-relay	crates/buzz-relay/src/main.rs
buzz-cli	crates/buzz-cli/src/main.rs
buzz-db	crates/buzz-db/src/lib.rs
buzz-pubsub	crates/buzz-pubsub/src/lib.rs
buzz-search	crates/buzz-search/src/lib.rs
buzz-workflow	crates/buzz-workflow/src/lib.rs
buzz-sdk	crates/buzz-sdk/src/event.rs
sprig	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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}