docs: ARCHITECTURE.md accuracy pass — verified against every line of code#236
Merged
Conversation
…code Major corrections (main was stale — still referenced MySQL, wrong LOC counts): - LOC: 22.7K → 72K across 13 → 17 crates (verified via wc -l) - Postgres everywhere: ON CONFLICT DO NOTHING, pg_advisory_lock, PARTITION BY RANGE, INNER JOIN event_mentions (all MySQL-isms removed) - handler_semaphore: 64 → 1024, MAX_SUBSCRIPTIONS: 100 → 1024 - Cron scheduler: was 'TODO' → fully implemented (window-based matching) - Local-echo dedup: was 'TODO' → implemented via AppState.local_event_ids - Feed mentions: was 'full table scan' → normalized event_mentions table - MCP: kind 40 → 9007 (NIP-29), e tag → h tag, 43 registered tools - ALL_KINDS: 74 → 80 entries (KIND_AUTH excluded) - 148 e2e tests across 8 files (was 42 across 4) New content: - sprout-acp section (14,920 LOC — largest crate, was missing entirely) - sprout-sdk, sprout-media, sprout-cli added to crate hierarchy - REST API table expanded: 15 → 40 endpoints (verified against router.rs) - MinIO and Prometheus added to infrastructure - Approval gates limitation clarified (executor + API exist, engine not wired) - send_dm/set_channel_topic workflow actions noted as stubbed Crossfire reviewed: 3 rounds × (opus + codex CLI). All numbers verified against live codebase. Appendix sums to exactly 72,126.
- Slow client handling: not immediate cancel — 3-strike grace limit - Search indexing: bounded worker queue (capacity 1000), not spawned per event - Ephemeral pipeline: non-presence events now have local fan-out + dedup - Workflow webhooks: constant-time XOR secret comparison, not HMAC-SHA256 - Typing indicators: local fan-out now works — limitation updated - Workflow trigger exclusions: relay-signed + GIFT_WRAP also excluded - SSRF: added 0.0.0.0/8, 255.255.255.255, 2001:db8::/32 to blocked list
…x round 5 - Auth paths: Okta JWT uses auth_token tag (not auth), API token path intercepted by relay handler (not verify_auth_event), dev mode grants Scope::all_known() (not just MessagesRead+MessagesWrite) - AppState: expanded to show Arc wrappers, relay_keypair, local_event_ids, search_index_tx; marked as 'key fields, not exhaustive' - Typesense diagram: 'spawned per event' → 'bounded worker queue' - is_private_ip summary: added unspecified/broadcast/documentation ranges
…round 6 - Proxy kind translation: document actual accepted kinds (1,7,41,42 inbound; stream/edit/reaction/deletion outbound) vs full KindTranslator mappings - Separate API token hashing (caller pre-hashes) from approval token hashing (create_approval hashes internally) - Huddle: clarify session types are data structures only, no active registry
The engine marks approval-gated runs as Failed before creating WaitingApproval rows, so the grant/deny endpoints are wired but currently unreachable from normal execution (WF-08).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
ARCHITECTURE.md was severely stale — still referenced MySQL constructs, had LOC counts from months ago (22.7K vs actual 72K), and was missing the largest crate entirely. Every claim needed verification against the live codebase.
What changed
1 file · +198 / −109 · 859 → 948 lines · 5 commits
Major corrections
INSERT IGNORE,GET_LOCK,JSON_CONTAINS,TO_DAYS)ON CONFLICT DO NOTHING,pg_advisory_lock,INNER JOIN event_mentions,PARTITION BY RANGE)AppState.local_event_ids)JSON_CONTAINS)INNER JOIN event_mentions)create_channelset_canvasetaghtagauthtag; dev mode grants[MessagesRead, MessagesWrite]auth_tokentag; dev mode grantsScope::all_known(); API tokens intercepted by relay handlerSLOW_CLIENT_GRACE_LIMIT)search_index_tx, capacity 1000)New content
router.rs); approval endpoints annotated as unreachable (🚧 WF-08)sprout-acp,sprout-sdk,sprout-media,sprout-cliArcwrappers,relay_keypair,local_event_ids,search_index_tx; marked "not exhaustive"0.0.0.0/8,255.255.255.255,2001:db8::/32create_approvalhashes internally)KindTranslatormappings from actual proxy event flowVerification methodology
Every numerical claim was verified against the live codebase:
find crates/<name> -name '*.rs' | xargs wc -lhandler_semaphore,MAX_SUBSCRIPTIONS,KIND_count,#[tool(count)router.rsReview process
7 rounds of crossfire review (Claude Opus subagents + OpenAI Codex CLI):
Each round found genuinely new issues in sections previous rounds hadn't deeply verified. All findings addressed. Round 7 verified 13 specific spot-checks (a–m) against source — all passed.
Commits
ARCHITECTURE.md accuracy pass — verified against every line of codefix 7 additional inaccuracies found by deep codex reviewfix auth paths, AppState struct, and Typesense diagram per codex round 5fix proxy kind tables, token hashing, huddle session per codex round 6mark approval endpoints as unreachable per codex round 7What's deferred
sprout-sdk,sprout-media,sprout-cli(added to hierarchy but no detailed sections yet)