Skip to content

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

Description

@MohsinHashmi-DataInn

Observed at commit 63496cc (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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions