docs: ARCHITECTURE.md has drifted from the relay code (search_index_tx, fan-out tiers, rate limiting)
- 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
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