Skip to content

Commit 2498983

Browse files
npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67dTyler Longwell
andcommitted
docs(multi-tenant): add conformance table and community semantics to root docs
Add docs/multi-tenant-conformance.md mapping each relay-global surface (membership, NIP-98 replay, Typesense scoping, Redis keys, workflows, NIP-11, git/NIP-34 seams) to its source behavior and the model's treatment, anchored on the frozen host-binding contract. Update README/NOSTR/ARCHITECTURE/VISION_AGENT/VISION_PROJECTS to describe community as the tenant boundary while preserving all N=1 client wire/API behavior promises (community adds nothing observable at N=1). Co-authored-by: Tyler Longwell <[email protected]> Signed-off-by: Tyler Longwell <[email protected]>
1 parent c6f6fef commit 2498983

6 files changed

Lines changed: 150 additions & 27 deletions

File tree

‎ARCHITECTURE.md‎

Lines changed: 31 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,14 @@ Buzz is a self-hosted team communication platform built on the Nostr protocol (N
66

77
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.
88

9+
A Buzz **community** is the tenant-visible workspace selected by the request host.
10+
The self-hosted default remains one host, one relay process, one implicit
11+
community. Multi-community deployments move that semantic boundary one level up:
12+
`req.community = resolve_host(connection.host)` is established before AUTH,
13+
EVENT, REQ, REST, media, git, search, workflow, or pub/sub handling. Unknown
14+
hosts fail closed, and NIP-98/API-token stamps must agree with the host-derived
15+
community rather than overriding it.
16+
917
Buzz is a Rust monorepo, licensed Apache 2.0 under Block, Inc.
1018

1119
---
@@ -87,7 +95,7 @@ buzz-admin (operator CLI: relay membership + key generation)
8795
buzz-test-client (integration test harness + manual CLI)
8896
```
8997

90-
**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. `buzz-proxy` connects to the relay as a WebSocket client and translates NIP-28 events between standard Nostr clients and the Buzz relay.
98+
**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. `buzz-proxy` connects to the relay as a WebSocket client and translates NIP-28 events between standard Nostr clients and the Buzz 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.
9199

92100
---
93101

@@ -159,6 +167,16 @@ Max frame size: 65,536 bytes. Max subscriptions per connection: 1024. Max histor
159167

160168
Every WebSocket connection follows this exact sequence:
161169

170+
### Step 0: Community Binding
171+
172+
The server resolves `TenantContext` from the request host before any handler can
173+
observe tenant data. The URL/domain is authoritative for the community, matching
174+
today's "the relay URL is the workspace" behavior. In single-community mode the
175+
configured host maps to the default community. In multi-community mode, an
176+
unknown or unmapped host rejects generically and never falls through to a default
177+
tenant. Client-supplied `#h` tags are still channel identifiers; they must resolve
178+
to a channel inside the host-derived community.
179+
162180
### Step 1: Semaphore Acquire
163181

164182
`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.
@@ -414,7 +432,7 @@ All database access. Uses `sqlx::query()` (runtime, not compile-time macros) —
414432

415433
### buzz-pubsub — Redis Pub/Sub, Presence, Typing
416434

417-
Manages Redis pub/sub fan-out, presence tracking, and typing indicators.
435+
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.
418436

419437
**Architecture:**
420438

@@ -446,7 +464,7 @@ EXPIRE buzz:typing:{channel_id} 60
446464

447465
### buzz-search — Typesense Integration
448466

449-
Full-text search via Typesense. All HTTP calls use `reqwest` with `X-TYPESENSE-API-KEY`.
467+
Full-text search via Typesense. All HTTP calls use `reqwest` with `X-TYPESENSE-API-KEY`. In multi-community mode, indexed documents and every query filter include `community_id`; the shared Typesense collection is infrastructure, not a cross-community result space.
450468

451469
**Collection schema (7 fields):** `id`, `content`, `kind` (int32), `pubkey` (facet), `channel_id` (facet, optional), `created_at` (int64, default sort), `tags_flat` (string[]).
452470

@@ -466,7 +484,7 @@ Full-text search via Typesense. All HTTP calls use `reqwest` with `X-TYPESENSE-A
466484

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

469-
**Hash chain:** each entry stores `prev_hash` (hash of the previous entry). `verify_chain()` walks entries and recomputes hashes to detect tampering. Genesis entry uses `GENESIS_HASH` (64 zeros).
487+
**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).
470488

471489
**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.
472490

@@ -480,7 +498,7 @@ Tamper-evident append-only log with SHA-256 hash chaining.
480498

481499
### buzz-workflow — YAML-as-Code Automation Engine
482500

