docs: ARCHITECTURE.md has drifted from the relay code (search_index_tx, fan-out tiers, rate limiting)
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
- Domain
- backend, documentation
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from block/buzz
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
-
workflow_sink's mention parser never masks code regions — @name inside a code span wakes the agent Open
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 Half a day Newbie friendliness 88/100
-
Difficulty 1/5 Under an hour Newbie friendliness 92/100
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Eynzof/Hermes-CN-Desktop#610 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
gitbutlerapp/gitbutler#15998 · 1 comment ·
-
bug triage:deciding
Difficulty 1/5 Under an hour Newbie friendliness 88/100
open-telemetry/otel-arrow#4132 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100