From 9bfb170ffa430376dc5ee1d501c56d7e755a5d6e Mon Sep 17 00:00:00 2001
From: Vitor Pamplona <vitor@vitorpamplona.com>
Date: Fri, 20 Mar 2026 17:15:05 -0400
Subject: [PATCH] simple documentation

---
 .../nip01Core/relay/server/LiveEventStore.kt     | 10 ++++++++++
 .../quartz/nip01Core/relay/server/NostrServer.kt | 16 ++++++----------
 .../nip01Core/relay/server/RelaySession.kt       |  3 ++-
 3 files changed, 18 insertions(+), 11 deletions(-)

diff --git a/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/relay/server/LiveEventStore.kt b/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/relay/server/LiveEventStore.kt
index 77f1df4fbe..4268dcef39 100644
--- a/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/relay/server/LiveEventStore.kt
+++ b/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/relay/server/LiveEventStore.kt
@@ -26,6 +26,16 @@ import com.vitorpamplona.quartz.nip01Core.store.IEventStore
 import kotlinx.coroutines.channels.BufferOverflow
 import kotlinx.coroutines.flow.MutableSharedFlow
 
+/**
+ * A reactive event store that combines historical data retrieval with live event streaming.
+ *
+ * This class wraps an [IEventStore] to provide real-time updates. When a [query] is executed,
+ * it first replays all matching historical events from the underlying store, signals the
+ * End of Stored Events (EOSE), and then continues to stream matching new events as they
+ * are inserted.
+ *
+ * @property store The underlying persistent storage for events.
+ */
 class LiveEventStore(
     private val store: IEventStore,
 ) {
diff --git a/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/relay/server/NostrServer.kt b/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/relay/server/NostrServer.kt
index 96476ab240..b443d00652 100644
--- a/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/relay/server/NostrServer.kt
+++ b/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/relay/server/NostrServer.kt
@@ -30,18 +30,14 @@ import kotlinx.coroutines.cancel
 import kotlin.coroutines.CoroutineContext
 
 /**
- * This class manages per-connection subscriptions as coroutines. Each
- * subscription ([REQ]) launches a child coroutine that first replays stored
- * events matching the filters, sends EOSE, and then streams live events.
- * Closing a subscription ([CLOSE]) immediately cancels its coroutine.
+ * Represents a Nostr relay server that manages client connections, event storage, and verification.
  *
- * The server is transport-agnostic: callers feed incoming JSON via
- * [processMessage] and receive outgoing JSON via the [send] callback
- * provided to [connect]. This allows use with any WebSocket library.
+ * This class acts as the central coordinator for a relay server, handling the lifecycle of [RelaySession]s
+ * and providing access to the underlying event store.
  *
- * @param store The [EventStore] backing this relay.
- * @param verify Validates incoming events. Defaults to cryptographic
- *                      verification (id + signature). Override for testing.
+ * @property store The persistent storage engine for Nostr events.
+ * @property parentContext The coroutine context used as a base for the server's execution scope.
+ * @property verify The function used to validate the integrity and signatures of incoming events.
  */
 class NostrServer(
     private val store: IEventStore,
diff --git a/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/relay/server/RelaySession.kt b/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/relay/server/RelaySession.kt
index da27c4a45f..78f22402b8 100644
--- a/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/relay/server/RelaySession.kt
+++ b/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/relay/server/RelaySession.kt
@@ -41,7 +41,8 @@ import kotlinx.coroutines.Job
 import kotlinx.coroutines.launch
 
 /**
- * Represents a single connected client with its active subscriptions.
+ * Represents an active session between a Nostr client and the relay.
+ * Each one of these is a connection that can hold many subscriptions
  */
 class RelaySession(
     private val store: LiveEventStore,