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

Nobody has claimed this yet.

Assessment

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

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.

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.

Dominant language
Rust
Stars
33.7k
Forks
4.4k
Avg merge
1d 21h
Merged PRs (30d)
239

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from block/buzz

All issues in block/buzz

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.