How scsibug/nostr-rs-relay works
Main System Components
• API Layer (WebSocket + Control API)
• WebSocket server accepting client connections
• Control message listener (for admin commands)
• Core Relay Logic
• Connection manager (manages client sessions)
• Subscription manager (tracks active filters and subscribers)
• Event dispatcher (routes incoming events to DB writer and subscribers)
• Persistence Layer
• DB writer pool (event inserts, migrations)
• Client query pool (filter + fetch events)
• Repository implementations (SQLite & PostgreSQL via src/repo/*)
• Configuration & Startup
• config.toml loader
• Build script (build.rs) and schema migrations
• Optional Payment Subsystem
• Lightning Network adapters (src/payment/cln_rest.rs, src/payment/lnbits.rs)
• CLI & Tooling
• bulkloader binary for batch imports
• nostr-rs-relay main binary
• Example client (examples/nauthz)
• External Dependencies
• Nostr clients (e.g., noscl, websocat)
• Reverse proxy (TLS termination, load-balancer)
• Docker container runtime (for deployment)
Relationships & Data Flows
• Client → WebSocket Server:
• Publish events, subscribe with filters
• WebSocket Server → Subscription Manager:
• Register filters, maintain subscriber lists
• WebSocket Server → Event Dispatcher → DB Writer Pool:
• Persist events asynchronously (SQLite/Postgres)
• DB Writer Pool → Repository Layer:
• Execute SQL migrations, insert/select queries
• Event Dispatcher → Subscription Manager → Clients:
• Broadcast matching events
• Control API → Core Logic:
• Administrative commands (e.g., info, close)
• Payment Subsystem ←→ External Lightning Service:
• On-chain/Lightning event fees or authentication (if enabled)
Architectural Patterns & Principles
• Layered Architecture:
• API Layer, Domain Logic, Persistence Layer
• Repository Pattern:
• Abstracted DB implementations under src/repo/
• Connection Pooling:
• Separate pools for writes (min=1, max=4) and client queries (min=4, max=128)
• Asynchronous, Event-Driven:
• Tokio runtime powering WS server, DB tasks, control listener
• Configuration-Driven:
• config.toml drives rate limits, network addresses, DB paths
Additional Details to Capture
• On startup: config loader → schema migration → connection pools
• CLI bulkloader as a separate process invoking the same core library
• Proto definitions (proto/nauthz.proto) if gRPC extensions are used
• Tests folder demonstrates integration points (can be omitted or shown as validation)