System Architecture
Design scalable, reliable Nostr systems. Learn traditional multi-relay patterns and modern HA cluster architectures like Shugur's distributed relay network.
Overview
Key building blocks and responsibilities across client, API, workers, storage, and relays.
A robust Nostr architecture separates concerns clearly: UI client, API gateway, background processors, observability, and storage. Relays are treated as an eventually-consistent message fabric.
- Clients publish/subscribe via multiple relays for resilience.
- APIs handle auth, rate-limits, input validation, and aggregate data from relays + storage.
- Workers handle enrichment: indexing, moderation, recommendations, archiving.
- Observability collects metrics, traces, logs for performance and reliability.
Resilience Patterns
Design for failure and recovery
- Retry with backoff + jitter: Avoid thundering herds; cap max retries.
- Timeouts everywhere: Socket, publish, subscription bootstrap.
- Circuit breakers: Short-circuit unhealthy relays/services.
- Idempotency: De-duplicate by event id; use deterministic ids for commands.
- Bulkheads: Isolate pools for critical vs. best-effort work.
Reference Architecture
A pragmatic blueprint for most apps
Core Services
- API Gateway (REST/GraphQL) with caching
- Websocket fan-out for live updates
- Background queues for indexing and ML
- Object/DB storage for durable state
Relay Strategy
- Multi-relay read with health-aware selection
- Primary + fallback publish
- Eventual consistency with de-duplication
Data Modeling
Model events, indexes, and derived views
Persist raw events for audit, then project into queryable shapes: timelines, user profiles, relationships.
Use idempotent processors keyed by event id to safely re-run pipelines.
Security & Compliance
Protect keys, validate data, and reduce abuse
Key Handling
Never transmit private keys; use secure storage; sign locally.
Validation
Verify signatures, kinds, tags, and size limits on ingest.
Abuse Controls
Rate limits, CAPTCHAs where needed, allowlists/denylists for relays.
Content Filters
Moderation rules, NSFW flags, and reporting flows.
Deployment & Operations
Regions, CI/CD, rollouts, and backup
Multi-Region Reads
Prefer nearest relays and cache layer; failover on errors.
Blue/Green
Roll out API and workers gradually with health checks.
Backups
Archive raw events to object storage; test restore procedures.
Where to go next
Continue with performance, testing, or relay setup.