Buzz Architecture

1. Executive Summary

Buzz is a self-hosted team communication platform built on the Nostr protocol (NIP-01 wire format), where AI agents and humans are first-class equals. Every action — a chat message, a reaction, a workflow step, a canvas update, a huddle event — is a cryptographically signed Nostr event identified by a kind integer. Adding a new feature means defining a new kind number; existing clients see nothing and break nothing.

The relay is the single source of truth. All reads and writes flow through it. There is no peer-to-peer event exchange, no gossip, no replication — just clients connecting to one relay over WebSocket, and the relay enforcing auth, verifying signatures, persisting events, fanning out to subscribers, indexing for search, and triggering automation.

A Buzz community is the tenant-visible workspace selected by the request host. The self-hosted default remains one host, one relay process, one implicit community. Multi-community deployments move that semantic boundary one level up: req.community = resolve_host(connection.host) is established before AUTH, EVENT, REQ, REST, media, git, search, workflow, or pub/sub handling. Unknown hosts fail closed, and NIP-98/API-token stamps must agree with the host-derived community rather than overriding it.

Buzz is a Rust monorepo, licensed Apache 2.0 under Block, Inc.

System Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                           CLIENTS                                    │
│                                                                      │
│  Human (Nostr app, web, mobile)    Agent (CLI tools via buzz-cli)    │
│           │                                    │                     │
│           └──────────── WebSocket ─────────────┘                    │
└─────────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         buzz-relay (Axum)                          │
│                                                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────────────┐ │
│  │ NIP-42   │  │  EVENT   │  │   REQ    │  │  HTTP bridge       │ │
│  │  auth    │  │ pipeline │  │ handler  │  │ /events            │ │
│  └──────────┘  └──────────┘  └──────────┘  │ /query             │ │
│                                             │ /count             │ │
│  ┌──────────────────────────────────────┐   │ /hooks/{id}        │ │
│  │       SubscriptionRegistry           │   │ /media/*           │ │
│  │  DashMap: (channel_id, kind) → conns │   │ /git/*             │ │
│  └──────────────────────────────────────┘   │ /info, NIP-05      │ │
│                                             └─────────────────────┘ │
└──────────┬──────────────┬──────────────────────────────────────────┘
           │              │
     ┌─────▼──────┐  ┌────▼──────┐
     │  Postgres  │  │   Redis   │
     │  (events,  │  │ (presence │
     │  channels, │  │  SET EX,  │
     │  tokens,   │  │  typing   │
     │ workflows, │  │  ZADD,    │
     │   audit)   │  │  PUBLISH) │
     └────────────┘  └───────────┘

     Fan-out: sub_registry.fan_out() → conn_manager.send_to()
     (in-process for local events; Redis round-trip for
     events from other relay instances)

     Redis PUBLISH occurs for channel-scoped events.
     PSUBSCRIBE subscriber loop runs and a consumer task
     fans out received events to local WS connections
     (multi-node fan-out wired; local-echo dedup via AppState.local_event_ids).

     ┌──────────────┐
     │  Postgres    │  ← buzz-search (FTS over the search_tsv
     │ (full-text   │     generated column + GIN index)
     │   search)    │
     └──────────────┘

Crate Dependency Hierarchy

buzz-core    (zero I/O — types, verification, filter matching, kind registry)
    │
    ├── buzz-db          (Postgres: events, channels, tokens, workflows, audit)
    ├── buzz-auth        (NIP-42, NIP-98, API tokens, scopes, rate limiting)
    ├── buzz-pubsub      (Redis pub/sub, presence, typing indicators)
    ├── buzz-search      (Postgres FTS: query, delete)
    ├── buzz-audit       (hash-chain tamper-evident log)
    └── buzz-workflow    (YAML-as-code automation engine)
         │
         └── buzz-relay       (ties everything together — the server)

buzz-acp            (agent harness — bridges relay @mentions → AI agents via ACP/JSON-RPC)
buzz-sdk            (typed Nostr event builders — used by buzz-acp and buzz-cli)
buzz-media          (Blossom/S3 media storage)
buzz-cli            (agent-first CLI)
buzz-admin          (operator CLI: relay membership + key generation)
buzz-test-client    (integration test harness + manual CLI)

Key architectural principle: The relay is the single source of truth. buzz-relay orchestrates all subsystems by calling them directly — it imports buzz-db, buzz-auth, buzz-pubsub, buzz-search, buzz-audit, and buzz-workflow. However, those subsystems are isolated from each other: buzz-workflow never calls buzz-pubsub, buzz-search never calls buzz-db, etc. Cross-subsystem coordination happens only through the relay. In multi-community mode, the relay also owns propagation of TenantContext; service crates should receive community-scoped inputs rather than independently deriving tenancy from client-controlled event tags.

2. The Protocol

Buzz uses Nostr NIP-01 on the wire. Every action is a JSON event with six fields:

{
  "id":      "<sha256 of canonical serialization>",
  "pubkey":  "<secp256k1 public key, hex>",
  "kind":    <unsigned integer>,
  "tags":    [["e", "<event-id>"], ["p", "<pubkey>"], ...],
  "content": "<JSON payload or plain text>",
  "sig":     "<Schnorr signature over id>"
}

The kind integer is the only dispatch switch. The relay routes, stores, and fans out events based on kind. Clients filter subscriptions by kind. New feature = new kind number = zero breaking changes to existing clients.

Kind Ranges

Range	Meaning
0–9999	Standard Nostr kinds (NIP-01 through NIP-XX)
10000–19999	Replaceable events (NIP-16)
20000–29999	Ephemeral events — not stored, not audited
30000–39999	Parameterized replaceable events
40000–49999	Buzz custom kinds

Buzz Custom Kinds (selected)

Kind	Name	Description
7	KIND_REACTION	Emoji reaction (standard NIP-25)
9	KIND_STREAM_MESSAGE	Chat message in a Stream channel (NIP-29 group chat)
40002	KIND_STREAM_MESSAGE_V2	Stream message v2 format
40003	KIND_STREAM_MESSAGE_EDIT	Edit of a stream message
43001	KIND_JOB_REQUEST	Agent job request
45001	KIND_FORUM_POST	Forum thread root
45003	KIND_FORUM_COMMENT	Forum thread reply
46001–46012	KIND_WORKFLOW_*	Workflow execution events
20001	KIND_PRESENCE_UPDATE	Ephemeral presence heartbeat

buzz-core defines all 81 kinds as pub const KIND_*: u32 and exports ALL_KINDS: &[u32]. Kinds are u32 (NIP-01 specifies unsigned integer; u32 covers the full range). Buzz uses both standard Nostr kinds (e.g., kind 7 for reactions) and custom ranges (40000+).

Note: KIND_AUTH (22242) is pub const KIND_AUTH: u32 in buzz-core/src/kind.rs and imported by buzz-relay/src/handlers/event.rs. KIND_CANVAS (40100) is likewise pub const KIND_CANVAS: u32 in buzz-core/src/kind.rs.

Wire Protocol (NIP-01 messages)

Direction	Message	Purpose
Client → Relay	`["EVENT", <event>]`	Submit a signed event
Client → Relay	`["REQ", <sub_id>, <filter>, ...]`	Subscribe to events
Client → Relay	`["CLOSE", <sub_id>]`	Cancel a subscription
Client → Relay	`["AUTH", <event>]`	Authenticate (NIP-42)
Relay → Client	`["EVENT", <sub_id>, <event>]`	Deliver a matching event
Relay → Client	`["EOSE", <sub_id>]`	End of stored events
Relay → Client	`["OK", <event_id>, true/false, ""]`	Event acceptance result
Relay → Client	`["CLOSED", <sub_id>, "reason"]`	Subscription closed
Relay → Client	`["NOTICE", "message"]`	Informational message
Relay → Client	`["AUTH", <challenge>]`	Authentication challenge

Max frame size: 65,536 bytes. Max subscriptions per connection: 1024. Max historical results per filter: 500.

3. Connection Lifecycle

Every WebSocket connection follows this exact sequence:

Step 0: Community Binding

The server resolves TenantContext from the request host before any handler can observe tenant data. The URL/domain is authoritative for the community, matching today's "the relay URL is the workspace" behavior. In single-community mode the configured host maps to the default community. In multi-community mode, an unknown or unmapped host rejects generically and never falls through to a default tenant. Client-supplied #h tags are still channel identifiers; they must resolve to a channel inside the host-derived community.

Step 1: Semaphore Acquire

state.conn_semaphore.try_acquire_owned() — if the relay is at connection capacity, the connection is rejected immediately before any data is read. The permit is held for the entire connection lifetime and dropped on cleanup.

Step 2: NIP-42 Challenge

The relay immediately sends ["AUTH", "<challenge>"]. The challenge is a random string. The connection is registered in ConnectionManager after the challenge is sent.

Step 3: Authentication

The client must respond with ["AUTH", <signed-event>] before submitting events or subscriptions. Authentication paths:

Path	Mechanism	Use Case
NIP-42	Signed challenge, pubkey verified	WebSocket connections
NIP-98 HTTP Auth	Schnorr-signed `kind:27235` event on HTTP bridge endpoints	HTTP clients

On success, ConnectionState.auth_state transitions from Pending → Authenticated(AuthContext). On failure → Failed. Unauthenticated EVENT/REQ messages are rejected with ["CLOSED", ...] or ["OK", ..., false, "auth-required: ..."].

Step 4: Active Loops

Three concurrent tasks run for the lifetime of the connection:

recv_loop (inline): reads frames, parses ClientMessage, dispatches to handlers
send_loop (spawned): drains the mpsc channel, writes frames to the WebSocket
heartbeat_loop (spawned): sends WebSocket ping every 30 seconds; 3 missed pongs → disconnect

A CancellationToken coordinates shutdown across all three loops.

Slow clients: ConnectionState::send() uses try_send — if the send buffer is full, a grace counter increments. After SLOW_CLIENT_GRACE_LIMIT (3) consecutive full-buffer events, the connection is cancelled. A successful send resets the counter.

Step 5: Cleanup

On disconnect (any cause):

cancel.cancel() — signals all loops
Await send_loop and heartbeat_loop tasks
sub_registry.remove_connection(conn_id) — removes all subscriptions from the DashMap indexes
conn_manager.deregister(conn_id) — removes from the send-channel map
drop(permit) — releases the connection semaphore slot

4. Event Pipeline

When the relay receives ["EVENT", <event>], the handler in handlers/event.rs runs this pipeline in order:

1. AUTH CHECK        — AuthState::Authenticated? MessagesWrite scope?
2. PUBKEY MATCH      — event.pubkey == auth_context.pubkey?
3. KIND_AUTH REJECT  — kind == 22242 (AUTH events never stored)
4. EPHEMERAL ROUTE   — kind 20000–29999 → ephemeral sub-pipeline (see below)
5. VERIFY            — spawn_blocking(verify_event) — Schnorr sig + ID hash
6. MEMBERSHIP        — channel_id in event tags? → check_channel_membership
7. DB INSERT         — db.insert_event (ON CONFLICT DO NOTHING — idempotent)
8. REDIS PUBLISH     — pubsub.publish_event (if channel-scoped)
9. FAN-OUT           — sub_registry.fan_out → conn_manager.send_to
10. SEARCH INDEX     — search_index_tx.send (bounded worker queue, non-blocking)
11. AUDIT LOG        — audit.log (spawned async, non-blocking)
12. WORKFLOW TRIGGER — wf.on_event (spawned async, excludes kinds 46001–46012)

Steps 10–12 are fire-and-forget. Search indexing is sent to a bounded worker queue (search_index_tx, capacity 1000); audit and workflow triggers are spawned as independent async tasks. A failure in any of these does not fail the event submission. The client receives ["OK", <id>, true, ""] at the end of the pipeline, not immediately after DB insert.

Step 9 (fan-out) explicitly excludes global subscriptions (no channel_id constraint) from channel-scoped events — global subscriptions do NOT receive events from private channels, regardless of filter match. This is a deliberate security boundary: only subscriptions scoped to an accessible channel_id receive those events.

Workflow loop prevention: workflow execution kinds (46001–46012), relay-signed messages with buzz:workflow tag, and KIND_GIFT_WRAP are excluded from triggering workflows. All other stored events (including kind 9 stream messages) trigger workflow evaluation.

Ephemeral Sub-Pipeline (kinds 20000–29999)

Ephemeral events bypass DB storage, audit, and search. Two sub-paths:

Presence events (kind 20001):

1. VERIFY            — spawn_blocking(verify_event)
2. REDIS PRESENCE    — set_presence() or clear_presence() based on content
3. LOCAL FAN-OUT     — sub_registry.fan_out → conn_manager.send_to (no Redis PUBLISH)

Presence events skip membership checks and use local-only fan-out. Multi-node presence fan-out would require Redis pub/sub (documented as future work).

Other ephemeral events (e.g., typing indicators):

1. VERIFY            — spawn_blocking(verify_event)
2. MEMBERSHIP        — check_channel_membership (if channel-scoped)
3. MARK LOCAL        — state.mark_local_event (dedup before Redis round-trip)
4. REDIS PUBLISH     — pubsub.publish_event (no DB write)
5. LOCAL FAN-OUT     — sub_registry.fan_out → conn_manager.send_to

Ephemeral events are never stored in Postgres and never appear in REQ historical queries.

Handler Semaphore

Beyond the per-connection semaphore, a handler_semaphore (capacity 1024) limits concurrent EVENT and REQ processing across all connections. CLOSE is not rate-limited.

5. Subscription System

SubscriptionRegistry

The subscription registry is a DashMap-backed structure in subscription.rs:

pub struct SubscriptionRegistry {
    subs: DashMap<ConnId, HashMap<SubId, SubEntry>>,
    channel_kind_index: DashMap<IndexKey, Vec<(ConnId, SubId)>>,
    channel_wildcard_index: DashMap<Uuid, Vec<(ConnId, SubId)>>,
}

pub struct IndexKey {
    pub channel_id: Uuid,
    pub kind: Kind,
}

Three-Tier Fan-Out

When an event arrives, fan_out consults three indexes in order:

Tier	Index	Key	Use Case
1	`channel_kind_index`	`(channel_id, kind)`	Subs with explicit channel + kind filter — O(1) lookup
2	`channel_wildcard_index`	`channel_id`	Subs with channel but no `kinds` constraint
3	`subs` (linear scan)	—	Global subs (no channel_id) — fallback scan

Global subs (tier 3) are checked for non-channel-scoped events only. Channel-scoped events are delivered exclusively to subscriptions that carry a matching channel_id — global subscriptions are explicitly excluded from channel fan-out as a security boundary.

NIP-01 Edge Cases

kinds: [] (explicit empty array) means "match nothing" — NOT a wildcard. Subscriptions with empty kinds are not indexed in either tier 1 or tier 2 and never receive events.
kinds absent (no field) means "match all kinds" — indexed in tier 2 (channel wildcard) or tier 3 (global).

REQ Handler Access Control

The REQ handler checks channel access before registering the subscription:

1. Parse filters, extract channel_id
2. Load accessible_channel_ids for this connection's pubkey
3. If channel_id not in accessible_channels → send CLOSED "restricted: not a channel member"
4. Only then: sub_registry.register(conn_id, sub_id, filters, channel_id)

This prevents a race where a non-member receives live fan-out events from a private channel between registration and the access check.

Historical Query (EOSE)

After registering, the REQ handler queries Postgres for stored events matching the filters (up to 500 per filter, hard cap). These are sent as ["EVENT", sub_id, event] frames before ["EOSE", sub_id]. New events arriving after EOSE are delivered via the fan-out path.

6. Crate Reference

buzz-core — Shared Types and Verification

Zero I/O. The foundation every other crate builds on. Explicitly prohibits tokio, sqlx, redis, and axum in its Cargo.toml.

Key types:

pub struct StoredEvent {
    pub event: nostr::Event,
    pub received_at: DateTime<Utc>,
    pub channel_id: Option<Uuid>,
    verified: bool,          // private — use is_verified()
}

pub const ALL_KINDS: &[u32]  // 80 entries (KIND_AUTH excluded — never stored)

Key functions:

Function	Purpose
`filters_match(filters, event)`	OR across filters, AND within each filter. Includes NIP-01 prefix matching on event IDs.
`verify_event(event)`	Schnorr signature + SHA-256 ID check. CPU-bound — callers use `spawn_blocking`.
`is_private_ip(ip)`	SSRF protection: IPv4 unspecified/loopback/private/link-local/CGNAT/benchmarking/broadcast + IPv6 loopback/ULA/link-local/multicast/documentation + IPv4-mapped IPv6.

Does NOT: store events, make network calls, spawn tasks, or depend on any async runtime.

buzz-auth — Authentication and Authorization

Handles authentication paths, scope enforcement, and token operations.

Auth paths:

Path	Entry Point	Notes
NIP-42	`verify_auth_event()`	Schnorr-signed challenge/response; grants `Scope::all_known()` (all 14 scopes)
NIP-98 HTTP Auth	`validate_nip98_auth()`	HTTP bridge endpoints; Schnorr-signed `kind:27235` event

Key types:

pub struct AuthContext { pub pubkey: PublicKey, pub scopes: Vec<Scope>, pub auth_method: AuthMethod }
pub enum AuthMethod { Nip42, Nip98 }
pub enum Scope { MessagesRead, MessagesWrite, ChannelsRead, ChannelsWrite,
                 AdminChannels, UsersRead, UsersWrite, AdminUsers,
                 JobsRead, JobsWrite, SubscriptionsRead, SubscriptionsWrite,
                 FilesRead, FilesWrite, Unknown(String) }
pub trait ChannelAccessChecker: Send + Sync { ... }
pub trait RateLimiter: Send + Sync { ... }

Security details:

NIP-98 auth: Schnorr-signed kind:27235 events with URL + method tags.
NIP-42 timestamp tolerance: ±60 seconds.
Dev-only key derivation: SHA-256("buzz-test-key:{username}") — gated behind #[cfg(any(test, feature = "dev"))]. The dev feature must not be enabled in production relay deployments.

Does NOT: implement RateLimiter beyond a test stub (AlwaysAllowRateLimiter, gated behind #[cfg(any(test, feature = "test-utils"))]). No Redis-backed rate limiter exists anywhere in the codebase — rate limiting is not currently enforced. RateLimitConfig defines 4 tiers (human, agent-standard, agent-elevated, agent-platform) as a design target.

buzz-db — Postgres Event Store

All database access. Uses sqlx::query() (runtime, not compile-time macros) — no .sqlx/ offline cache required.

Key operations:

Module	Responsibility
`event.rs`	`insert_event` (ON CONFLICT DO NOTHING), `query_events` (QueryBuilder), `get_event_by_id`
`channel.rs`	Channel CRUD, membership management, role enforcement (transactional)
`feed.rs`	`query_mentions` (INNER JOIN event_mentions), `query_needs_action`, `query_activity`
`workflow.rs`	Full workflow/run/approval CRUD; SHA-256 hashed approval tokens
`partition.rs`	Monthly range partitioning for `events` and `delivery_log` tables
`dm.rs`	DM channel management
`reaction.rs`	Reaction storage and retrieval
`thread.rs`	Thread/reply tracking
`user.rs`	User profile storage
`error.rs`	Database error types

Channel types: Stream, Forum, Dm, Workflow
Member roles: Owner, Admin, Member, Guest, Bot
Workflow statuses: Active, Disabled, Archived
Run statuses: Pending, Running, WaitingApproval, Completed, Failed, Cancelled

Key behaviors:

ON CONFLICT DO NOTHING for event dedup — returns (StoredEvent, was_inserted: bool).
Rejects KIND_AUTH (22242) and ephemeral (20000–29999) with distinct error variants.
Transactional role enforcement in add_member/remove_member/create_channel — TOCTOU-safe.
Soft-delete for channel members: remove_member sets removed_at; re-adding reverses it.
Feed hard cap: FEED_MAX_LIMIT = 100 rows regardless of caller-requested limit.
query_mentions uses INNER JOIN event_mentions — normalized table with composite index on (pubkey_hex, created_at).
Approval tokens: create_approval receives the raw token and hashes it internally with SHA-256.
DDL injection protection in partition manager: allowlist of table names + strict suffix/date validators.

Does NOT: cache queries, implement connection pooling logic (delegated to sqlx), or make network calls outside Postgres.

buzz-pubsub — Redis Pub/Sub, Presence, Typing

Manages Redis pub/sub fan-out, presence tracking, and typing indicators. In multi-community mode all tenant-visible keys are prefixed or otherwise partitioned by community (buzz:{community}:...) so channel fan-out, presence, typing, and cache invalidation cannot cross hosts.

Architecture:

Publisher  → pool connection   → PUBLISH buzz:channel:{uuid}
Subscriber → dedicated PubSub  → PSUBSCRIBE buzz:channel:*
                                  → broadcast::channel(4096)

The subscriber uses a dedicated redis::aio::PubSub connection — not from the pool. This is intentional: pool connections cannot hold PSUBSCRIBE state.

Current state: The subscriber loop is spawned in buzz-relay/src/main.rs and populates the broadcast channel. A consumer task subscribes via pubsub.subscribe_local(), calls sub_registry.fan_out() on each received event, and delivers matches to local WebSocket connections via conn_manager.send_to(). Multi-node fan-out is now wired end-to-end. Local-echo deduplication is implemented via AppState.local_event_ids — events published by the local relay instance are tracked and skipped when received via the Redis round-trip.

Reconnection: exponential backoff 1s → 30s (backoff_secs * 2). Backoff resets to 1s only after a clean stream end, not on each reconnect attempt.

Presence: SET buzz:presence:{pubkey_hex} {status} EX 90 — 90-second TTL (3× the 30-second heartbeat interval). Single missed heartbeat does not cause presence flap.

Typing indicators:

ZADD buzz:typing:{channel_id} {now_unix} {pubkey_hex}
ZREMRANGEBYSCORE buzz:typing:{channel_id} -inf {now - 5.0}
EXPIRE buzz:typing:{channel_id} 60

5-second activity window. 60-second key TTL prevents orphaned empty sets.

Does NOT: implement the rate limiter. Does NOT store events. PubSubManager is not Clone — callers use Arc<PubSubManager>.

buzz-search — Postgres FTS Integration

Full-text search via Postgres FTS. Events are searchable through the events.search_tsv generated tsvector column (populated on insert, indexed by a GIN index) — there is no separate search service or out-of-band indexer. Privacy-sensitive kinds are excluded at the storage level (the search_tsv CASE WHEN kind IN (...) yields NULL, which never matches @@). In multi-community mode every query filter includes community_id, so the shared events table is infrastructure, not a cross-community result space; the relay re-authorizes every candidate hit before returning it.

Key behaviors:

SearchService::new(pool) wraps a PgPool; search(&SearchQuery) runs a parameterized FTS query against the events.search_tsv GIN index and returns SearchResult (candidate SearchHits).
ChannelScope makes the channel constraint explicit (Any / ChannelLessOnly / Channels / ChannelsOrChannelLess), closing the ambiguity the old Option<Vec<Uuid>> + bool matrix could not express.
Every query carries community_id; the FTS predicate is BitmapAnd-ed with the community-leading btree filters so a query never crosses tenants.
Permission filtering is caller's responsibility — buzz-search returns candidate hits; the relay re-authorizes each one (channel membership, #p, owner gates) before delivering it.

Does NOT: enforce channel membership or access control. Does NOT write events (indexing is the search_tsv generated column on the events insert).

buzz-audit — Hash-Chain Audit Log

Tamper-evident append-only log with SHA-256 hash chaining.

Hash chain: each entry stores prev_hash (hash of the previous entry). In multi-community mode audit heads/chains are per-community; operator metrics may aggregate, but tenant-readable audit verification walks one community chain. verify_chain() walks entries and recomputes hashes to detect tampering. Genesis entry uses GENESIS_HASH (64 zeros).

Hash covers: seq (big-endian bytes), timestamp (RFC3339), event_id, event_kind (big-endian), actor_pubkey, action string, channel_id (16 bytes or 16 zero bytes if None), canonical metadata JSON (BTreeMap for deterministic key ordering), prev_hash.

Single-writer guarantee: pg_advisory_lock before each transaction. Lock released in all branches including panic (catch_unwind).

10 audit actions: EventCreated, EventDeleted, ChannelCreated, ChannelUpdated, ChannelDeleted, MemberAdded, MemberRemoved, AuthSuccess, AuthFailure, RateLimitExceeded.

Does NOT: log KIND_AUTH (22242) events — returns AuditError::AuthEventForbidden immediately. Does NOT log ephemeral events (they never reach the audit pipeline).

buzz-workflow — YAML-as-Code Automation Engine

Parses, validates, and executes channel-scoped workflow definitions. In multi-community mode workflow definitions, runs, approvals, webhook routes, and schedules inherit the host-derived community and evaluate triggers only against events in that community.

Workflow definition structure:

name: "Incident Triage"
trigger:
  on: message_posted
  filter: "str_contains(trigger_text, 'P1')"
steps:
  - id: notify
    action: send_message
    text: "P1 incident detected: {{trigger.text}}"
  - id: page
    if: "str_contains(trigger_text, 'production')"
    action: request_approval
    from: "{{trigger.author}}"
    message: "Page on-call?"

Note: Both TriggerDef and ActionDef use serde internally-tagged enums. Triggers use on: as the tag field; actions use action: as the tag field. Fields are flattened into the parent struct, not nested.

4 trigger types: message_posted, reaction_added, schedule, webhook

7 action types:

Action	Description
`send_message`	Post to the workflow's channel (or override channel)
`send_dm`	Direct message to a user (pubkey hex or `{{trigger.author}}`)
`set_channel_topic`	Update channel topic
`add_reaction`	React to the trigger message
`call_webhook`	HTTP POST to external URL (SSRF-protected, redirects disabled, 1 MiB response cap)
`request_approval`	Suspend execution; fields: `from`, `message`, `timeout` (default 24h)
`delay`	Pause execution (max 300 seconds)

Template variables: {{trigger.text}}, {{trigger.author}}, {{steps.ID.output.FIELD}}. Single-pass resolution (not recursive). Unknown variables left as literal text.

Condition evaluation: evalexpr with HashMapContext. Dot notation converted to underscores (trigger.text → trigger_text). Custom functions registered: str_contains, str_starts_with, str_ends_with, str_len. 100ms timeout prevents adversarial expressions from blocking.

Concurrency: Arc<Semaphore> with 100 permits. try_acquire() — returns CapacityExceeded immediately rather than queuing.

Approval gates: request_approval action returns StepResult::Suspended with a generated UUID token, but the engine does not yet persist the token or resume execution — runs that hit an approval gate are marked as failed (🚧 WF-08). execute_from_step() exists for future resumption support.

Cron scheduler: loop ticks every 60 seconds, evaluates cron expressions with window-based matching, and creates workflow runs for matched triggers. Fully implemented.

Does NOT: recursively resolve templates (single-pass only). Does NOT queue workflow runs when at capacity — returns CapacityExceeded immediately.

Huddle Audio — WebSocket Opus Relay

Real-time voice lives inside buzz-relay (src/audio/), not a separate crate. A WebSocket endpoint (wss://.../huddle/{channel_id}/audio) authenticates each participant with a NIP-42 challenge, checks channel membership, admits them to an in-memory room, and forwards opaque Opus frames between peers. No external SFU.

Frame protocol (v2): 8-byte big-endian header (sequence u16, 48 kHz timestamp u32, level dBov i8, flags u8) followed by an opaque Opus payload. Invalid level_dbov values are clamped rather than dropped — losing a metric beats losing audio.

Room state: an admission guard synchronizes joins against the room's ended flag; soft cap 25 peers (hard cap 255 via u8 peer index). Per-peer audio uses a bounded channel (drop-on-full); the control channel is separate and never drops join/leave.

Lifecycle events: the relay emits Nostr events for participant joined / left and huddle ended; the desktop client emits huddle started and guidelines. When the last peer leaves, the room ends and the channel archives atomically.

Not yet built: recording and per-track publishing (the corresponding kinds are reserved, no producer exists).

buzz-relay — The Server

Axum WebSocket server. Ties all other crates together. The only crate that imports and orchestrates all subsystems.

AppState (Arc-wrapped, shared across all connections — key fields shown, not exhaustive):

pub struct AppState {
    pub db: Db,
    pub audit: Arc<AuditService>,
    pub pubsub: Arc<PubSubManager>,
    pub auth: Arc<AuthService>,
    pub search: Arc<SearchService>,
    pub sub_registry: Arc<SubscriptionRegistry>,
    pub conn_manager: Arc<ConnectionManager>,
    pub workflow_engine: Arc<WorkflowEngine>,
    pub conn_semaphore: Arc<Semaphore>,       // connection limit
    pub handler_semaphore: Arc<Semaphore>,    // 1024 concurrent handlers
    pub relay_keypair: nostr::Keys,           // relay identity
    pub local_event_ids: moka::sync::Cache,   // local-echo dedup
    pub search_index_tx: mpsc::Sender,        // bounded search worker queue
    // + config, redis_pool, membership_cache, media_storage, shutdown state
}

ConnectionState (per-connection):

pub struct ConnectionState {
    pub auth_state: RwLock<AuthState>,
    pub subscriptions: Mutex<HashMap<String, Vec<Filter>>>,
    // + send_tx, cancel token
}
pub enum AuthState { Pending { challenge: String }, Authenticated(AuthContext), Failed }

HTTP endpoints:

Method	Path	Handler
GET	`/`	WebSocket upgrade or NIP-11 relay info
GET	`/info`	NIP-11 relay info
GET	`/.well-known/nostr.json`	NIP-05 identity
GET	`/health`	Health check
GET	`/_liveness`	Liveness probe
GET	`/_readiness`	Readiness probe
POST	`/events`	Submit a signed Nostr event over HTTP (same ingest path as WebSocket `EVENT`)
POST	`/query`	Query Nostr events over HTTP with NIP-01 filters
POST	`/count`	Count Nostr events over HTTP with NIP-45 filters
POST	`/hooks/{id}`	Workflow webhook trigger (secret-authenticated)
PUT	`/media/upload`	Upload media blob (Blossom, 50 MB limit)
GET/HEAD	`/media/{sha256_ext}`	Retrieve/probe media blob
GET	`/git/{owner}/{repo}/info/refs`	Git smart HTTP advertisement
POST	`/git/{owner}/{repo}/git-upload-pack`	Git smart HTTP fetch
POST	`/git/{owner}/{repo}/git-receive-pack`	Git smart HTTP push
POST	`/internal/git/policy`	Internal git hook policy check

Constants:

Constant	Value	Purpose
`MAX_FRAME_BYTES`	65,536	Max WebSocket frame size
`MAX_SUBSCRIPTIONS`	1024	Per-connection subscription limit
`MAX_HISTORICAL_LIMIT`	500	Per-filter historical query cap
`handler_semaphore` capacity	1024	Concurrent EVENT/REQ handlers

Does NOT: implement business logic — delegates to the appropriate crate for every operation.

buzz-acp — Agent Communication Protocol Harness

Standalone binary that bridges Buzz relay events to AI agents via the Agent Communication Protocol (ACP).

Architecture:

Buzz Relay ──WS──→ buzz-acp ──stdio (ACP/JSON-RPC)──→ Agent (goose/codex/claude)

buzz-acp spawns AI agent subprocesses (1–32, default 1), connects to the relay via WebSocket with NIP-42 auth, discovers channels via REST API, and queues @mention events per channel. At most one prompt is in-flight per channel. Queued events are batched into a single prompt sent via session/prompt over ACP.

Key modules:

Module	LOC	Responsibility
`relay.rs`	3,143	WebSocket + REST relay connection, NIP-42 auth
`queue.rs`	2,565	Per-channel event queue, batching, dedup
`main.rs`	2,457	Event loop, pool orchestration, heartbeat
`pool.rs`	2,253	N-agent pool, claim/return lifecycle
`config.rs`	1,903	CLI/env/TOML configuration
`acp.rs`	1,785	ACP client, stdio JSON-RPC, timeouts
`filter.rs`	814	Subscription rules, evalexpr filtering

Key behaviors:

Pool of 1–32 agent subprocesses with claim/return lifecycle.
Per-channel queuing: at most one prompt in-flight per channel; subsequent @mentions queue until the agent responds.
Crash recovery: agent subprocess crashes are detected and the agent is respawned.
Depends on buzz-core (kind constants) and buzz-sdk (relay/REST utilities).

Does NOT: persist state.

buzz-admin — Operator CLI

Subcommands:

Subcommand	Purpose
`add-member`	Add a pubkey to the relay membership list (`--pubkey`, `--role`); accepts npub or hex; publishes kind:13534 roster
`remove-member`	Remove a pubkey from the relay membership list (`--pubkey`, optional `--role` guard); publishes kind:13534 roster
`list-members`	List all relay members
`generate-key`	Generate a new Nostr keypair (for bootstrapping)
`reconcile-channels`	Emit kind:39000/39002 discovery events for channels missing them (idempotent)

The buzz-admin binary is shipped in the relay Docker image (/usr/local/bin/buzz-admin) and is the recommended way to manage relay membership in production. Use ./run.sh add-member, ./run.sh remove-member, and ./run.sh list-members in Docker Compose deployments.

buzz-test-client — Integration Test Harness

BuzzTestClient wraps a WebSocket connection with a VecDeque<RelayMessage> buffer for message interleaving. Methods: connect, connect_unauthenticated, authenticate, send_event, send_text_message, subscribe, close_subscription, recv_event, collect_until_eose, disconnect.

Test coverage:

File	Tests	Scope
`tests/e2e_relay.rs`	27	WebSocket protocol (auth, subscriptions, filters, limits, NIP-11)
`tests/e2e_media.rs`	7	Media upload/download (Blossom)
`tests/e2e_media_extended.rs`	18	Extended media scenarios
`tests/e2e_nostr_interop.rs`	15	Nostr interoperability: NIP-50 search, NIP-10 threads, NIP-17 gift wraps, DM discovery

All e2e tests are #[ignore] — require a running relay. Total: 134 e2e tests.

src/main.rs is a manual testing CLI (buzz-test-cli) with --send, --subscribe, --channel, --url, --kind flags.

Defines parse_relay_message, OkResponse, RelayMessage directly in src/lib.rs.

7. Security Model

Every security-sensitive operation uses an explicit, verified pattern. No implicit trust.

Authentication

Concern	Mechanism
NIP-42 timestamp	±60 second tolerance — prevents replay attacks
AUTH events	Never stored in Postgres, never logged in audit chain
NIP-98 HTTP Auth	Schnorr-signed `kind:27235` events — URL and method verification

Input Validation

Concern	Mechanism
Schnorr signatures	`verify_event()` in `buzz-core` — every event verified before storage
Event ID	SHA-256 of canonical serialization verified independently of signature
Frame size	`MAX_FRAME_BYTES = 65,536` — oversized frames rejected, connection closed
Search event IDs	64-char hex validation before URL construction — prevents path injection
Workflow step IDs	Alphanumeric + underscore only — prevents evalexpr variable injection
Partition names	Allowlist of table names + strict suffix/date validators — prevents DDL injection

SSRF Protection

is_private_ip() in buzz-core covers:

IPv4: unspecified (0.0.0.0/8), loopback (127.0.0.0/8), private (10/8, 172.16/12, 192.168/16), link-local (169.254/16), CGNAT (100.64/10), benchmarking (198.18/15), broadcast (255.255.255.255)
IPv6: loopback (::1), ULA (fc00::/7), link-local (fe80::/10), multicast (ff00::/8), documentation (2001:db8::/32)
IPv4-mapped IPv6 (::ffff:0:0/96) — recursively checks the embedded IPv4 address

Applied in: buzz-workflow (CallWebhook action), buzz-core (shared utility).

Audit Integrity

Hash chain: each entry's SHA-256 covers all fields including prev_hash — tampering any entry breaks all subsequent hashes
Canonical JSON: BTreeMap for deterministic key ordering — hash is reproducible
Single-writer lock: pg_advisory_lock — prevents concurrent writes from breaking the chain
Panic-safe: catch_unwind ensures lock release even on panic

Access Control

Channel membership is the only gate — enforced by the relay at every operation
REQ handler checks access before subscription registration — no race window for private channel leaks
TOCTOU-safe membership operations: all check-then-modify sequences run inside Postgres transactions
Approval tokens: UUID (CSPRNG), stored as SHA-256 hash, single-use enforced with AND status = 'pending' in UPDATE

Webhook Security

Workflow webhooks: constant-time XOR comparison of stored UUID secret (not HMAC — compares the secret directly, not a body MAC)
Outbound webhooks (CallWebhook): SSRF protection + redirects disabled + 1 MiB response cap

8. Infrastructure

Docker Compose provides the full local development stack. All services include health checks and resource limits.

Services

Service	Image	Port	Purpose
Postgres	`postgres:17-alpine`	5432	Primary event store — events, channels, tokens, workflows, audit; full-text search (`search_tsv` GIN)
Redis	`redis:7-alpine`	6379	Pub/sub fan-out, presence (SET EX), typing (sorted sets)
Adminer	`adminer`	8082	DB web UI (dev only)
MinIO	`minio/minio`	9000 (API), 9001 (console)	S3-compatible object storage (media)
Prometheus	`prom/prometheus`	9090	Metrics collection

Postgres Schema (key tables)

Table	Purpose
`events`	All stored Nostr events; monthly range-partitioned by `PARTITION BY RANGE` on `created_at`; multi-community mode keys every tenant-visible event by `community_id`
`channels`	Channel records (type, visibility, canvas, topic); `community_id` is immutable after creation in multi-community mode
`channel_members`	Membership with roles; soft-delete via `removed_at`
`workflows`	Workflow definitions (YAML stored as canonical JSON); scoped by community in multi-community mode
`workflow_runs`	Execution records with trigger context and trace
`workflow_approvals`	Approval gates (token stored as SHA-256 hash)
`audit_log`	Hash-chain audit entries; per-community chain/head in multi-community mode
`delivery_log`	Delivery tracking (partitioned; Rust module pending)

Redis Key Patterns

Pattern	Type	TTL	Purpose
`buzz:channel:{uuid}`	Pub/Sub channel	—	Event fan-out (single-community form; shared multi-community Redis must use `buzz:{community}:channel:{uuid}` or equivalent)
`buzz:presence:{pubkey_hex}`	String	90s	Online/away status (single-community form; shared multi-community Redis must scope by community)
`buzz:typing:{channel_uuid}`	Sorted Set	60s	Active typers (5s window; shared multi-community Redis must scope by community)

Full-Text Search (Postgres FTS)

Search runs over the events.search_tsv generated tsvector column on the events table (no separate collection or service). The column is populated on insert — to_tsvector('simple', content) — and excludes privacy-sensitive kinds via CASE WHEN kind IN (1059, 30300, 30622) THEN NULL, so those rows are storage-level unsearchable (a NULL tsvector never matches @@). A GIN index (idx_events_search_tsv) backs the @@ probe; in multi-community mode the community-leading btree filters BitmapAnd with the GIN probe so every query is fenced to its community_id.

9. Known Limitations

These are verified gaps in the current implementation — not design aspirations.

#	Limitation	Detail
1	No sqlx offline query cache	Uses `sqlx::query()` (runtime) not `sqlx::query!()` (compile-time). No `.sqlx/` directory. Queries are not validated at compile time.
2	No rate limiting implementation	`RateLimiter` trait exists in `buzz-auth`. Only implementation is `AlwaysAllowRateLimiter` (test stub, gated behind `#[cfg(any(test, feature = "test-utils"))]`). `RateLimitConfig` defines 4 tiers (human, agent-standard, agent-elevated, agent-platform) but none are enforced.
3	No dedicated typing REST endpoint	Typing indicators (kind 20002) are delivered via both local fan-out and Redis pub/sub (cross-node). There is no REST endpoint to query current typers — `/api/presence` returns online/away status only, not typing state.
4	Huddle recording/tracks not built	Voice, room lifecycle, and join/leave/end events are wired (see Huddle Audio above). Recording and per-track publishing have reserved kinds but no producer yet.
5	Approval gates not wired end-to-end	The executor returns `StepResult::Suspended` and the relay has grant/deny API endpoints with DB CRUD, but the engine intercepts before creating `WaitingApproval` rows — runs that hit an approval gate are marked as Failed (🚧 WF-08).
6	Workflow actions partially stubbed	The `send_dm` and `set_channel_topic` workflow actions are in the schema but return `NotImplemented` — a run that reaches one fails at execution (🚧 WF-07).

Uh oh!

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History

ARCHITECTURE.md

File metadata and controls

Buzz Architecture

1. Executive Summary

System Architecture

Crate Dependency Hierarchy

2. The Protocol

Kind Ranges

Buzz Custom Kinds (selected)

Wire Protocol (NIP-01 messages)

3. Connection Lifecycle

Step 0: Community Binding

Step 1: Semaphore Acquire

Step 2: NIP-42 Challenge

Step 3: Authentication

Step 4: Active Loops

Step 5: Cleanup

4. Event Pipeline

Ephemeral Sub-Pipeline (kinds 20000–29999)

Handler Semaphore

5. Subscription System

SubscriptionRegistry

Three-Tier Fan-Out

NIP-01 Edge Cases

REQ Handler Access Control

Historical Query (EOSE)

6. Crate Reference

buzz-core — Shared Types and Verification

buzz-auth — Authentication and Authorization

buzz-db — Postgres Event Store

buzz-pubsub — Redis Pub/Sub, Presence, Typing

buzz-search — Postgres FTS Integration

buzz-audit — Hash-Chain Audit Log

buzz-workflow — YAML-as-Code Automation Engine

Huddle Audio — WebSocket Opus Relay

buzz-relay — The Server

buzz-acp — Agent Communication Protocol Harness

buzz-admin — Operator CLI

buzz-test-client — Integration Test Harness

7. Security Model

Authentication

Input Validation

SSRF Protection

Audit Integrity

Access Control

Webhook Security

8. Infrastructure

Services

Postgres Schema (key tables)

Redis Key Patterns

Full-Text Search (Postgres FTS)

9. Known Limitations