ARCHITECTURE.md drift: rate-limiting claim inverted, stale limits and pipeline description
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
Audited ARCHITECTURE.md against the code at `ac4fa13` (main). Several load-bearing claims have drifted; the first one is security-relevant for operators.
## 1. Rate limiting — doc states the opposite of the code
Doc (§ buzz-auth "Does NOT", and Known Limitations #2) says no rate limiter is implemented or enforced. The code has a Redis-backed limiter, wired and enforced:
- `crates/buzz-pubsub/src/rate_limiter.rs` — `RedisRateLimiter`
- `crates/buzz-relay/src/state.rs:584,713` — wired as `admission_rate_limiter`
- `crates/buzz-relay/src/connection.rs:615,638` — enforced on WS connect + per-message
- `crates/buzz-relay/src/api/bridge.rs:30` — enforced on the HTTP bridge
An operator reading the doc's gap table would assume the relay is unprotected.
## 2. Client-facing limits are stale
- Max frame: doc says 65,536; code default is `DEFAULT_MAX_FRAME_BYTES = 512 * 1024` (`crates/buzz-relay/src/config.rs:14`, env-overridable). `nip11.rs:226` still advertises `max_content_len: 65536` (separate value — worth clarifying which is which).
- Historical query cap: doc says 500; code is `DEFAULT_MAX_PAGE_LIMIT = 1_000` (`crates/buzz-db/src/event.rs:25`), advertised as NIP-11 `max_limit`.
## 3. Event pipeline step 10 / search description stale
- The `search_index_tx` bounded worker queue described in the pipeline no longer exists — FTS is a generated `search_tsv` column populated by the insert itself (comment at `crates/buzz-relay/src/handlers/event.rs:502-506`).
- The privacy exclusion list is no longer `(1059, 30300, 30622)`: `migrations/0001` had 5 kinds, and `migrations/0008_fresh_install_search_allowlist.sql:15-21` flips fresh installs to a positive allowlist `kind IN (0, 9, 40002, 45001, 45003)`.
- Pipeline ordering note: redis/fan-out/workflow now run in a spawned task (`event.rs:342-390`).
## 4. Stale counts (least load-bearing — consider dropping exact numbers)
- `ALL_KINDS`: doc says "127 kinds" in §2 and "80 entries" in §6; actual count is 129 (`crates/buzz-core/src/kind.rs:622`).
- buzz-acp LOC table is ~2× off across the board (e.g. relay.rs 6246 vs doc 3143; main.rs is now a 3-line shim, logic in lib.rs).
- e2e test table: rows say 27/7/18/15 with total 134, but the rows sum to 67; current per-file counts are 43/7/21/25, with 242 test fns across 18 files.
## Verified accurate (no action)
Zero-I/O buzz-core, channel fan-out security boundary (global subs excluded), audit hash-chain design, huddle caps (25 soft / 255 hard / 8-byte header), NIP-42 ±60s, workflow approval-gate and send_dm/set_channel_topic gaps.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Contributor guide
Research direction
Start with ARCHITECTURE.md and compare each affected section against the referenced Rust files, migrations, and test-count details. Update the rate-limiting, limits, pipeline, search, and count descriptions while preserving the items marked accurate; done means the documented claims match the code at the referenced main revision.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 58/100