483-
Parses, validates, and executes channel-scoped workflow definitions.
501+
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.
484502

485503
**Workflow definition structure:**
486504
```yaml
@@ -824,26 +842,26 @@ Docker Compose provides the full local development stack. All services include h
824842
825843
| Table | Purpose |
826844
|-------|---------|
827-
| `events` | All stored Nostr events; monthly range-partitioned by `PARTITION BY RANGE` on `created_at` |
828-
| `channels` | Channel records (type, visibility, canvas, topic) |
845+
| `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` |
846+
| `channels` | Channel records (type, visibility, canvas, topic); `community_id` is immutable after creation in multi-community mode |
829847
| `channel_members` | Membership with roles; soft-delete via `removed_at` |
830-
| `workflows` | Workflow definitions (YAML stored as canonical JSON) |
848+
| `workflows` | Workflow definitions (YAML stored as canonical JSON); scoped by community in multi-community mode |
831849
| `workflow_runs` | Execution records with trigger context and trace |
832850
| `workflow_approvals` | Approval gates (token stored as SHA-256 hash) |
833-
| `audit_log` | Hash-chain audit entries |
851+
| `audit_log` | Hash-chain audit entries; per-community chain/head in multi-community mode |
834852
| `delivery_log` | Delivery tracking (partitioned; Rust module pending) |
835853
836854
### Redis Key Patterns
837855
838856
| Pattern | Type | TTL | Purpose |
839857
|---------|------|-----|---------|
840-
| `buzz:channel:{uuid}` | Pub/Sub channel | — | Event fan-out |
841-
| `buzz:presence:{pubkey_hex}` | String | 90s | Online/away status |
842-
| `buzz:typing:{channel_uuid}` | Sorted Set | 60s | Active typers (5s window) |
858+
| `buzz:channel:{uuid}` | Pub/Sub channel | — | Event fan-out (single-community form; shared multi-community Redis must use `buzz:{community}:channel:{uuid}` or equivalent) |
859+
| `buzz:presence:{pubkey_hex}` | String | 90s | Online/away status (single-community form; shared multi-community Redis must scope by community) |
860+
| `buzz:typing:{channel_uuid}` | Sorted Set | 60s | Active typers (5s window; shared multi-community Redis must scope by community) |
843861
844862
### Typesense Collection
845863
846-
Single collection (`events` by default, configurable via `TYPESENSE_COLLECTION`). Schema: `id`, `content`, `kind` (int32), `pubkey` (facet), `channel_id` (facet, optional), `created_at` (int64, default sort), `tags_flat` (string[]).
864+
Single collection (`events` by default, configurable via `TYPESENSE_COLLECTION`). Schema today: `id`, `content`, `kind` (int32), `pubkey` (facet), `channel_id` (facet, optional), `created_at` (int64, default sort), `tags_flat` (string[]). Multi-community mode adds faceted `community_id` and either prefixes document IDs with community or makes all upsert/delete/refetch paths carry community context.
847865
848866
---
849867

‎NOSTR.md‎

Lines changed: 24 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,23 @@ clients and don't have company credentials.
1414

1515
Both paths require NIP-42 authentication.
1616

17+
## Community scope
18+
19+
Buzz treats the relay URL/domain as authoritative for the community. Today's
20+
single-relay deployment has exactly one community behind that URL, so existing
21+
NIP-29/NIP-28 clients keep using the same WebSocket URL, event kinds, tags, and
22+
REST/media/git paths. In a multi-community deployment, each community is reached
23+
by its own domain or subdomain; the backend resolves the community from the host
24+
before handling AUTH, EVENT, REQ, REST, media, git, search, or workflow traffic.
25+
26+
The Nostr wire format does not grow a tenant tag. Client-supplied `#h` tags still
27+
name channels/groups and are checked against the host-derived community. Events
28+
without `#h` — profiles, gift-wrapped DMs, membership notifications, lists,
29+
status, long-form notes, workflow/system events, and other "global" streams — are
30+
global only inside the connected community. A pubkey can join multiple
31+
communities and repost its profile in each one; DMs and profiles do not inherit
32+
across community domains.
33+
1734
---
1835

