Skip to content

BigBrotr

Python 3.11+ PostgreSQL 16 License: MIT Documentation

A modular Nostr relay discovery, monitoring, and event archiving system.

BigBrotr continuously discovers Nostr relays across all network types, validates their connectivity, performs comprehensive health checks, and archives events from the relay network. Built on Python 3.11+ with strict typing, asyncio, and PostgreSQL 16.

How It Works

Six independent async services share a PostgreSQL database, each with a distinct role in the discovery-monitoring-archiving workflow:

flowchart TD
    DB[("PostgreSQL")]

    SE["Seeder<br/><small>Bootstrap</small>"]
    FI["Finder<br/><small>Discovery</small>"]
    VA["Validator<br/><small>Verification</small>"]
    MO["Monitor<br/><small>Health checks</small>"]
    SY["Synchronizer<br/><small>Event collection</small>"]
    RE["Refresher<br/><small>View refresh</small>"]

    SE --> DB
    FI --> DB
    VA --> DB
    MO --> DB
    SY --> DB
    RE --> DB

    style SE fill:#7B1FA2,color:#fff,stroke:#4A148C
    style FI fill:#7B1FA2,color:#fff,stroke:#4A148C
    style VA fill:#7B1FA2,color:#fff,stroke:#4A148C
    style MO fill:#7B1FA2,color:#fff,stroke:#4A148C
    style SY fill:#7B1FA2,color:#fff,stroke:#4A148C
    style RE fill:#7B1FA2,color:#fff,stroke:#4A148C
    style DB fill:#311B92,color:#fff,stroke:#1A237E
Service Role Mode
Seeder Bootstraps initial relay URLs from a seed file One-shot
Finder Discovers new relays from events and external APIs Continuous
Validator Verifies URLs are live Nostr relays via WebSocket Continuous
Monitor Runs NIP-11 + NIP-66 health checks, publishes kind 10166/30166 events Continuous
Synchronizer Collects events from relays using cursor-based pagination Continuous
Refresher Refreshes materialized views for analytics queries Continuous

Key Features

  • Multi-Network Support

    Discover and monitor relays across clearnet, Tor (.onion), I2P (.i2p), and Lokinet (.loki) networks with per-network concurrency control.

  • NIP Compliance

    Full NIP-11 relay information and NIP-66 relay monitoring (RTT, SSL, DNS, GeoIP, HTTP, network ASN) with kind 10166/30166 event publishing.

  • PostgreSQL Backend

    25 stored functions, 11 materialized views, 44 indexes. Content-addressed metadata with SHA-256 deduplication.

  • Fully Async

    asyncpg connection pooling, aiohttp HTTP client, per-network semaphore concurrency, graceful shutdown.

  • Docker Ready

    Single parametric Dockerfile for all deployments. Full monitoring stack with Prometheus and Grafana.

  • Type Safe

    Strict mypy, frozen dataclasses with slots=True, Pydantic v2 configuration models.

Architecture

The codebase follows a strict Diamond DAG -- imports flow strictly downward:

graph TD
    S["<b>services</b><br/><small>Business logic</small>"]
    C["<b>core</b><br/><small>Pool, Brotr, BaseService</small>"]
    N["<b>nips</b><br/><small>NIP-11, NIP-66</small>"]
    U["<b>utils</b><br/><small>DNS, Keys, Transport</small>"]
    M["<b>models</b><br/><small>Pure dataclasses</small>"]

    S --> C
    S --> N
    S --> U
    N --> C
    N --> U
    C --> M
    N --> M
    U --> M

    style S fill:#7B1FA2,color:#fff,stroke:#4A148C
    style C fill:#512DA8,color:#fff,stroke:#311B92
    style N fill:#512DA8,color:#fff,stroke:#311B92
    style U fill:#512DA8,color:#fff,stroke:#311B92
    style M fill:#311B92,color:#fff,stroke:#1A237E
Layer Responsibility I/O
models Pure frozen dataclasses, enums, type definitions None
core Pool, Brotr, BaseService, Logger, Metrics Database
nips NIP-11 info fetch, NIP-66 health checks HTTP, DNS, SSL, WebSocket, GeoIP
utils DNS resolution, key management, WebSocket transport Network
services Business logic: Seeder, Finder, Validator, Monitor, Synchronizer All

Quick Start

git clone https://github.com/BigBrotr/bigbrotr.git
cd bigbrotr
curl -LsSf https://astral.sh/uv/install.sh | sh  # install uv (one-time)
uv sync --group dev
docker compose -f deployments/bigbrotr/docker-compose.yaml up -d postgres pgbouncer
python -m bigbrotr seeder --once

For a complete walkthrough, see the Getting Started guide.

Documentation Guide

Looking for... Go to...
First-time setup and installation Getting Started
System design, architecture, configuration User Guide
Step-by-step deployment and operational procedures How-to Guides
Development environment, testing, contributing Development
Python API documentation (auto-generated) API Reference
Version history Changelog