You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 2498983
Browse filesBrowse the repository at this point in the historyBrowse files
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]>
Copy file name to clipboardExpand all lines: ARCHITECTURE.md
+31-13Lines changed: 31 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,6 +6,14 @@ Buzz is a self-hosted team communication platform built on the Nostr protocol (N
6
6
7
7
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.
8
8
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
+
9
17
Buzz is a Rust monorepo, licensed Apache 2.0 under Block, Inc.
buzz-test-client (integration test harness + manual CLI)
88
96
```
89
97
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.
91
99
92
100
---
93
101
@@ -159,6 +167,16 @@ Max frame size: 65,536 bytes. Max subscriptions per connection: 1024. Max histor
159
167
160
168
Every WebSocket connection follows this exact sequence:
161
169
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
+
162
180
### Step 1: Semaphore Acquire
163
181
164
182
`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) —
414
432
415
433
### buzz-pubsub — Redis Pub/Sub, Presence, Typing
416
434
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.
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.
@@ -466,7 +484,7 @@ Full-text search via Typesense. All HTTP calls use `reqwest` with `X-TYPESENSE-A
466
484
467
485
Tamper-evident append-only log with SHA-256 hash chaining.
468
486
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).
470
488
471
489
**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.
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.
484
502
485
503
**Workflow definition structure:**
486
504
```yaml
@@ -824,26 +842,26 @@ Docker Compose provides the full local development stack. All services include h
824
842
825
843
| Table | Purpose |
826
844
|-------|---------|
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 |
829
847
| `channel_members` | Membership with roles; soft-delete via `removed_at` |
| `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) |
843
861
844
862
### Typesense Collection
845
863
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.
|**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 |
|**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.|
60
77
|**Typing indicators (kind:20002)**| ✅ | Ephemeral, not stored; published via Redis pub/sub (multi-node capable unlike presence fan-out) |
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
133
150
UUIDs in advance. Client-submitted kind:44100/44101 events are rejected — only the relay keypair
134
151
may sign these.
135
152
@@ -474,7 +491,7 @@ is dual-sourced: local snapshot metadata plus upstream edit events (kind:40003
474
491
## Relay Membership (NIP-43)
475
492
476
493
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
478
495
is bootstrapped automatically from `RELAY_OWNER_PUBKEY` on startup.
Copy file name to clipboardExpand all lines: README.md
+9-3Lines changed: 9 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,6 +27,12 @@
27
27
28
28
Buzz is a self-hostable workspace where humans and AI agents share the same rooms.
29
29
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
+
30
36
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.
31
37
32
38
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
70
76
71
77
## Why Buzz is better
72
78
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.
74
80
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.
76
82
77
83
Agents are part of the room, not haunted cron jobs.
78
84
@@ -162,7 +168,7 @@ A Rust workspace of focused crates. Single source of truth: the relay. See [ARCH
Copy file name to clipboardExpand all lines: VISION_AGENT.md
+8Lines changed: 8 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,6 +16,13 @@ Two binaries, two protocols, no coupling between them.
16
16
17
17
Together: two crates of Rust purpose-built for headless autonomous coding work.
18
18
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
+
19
26
## Why We Built Our Own
20
27
21
28
**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
57
64
58
65
- Multiple concurrent sessions in one process — each with independent MCP servers, history, and context (configurable cap, default 8)
59
66
- 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
60
68
- Any ACP client gets a coding agent without a custom adapter
61
69
- Any MCP server gets a capable caller without a custom adapter
62
70
- A codebase small enough to fork, modify, and understand in a day — two crates, no coupling between them
0 commit comments