1936
## Path 1: NIP-29 Direct
@@ -55,15 +72,15 @@ PGPASSWORD=buzz_dev psql -h localhost -U buzz -d buzz -c \
5572
| **Group metadata (kind:39000)** | ✅ | Relay-signed; always `d`, `name`, `closed` tags; `about` only if description non-empty; `private` if applicable; `hidden` for DM channels |
5673
| **Group admins (kind:39001)** | ✅ | Relay-signed; `d` tag + `p` tags with roles (`owner`, `admin`) |
5774
| **Group members (kind:39002)** | ✅ | Relay-signed; `d` tag + `p` tags for all members |
58-
| **Membership notifications** | ✅ | kind:44100 (added) / kind:44101 (removed); relay-signed, global scope |
59-
| **Presence (kind:20001)** | ✅ | Ephemeral; arbitrary status string (truncated to 128 chars); writes to Redis (`set_presence`/`clear_presence` on `"offline"`), then fan-out to local subscribers |
75+
| **Membership notifications** | ✅ | kind:44100 (added) / kind:44101 (removed); relay-signed, community-global scope (`channel_id=None` inside the connected community) |
76+
| **Presence (kind:20001)** | ✅ | Ephemeral; arbitrary status string (truncated to 128 chars); writes to Redis (`set_presence`/`clear_presence` on `"offline"`), then fan-out to local subscribers. In multi-community mode presence is scoped to the connected community. |
6077
| **Typing indicators (kind:20002)** | ✅ | Ephemeral, not stored; published via Redis pub/sub (multi-node capable unlike presence fan-out) |
6178
| **NIP-42 authentication** | ✅ | Proactive challenge; optional pubkey allowlist |
6279
| **NIP-11 relay info** | ✅ | `GET /` with `Accept: application/nostr+json` |
6380
| **Blossom media** | ✅ | `PUT /media/upload` (BUD-02), `GET /media/{sha256}.{ext}` (BUD-01) |
6481
| **NIP-50 search** | ✅ | One-shot search REQs: `{"search":"query","kinds":[9],"#h":["<uuid>"]}` → relevance-sorted results → EOSE. Not registered as persistent subscriptions. |
6582
| **NIP-10 threads** | ✅ | WS-submitted replies with `["e","<root>","","reply"]` tags create `thread_metadata` atomically. Visible in REST thread queries. Unknown parents rejected. |
66-
| **NIP-17 DMs (gift wrap)** | ✅ | kind:1059 accepted with ephemeral signing keys. Stored globally (channel_id=None). Delivered via `#p`-filtered subscriptions. Not indexed in search. |
83+
| **NIP-17 DMs (gift wrap)** | ✅ | kind:1059 accepted with ephemeral signing keys. Stored community-globally (`channel_id=None` inside the connected community). Delivered via `#p`-filtered subscriptions. Not indexed in search. |
6784
| **DM discovery** | ✅ | DM creation emits kind:39000 (with `hidden` tag) + kind:44100 membership notifications. NIP-29 clients discover DMs via standard group discovery flow. |
6885
| **Join request (kind:9021)** | ✅ | Open channels only. Adds member, emits system message + group discovery events + kind:44100 membership notification. Private channels rejected at ingest. |
6986
| **Edits (kind:40003)** | ⚠️ | Works on the wire but Buzz-only — no standard NIP-29 client renders these |
@@ -126,10 +143,10 @@ The relay emits relay-signed notifications when members are added or removed:
126143

127144
| Kind | Meaning | Tags | Scope |
128145
|------|---------|------|-------|
129-
| **44100** | Member added | `p` = target pubkey, `h` = channel UUID | Global |
130-
| **44101** | Member removed | `p` = target pubkey, `h` = channel UUID | Global |
146+
| **44100** | Member added | `p` = target pubkey, `h` = channel UUID | Community-global |
147+
| **44101** | Member removed | `p` = target pubkey, `h` = channel UUID | Community-global |
131148

132-
Stored globally (`channel_id = None`) so agents and clients can subscribe without knowing channel
149+
Stored community-globally (`channel_id = None` inside the connected community) so agents and clients can subscribe without knowing channel
133150
UUIDs in advance. Client-submitted kind:44100/44101 events are rejected — only the relay keypair
134151
may sign these.
135152

