# iicuriosity/nostr-spaces-tools architecture

> Architecture diagram of the GitHub repository iicuriosity/nostr-spaces-tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iicuriosity/nostr-spaces-tools
- Repository: https://github.com/iicuriosity/nostr-spaces-tools

## Overview

nostr-spaces-tools is a library for decentralized, Nostr-signalled audio rooms. An application gathers a profile and network metrics, opens the Nostr channel, then creates or discovers a Space; joining selects a suitable peer, negotiates WebRTC connections over Nostr, and carries audio between participants. The graph, peer, and space classes implement the collaboration and media layers. Some NostrChannel and CollaborationGraph source excerpts are partial; additional feature links here are limited to README documentation.

Main entry points: [`package/classes/NostrChannel.js`](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/NostrChannel.js) (Nostr Channel), [`package/classes/Space.js`](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/Space.js) (Space Model), [`package/classes/Peer.js`](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/Peer.js) (Peer), [`package/classes/CollaborationGraph.js`](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/CollaborationGraph.js) (Collaboration Graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Profile and Metrics"]
  node_profile["Profile<br/>[Profile.js]"]
  node_metrics["Network Metrics"]
  node_indexeddb[("Profile Storage")]
end

subgraph group_rooms["Spaces and Discovery"]
  node_space["Space Model<br/>[Space.js]"]
  node_discovery["Space Discovery<br/>[NostrChannel.js]"]
  node_speech["Speech Requests<br/>[NostrChannel.js]"]
end

subgraph group_network["Peer Collaboration"]
  node_graph["Collaboration Graph"]
  node_connection["Peer Connection Record<br/>[Connection.js]"]
  node_peer["Peer<br/>[Peer.js]"]
end

subgraph group_signalling["Nostr Signalling"]
  node_channel["Nostr Channel<br/>[NostrChannel.js]"]
end

subgraph group_media["Audio Transport"]
  node_webrtc["WebRTC Peer"]
  node_audio["Remote Audio<br/>[Space.js]"]
end

node_application(("Audio Application"))
node_relays(("Nostr Relays"))
node_microphone(("Microphone"))

node_application -->|"gathers metrics"| node_metrics
node_application -->|"creates profile"| node_profile
node_application -->|"opens channel"| node_channel
node_application -.->|"stores profile"| node_indexeddb
node_indexeddb -->|"reconstructs"| node_profile
node_channel -->|"uses credentials"| node_profile
node_channel -->|"publishes events"| node_relays
node_relays -->|"delivers events"| node_channel
node_application -->|"creates or discovers"| node_channel
node_channel -->|"constructs rooms"| node_space
node_channel -->|"queries events"| node_discovery
node_discovery -->|"fetches room events"| node_relays
node_application -->|"joins room"| node_space
node_space -->|"constructs graph"| node_graph
node_space -->|"creates peers"| node_peer
node_space -->|"selects peer"| node_graph
node_graph -->|"records links"| node_connection
node_space -->|"reserves connection"| node_peer
node_peer -->|"creates connection"| node_webrtc
node_peer -->|"captures audio"| node_microphone
node_peer -->|"sends SDP and ICE"| node_channel
node_channel -->|"delivers SDP and ICE"| node_peer
node_channel -->|"measures on join"| node_metrics
node_channel -->|"updates room graph"| node_space
node_peer -->|"passes remote stream"| node_audio
node_audio -->|"broadcasts tracks"| node_space
node_application -->|"requests to speak"| node_speech
node_speech -->|"publishes request"| node_relays
node_relays -->|"delivers response"| node_speech
node_speech -->|"updates requests"| node_space

click node_profile "https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/Profile.js"
click node_metrics "https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/utility/NetworkMetricsExtractor.js"
click node_indexeddb "https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/utility/IndexedDBService.js"
click node_channel "https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/NostrChannel.js"
click node_space "https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/Space.js"
click node_discovery "https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/NostrChannel.js"
click node_speech "https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/NostrChannel.js"
click node_graph "https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/CollaborationGraph.js"
click node_connection "https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/Connection.js"
click node_peer "https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/Peer.js"
click node_audio "https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/Space.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_profile,node_metrics,node_indexeddb toneBlue
class node_space,node_discovery,node_speech toneAmber
class node_graph,node_connection,node_peer toneMint
class node_channel toneRose
class node_webrtc,node_audio,node_application,node_relays,node_microphone toneIndigo
```

## Components

### Profile and Metrics

- [Profile](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/Profile.js): `package/classes/Profile.js`
- [Network Metrics](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/utility/NetworkMetricsExtractor.js): `package/utility/NetworkMetricsExtractor.js`
- [Profile Storage](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/utility/IndexedDBService.js): `package/utility/IndexedDBService.js`

### Spaces and Discovery

- [Space Model](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/Space.js): `package/classes/Space.js`
- [Space Discovery](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/NostrChannel.js): `package/classes/NostrChannel.js`
- [Speech Requests](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/NostrChannel.js): `package/classes/NostrChannel.js`

### Peer Collaboration

- [Collaboration Graph](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/CollaborationGraph.js): `package/classes/CollaborationGraph.js`
- [Peer Connection Record](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/Connection.js): `package/classes/Connection.js`
- [Peer](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/Peer.js): `package/classes/Peer.js`

### Nostr Signalling

- [Nostr Channel](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/NostrChannel.js): `package/classes/NostrChannel.js`

### Audio Transport

- **WebRTC Peer**
- [Remote Audio](https://github.com/iicuriosity/nostr-spaces-tools/blob/main/package/classes/Space.js): `package/classes/Space.js`

### Other components

- **Audio Application**
- **Nostr Relays**
- **Microphone**

## Connections

- Audio Application → Network Metrics: gathers metrics
- Audio Application → Profile: creates profile
- Audio Application → Nostr Channel: opens channel
- Audio Application → Profile Storage: stores profile
- Profile Storage → Profile: reconstructs
- Nostr Channel → Profile: uses credentials
- Nostr Channel → Nostr Relays: publishes events
- Nostr Relays → Nostr Channel: delivers events
- Audio Application → Nostr Channel: creates or discovers
- Nostr Channel → Space Model: constructs rooms
- Nostr Channel → Space Discovery: queries events
- Space Discovery → Nostr Relays: fetches room events
- Audio Application → Space Model: joins room
- Space Model → Collaboration Graph: constructs graph
- Space Model → Peer: creates peers
- Space Model → Collaboration Graph: selects peer
- Collaboration Graph → Peer Connection Record: records links
- Space Model → Peer: reserves connection
- Peer → WebRTC Peer: creates connection
- Peer → Microphone: captures audio
- Peer → Nostr Channel: sends SDP and ICE
- Nostr Channel → Peer: delivers SDP and ICE
- Nostr Channel → Network Metrics: measures on join
- Nostr Channel → Space Model: updates room graph
- Peer → Remote Audio: passes remote stream
- Remote Audio → Space Model: broadcasts tracks
- Audio Application → Speech Requests: requests to speak
- Speech Requests → Nostr Relays: publishes request
- Nostr Relays → Speech Requests: delivers response
- Speech Requests → Space Model: updates requests