# scsibug/nostr-rs-relay architecture

> Architecture diagram of the GitHub repository scsibug/nostr-rs-relay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/scsibug/nostr-rs-relay
- Repository: https://github.com/scsibug/nostr-rs-relay

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    NostrClients["Nostr Clients"]:::external
    ReverseProxy["Reverse Proxy (TLS/Load-Balancer)"]:::external
    LightningService["Lightning Service"]:::external
    Proto["Proto Definitions\n(proto/nauthz.proto)"]:::external

    %% Docker Container Boundary
    subgraph "Docker Container"
        direction TB

        %% Config & Startup
        subgraph "Config & Startup"
            direction TB
            ConfigLoader["Config Loader"]:::config
            BuildScript["Build Script & Migrations"]:::config
        end

        %% API Layer
        subgraph "API Layer"
            direction TB
            WS["WebSocket Server"]:::api
            ControlClose["Control API\n(src/close.rs)"]:::api
            ControlInfo["Control API\n(src/info.rs)"]:::api
        end

        %% Core Relay Logic
        subgraph "Core Relay Logic"
            direction TB
            ConnMgr["Connection Manager"]:::core
            SubMgr["Subscription Manager"]:::core
            Dispatcher["Event Dispatcher"]:::core
        end

        %% Persistence Layer
        subgraph "Persistence Layer"
            direction TB
            DBWriterPool["DB Writer Pool"]:::persist
            QueryPool["Client Query Pool"]:::persist
            subgraph "Repositories"
                direction TB
                RepoSQLite["SQLite Repo"]:::persist
                RepoSQLiteMig["SQLite Migrations"]:::persist
                RepoPostgres["Postgres Repo"]:::persist
                RepoPostgresMig["Postgres Migrations"]:::persist
            end
        end

        %% Optional Payment
        subgraph "Optional Payment Subsystem"
            direction TB
            CLN["CLN REST Adapter"]:::payment
            LNbits["LNbits Adapter"]:::payment
        end

        %% CLI & Tooling
        subgraph "CLI & Tooling"
            direction TB
            Bulkloader["Bulkloader Binary"]:::cli
            MainBinary["Main Relay Binary"]:::cli
            ExampleClient["Example Client\n(nauthz)"]:::cli
        end
    end

    %% Connections
    NostrClients -->|"Publish/Subscribe"| WS
    ReverseProxy --> WS
    ReverseProxy --> ControlClose
    ReverseProxy --> ControlInfo

    ConfigLoader -->|loads config| BuildScript

    WS -->|manage connections| ConnMgr
    WS -->|register filters| SubMgr
    ConnMgr --> SubMgr
    SubMgr --> Dispatcher
    Dispatcher -->|persist events| DBWriterPool
    Dispatcher -->|dispatch to subs| SubMgr
    SubMgr -->|broadcast events| WS

    WS -->|history queries| QueryPool
    QueryPool --> RepoSQLite
    QueryPool --> RepoPostgres

    DBWriterPool --> RepoSQLite
    DBWriterPool --> RepoPostgres
    RepoSQLite --> RepoSQLiteMig
    RepoPostgres --> RepoPostgresMig

    ControlClose -->|"admin commands"| ConnMgr
    ControlInfo -->|"admin commands"| ConnMgr

    CLN --> LightningService
    LNbits --> LightningService

    Proto --> MainBinary

    %% Click Events
    click WS "https://github.com/scsibug/nostr-rs-relay/blob/master/src/server.rs"
    click ControlClose "https://github.com/scsibug/nostr-rs-relay/blob/master/src/close.rs"
    click ControlInfo "https://github.com/scsibug/nostr-rs-relay/blob/master/src/info.rs"
    click ConnMgr "https://github.com/scsibug/nostr-rs-relay/blob/master/src/conn.rs"
    click SubMgr "https://github.com/scsibug/nostr-rs-relay/blob/master/src/subscription.rs"
    click Dispatcher "https://github.com/scsibug/nostr-rs-relay/blob/master/src/event.rs"
    click DBWriterPool "https://github.com/scsibug/nostr-rs-relay/blob/master/src/db.rs"
    click QueryPool "https://github.com/scsibug/nostr-rs-relay/blob/master/src/db.rs"
    click RepoSQLite "https://github.com/scsibug/nostr-rs-relay/blob/master/src/repo/sqlite.rs"
    click RepoSQLiteMig "https://github.com/scsibug/nostr-rs-relay/blob/master/src/repo/sqlite_migration.rs"
    click RepoPostgres "https://github.com/scsibug/nostr-rs-relay/blob/master/src/repo/postgres.rs"
    click RepoPostgresMig "https://github.com/scsibug/nostr-rs-relay/blob/master/src/repo/postgres_migration.rs"
    click ConfigLoader "https://github.com/scsibug/nostr-rs-relay/blob/master/src/config.rs"
    click BuildScript "https://github.com/scsibug/nostr-rs-relay/blob/master/build.rs"
    click CLN "https://github.com/scsibug/nostr-rs-relay/blob/master/src/payment/cln_rest.rs"
    click LNbits "https://github.com/scsibug/nostr-rs-relay/blob/master/src/payment/lnbits.rs"
    click Bulkloader "https://github.com/scsibug/nostr-rs-relay/blob/master/src/bin/bulkloader.rs"
    click MainBinary "https://github.com/scsibug/nostr-rs-relay/blob/master/src/main.rs"
    click ExampleClient "https://github.com/scsibug/nostr-rs-relay/blob/master/examples/nauthz/src/main.rs"
    click Proto "https://github.com/scsibug/nostr-rs-relay/blob/master/proto/nauthz.proto"

    %% Styles
    classDef api fill:#ADD8E6,stroke:#000;
    classDef core fill:#90EE90,stroke:#000;
    classDef persist fill:#FFD580,stroke:#000;
    classDef config fill:#DDA0DD,stroke:#000;
    classDef payment fill:#FFFF99,stroke:#000;
    classDef cli fill:#AFEEEE,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
```