@@ -474,7 +491,7 @@ is dual-sourced: local snapshot metadata plus upstream edit events (kind:40003
474491
## Relay Membership (NIP-43)
475492

476493
When `BUZZ_REQUIRE_RELAY_MEMBERSHIP=true`, every authenticated connection is checked against the
477-
`relay_members` table. Only pubkeys with a row in that table may use the relay. The relay owner
494+
`relay_members` table. In today's single-community deployment this is the relay-wide member list; in multi-community mode the same rule is scoped to the host-derived community. Only pubkeys with a row for that community may use that community. The relay owner
478495
is bootstrapped automatically from `RELAY_OWNER_PUBKEY` on startup.
479496

480497
### CLI: Managing Members

‎README.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,12 @@
2727

2828
Buzz is a self-hostable workspace where humans and AI agents share the same rooms.
2929

30+
A Buzz **community** is the workspace a user reaches by URL. In the single-relay
31+
setup that ships today, the relay URL selects exactly one community. A hosted
32+
operator can serve many communities behind many domains or subdomains, but the
33+
client-facing rule stays the same: the URL is authoritative for the workspace,
34+
and all tenant-observable state under that URL is community-local.
35+
3036
It's a Nostr relay: every message, reaction, workflow step, review approval, and git event is a signed event in one log. Same shape, same identity model, same audit trail, whether the author is a person or a process.
3137

3238
In practice it feels like a team workspace. Under the hood it's an event log with taste and a suspicious number of Rust crates.
@@ -70,9 +76,9 @@ Yes, it's another AI-adjacent developer tool. We're sorry. The difference is wha
7076

7177
## Why Buzz is better
7278

73-
One relay. One identity model. One event log. Humans, agents, workflows, and repos all speak the same protocol, sign with the same kind of key, and end up in the same search index.
79+
One community. One identity model. One event log. Humans, agents, workflows, and repos all speak the same protocol, sign with the same kind of key, and end up in the same search index. In the default self-hosted deployment, one relay hosts one community; in a hosted multi-tenant deployment, each community keeps that same semantic boundary even when the backend shares Postgres, Redis, Typesense, and object storage.
7480

75-
The bet is that one relay can do what teams currently fake with chat, forges, bots, CI dashboards, release tools, search indexes, and a pile of glue code. Not all at once, not magically, but with one substrate instead of seven tabs pretending they know about each other.
81+
The bet is that one community can do what teams currently fake with chat, forges, bots, CI dashboards, release tools, search indexes, and a pile of glue code. Not all at once, not magically, but with one substrate instead of seven tabs pretending they know about each other.
7682

7783
Agents are part of the room, not haunted cron jobs.
7884

@@ -162,7 +168,7 @@ A Rust workspace of focused crates. Single source of truth: the relay. See [ARCH
162168

163169
**Core protocol** — `buzz-core` (zero-I/O types, NIP-01 filters, Schnorr verify) · `buzz-relay` (Axum WS + REST)
164170

165-
**Services** — `buzz-db` (Postgres) · `buzz-auth` (NIP-42/98 Schnorr auth, rate limiting) · `buzz-pubsub` (Redis, presence, typing) · `buzz-search` (Typesense) · `buzz-audit` (hash-chain log)
171+
**Services** — `buzz-db` (Postgres) · `buzz-auth` (NIP-42/98 Schnorr auth, rate limiting) · `buzz-pubsub` (Redis, presence, typing) · `buzz-search` (Typesense) · `buzz-audit` (hash-chain log). Multi-community mode scopes tenant-observable rows, cache keys, search documents, workflow state, media metadata, git repo pointers, and audit chains by the host-derived community; shared infrastructure is an implementation detail, not a user-visible global workspace.
166172

167173
**Agent surface** — `buzz-cli` (agent-first CLI, JSON in / JSON out) · `buzz-acp` (ACP harness for Goose/Codex/Claude Code) · `buzz-agent` (ACP agent — see [VISION_AGENT.md](VISION_AGENT.md)) · `buzz-dev-mcp` (shell + file-edit tools) · `buzz-workflow` (YAML automation) · `buzz-persona` (agent persona packs)
168174

‎VISION_AGENT.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,13 @@ Two binaries, two protocols, no coupling between them.
1616

1717
Together: two crates of Rust purpose-built for headless autonomous coding work.
1818

19+
When agents run behind Buzz, the relay URL they connect to selects their
20+
community. A hosted operator may run many communities on shared infrastructure,
21+
but an agent's profile, presence, DMs, memories, jobs, channel memberships, and
22+
audit trail are still scoped to the community behind that URL. The same npub can
23+
join another community and repost a profile there, but no agent state is
24+
inherited across hosts.
25+
1926
## Why We Built Our Own
2027

2128
**Auditability.** A senior engineer can read both binaries in a sitting. There are no abstractions reserved for future flexibility. When the agent does something unexpected, the path from symptom to cause is short.
@@ -57,6 +64,7 @@ Two pipes. Two protocols. Each session gets its own MCP server instances — ful
5764

5865
- Multiple concurrent sessions in one process — each with independent MCP servers, history, and context (configurable cap, default 8)
5966
- Ten agents in parallel behind Buzz, each with their own MCP configuration
67+
- The same agent key can participate in multiple Buzz communities while keeping membership, jobs, DMs, profile, and presence community-local
6068
- Any ACP client gets a coding agent without a custom adapter
6169
- Any MCP server gets a capable caller without a custom adapter
6270
- A codebase small enough to fork, modify, and understand in a day — two crates, no coupling between them

0 commit comments

Comments
 (0)