BigBrotr

Distributed relay observatory for Nostr. Discovery, monitoring, archiving, analytics, and data access across clearnet, Tor, I2P, and Lokinet.

Docs Blog

Five Pillars

Discovery

Find relays across clearnet, Tor, I2P, and Lokinet. Seed from known sources, discover from events and APIs, validate with WebSocket handshakes.

Monitoring

Seven health checks per relay: NIP-11 info, RTT latency, SSL certificates, DNS records, geolocation, network/ASN, and HTTP headers. Results published as NIP-66 events.

Archiving

Cursor-based event synchronization from validated relays. Content-addressed metadata deduplication via SHA-256 hashing.

Analytics

11 PostgreSQL materialized views pre-computing aggregate statistics: event distribution by kind, per-relay stats, author counts, NIP adoption, software distribution, and daily time series.

Data Access

Two parallel interfaces exposing the same data: a REST API for HTTP clients and a NIP-90 Data Vending Machine for native Nostr queries over WebSocket.

Services

Seeder One-shot bootstrap from seed files and known relay lists.

Finder Discover relay URLs from NIP-65 events and public APIs.

Validator WebSocket handshake test, promotes candidates to relays.

Monitor NIP-11 and NIP-66 health checks with event publishing.

Refresher Orchestrates materialized view refresh on schedule.

Synchronizer Cursor-based event collection from validated relays.

Api REST API with automatic schema discovery, filtering, sorting, and pagination.

Dvm NIP-90 Data Vending Machine for native Nostr protocol access.

Quick Start

# Clone and start the full stack
git clone https://github.com/BigBrotr/bigbrotr.git
cd bigbrotr/deployments/bigbrotr
docker compose up -d

# Run a single service
python -m bigbrotr seeder --once
python -m bigbrotr finder --log-level DEBUG

Full Quick Start Guide Step-by-step instructions with Docker Compose and configuration.

Explore

Architecture Deep Dive Diamond DAG, package responsibilities, and design principles.

Database Schema Tables, stored functions, and materialized views.

Configuration Guide YAML configs, environment variables, and deployments.

Contributing Development setup, testing, and coding standards.

External

Deck Slide deck presenting BigBrotr's architecture and design.

API Docs Auto-generated Python API reference documentation.