block / block/buzz

docs: ARCHITECTURE.md has drifted from the relay code (search_index_tx, fan-out tiers, rate limiting)

Open Beginner friendly
#3,693 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
32.7k
Forks
4.3k
Avg merge
1d 13h
Merged PRs (30d)
253

Description

Observed at commit 63496cc1d4c6f1b7c613801bdcc694169dcf391a (v0.5.2-5-g63496cc1). Three places where ARCHITECTURE.md describes a relay that no longer exists — each contradicted by an explicit statement in the code itself:

**1. `search_index_tx` / separate FTS worker is gone**

ARCHITECTURE.md still lists a `search_index_tx` field, but indexing is now the row insert itself: `events.search_tsv` is a `GENERATED ALWAYS AS (to_tsvector(...)) STORED` column with a GIN index (`crates/buzz-search/src/lib.rs:5-15` — "every row write is the index update — there is no separate indexer, no mpsc queue, no reindex job"). The relay confirms in a comment at `crates/buzz-relay/src/handlers/event.rs:502-506`: "The old Typesense `index_event` worker and its `search_index_tx` mpsc are gone."

**2. "Three-Tier Fan-Out" is now five tiers**

ARCHITECTURE.md (~L294) describes three subscription index tiers; `crates/buzz-relay/src/subscription.rs` (~L50-58) defines five community-keyed maps: `channel_kind_index`, `channel_wildcard_index`, `global_kind_index`, `global_p_kind_index`, `global_wildcard_index`.

**3. "No rate-limiting implementation" is stale**

The known-gaps section (~L816-827) says rate limiting exists only as a trait with a test stub. WS admission rate limiting is now implemented and enforced on the hot path: `enforce_ws_admission` (`crates/buzz-relay/src/connection.rs:594-650`) runs Redis sliding-window checks before dispatch on every EVENT/REQ/COUNT, with four live limiters constructed in `AppState::new` (`crates/buzz-relay/src/state.rs:584-597`) and env-tunable limits (`crates/buzz-relay/src/config.rs:301-314`).

The other gaps listed there (WF-07 NotImplemented actions, WF-08 approval gates — see #3525 — missing huddle recording, no sqlx offline cache) still check out; it's specifically these three claims that have drifted.

Found while building code-derived documentation of the platform (with AI assistance) — the drift actively misled a docs-first pass until we re-verified against source. Happy to send a docs PR updating the three sections if that's welcome.

Contributor guide

Open the contributing guide

Research direction

Start with the three affected sections in ARCHITECTURE.md and verify each claim against the referenced relay, search, subscription, connection, state, and config files. Update the search-index description, fan-out tier count, and rate-limiting gap while leaving the other listed gaps intact. Done means ARCHITECTURE.md matches the cited code at the referenced commit.

Written by the indexing model from the issue text.

Assessment

Tech stack
postgresql, redis, rust
Domain
backend, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
85/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.