feat: add detailed documentation for authentication, connection, messaging, channels, moderation, and media flows

2026-09-04 00:26:07 +02:00 · 2026-02-24 20:50:20 +01:00
parent 8647b05c12
commit fb4f6c34ed
9 changed files with 847 additions and 0 deletions
@@ -0,0 +1,159 @@
+# Channels
+
+## Channel Creation
+
+Channels are created via the REST API. Public channels are broadcast to all
+connected clients.
+
+```mermaid
+sequenceDiagram
+    participant Client as Client (TUI/API)
+    participant CC as ChannelsController
+    participant ChS as ChannelService
+    participant CS as ChatService
+    participant DB as SQLite
+    participant SRB as SignalRBroadcaster
+    participant IRCB as IrcBroadcaster
+
+    Client->>CC: POST /api/channels {name, topic, isPublic}
+    CC->>ChS: CreateChannelAsync(creatorId, name, topic, isPublic)
+    ChS->>ChS: Normalize name (lowercase, trim)
+    ChS->>ChS: Validate format (2-100 chars, regex)
+    ChS->>DB: Check duplicate
+    ChS->>DB: INSERT Channel + ChannelMembership (creator auto-added)
+    ChS-->>CC: ChannelDto
+
+    alt Channel is public
+        CC->>CS: BroadcastChannelUpdatedAsync(channel)
+        CS->>SRB: SendChannelUpdatedAsync(channelDto)
+        SRB->>SRB: Notify all SignalR clients
+        CS->>IRCB: SendChannelUpdatedAsync(channelDto)
+    end
+
+    CC-->>Client: 201 Created (ChannelDto)
+```
+
+**Code references:**
+
+| Step | File | Location |
+|------|------|----------|
+| Controller endpoint | `src/EchoHub.Server/Controllers/ChannelsController.cs` | Lines 60-76 |
+| Channel service create | `src/EchoHub.Server/Services/ChannelService.cs` | Lines 50-90 |
+| Broadcast updated | `src/EchoHub.Server/Services/ChatService.cs` | Lines 308-309 |
+
+---
+
+## Channel Deletion
+
+Only the channel creator (or admin) can delete a channel. The default channel
+is protected.
+
+```mermaid
+sequenceDiagram
+    participant Client as Client
+    participant CC as ChannelsController
+    participant ChS as ChannelService
+    participant DB as SQLite
+
+    Client->>CC: DELETE /api/channels/{channel}
+    CC->>ChS: DeleteChannelAsync(channelName, callerId)
+    ChS->>ChS: Reject if default channel
+    ChS->>DB: Lookup channel
+    ChS->>ChS: Verify caller is creator or admin
+    ChS->>DB: DELETE Channel (cascade: messages, memberships)
+    ChS-->>CC: Success
+    CC-->>Client: 204 No Content
+```
+
+**Code references:**
+
+| Step | File | Location |
+|------|------|----------|
+| Controller endpoint | `src/EchoHub.Server/Controllers/ChannelsController.cs` | Lines 94-106 |
+| Channel service delete | `src/EchoHub.Server/Services/ChannelService.cs` | Lines 119-144 |
+
+---
+
+## Joining a Channel
+
+Both SignalR and IRC clients join channels through `ChatService`. The presence
+tracker determines if this is a genuinely new join (vs. a second connection) and
+broadcasts accordingly.
+
+```mermaid
+sequenceDiagram
+    participant Client as Client (SignalR or IRC)
+    participant Entry as ChatHub / IrcCommandHandler
+    participant CS as ChatService
+    participant ChS as ChannelService
+    participant PT as PresenceTracker
+    participant DB as SQLite
+    participant SRB as SignalRBroadcaster
+    participant IRCB as IrcBroadcaster
+
+    Client->>Entry: JoinChannel / JOIN #channel
+    Entry->>CS: JoinChannelAsync(connectionId, userId, username, channel)
+    CS->>ChS: EnsureChannelMembershipAsync(userId, channel)
+    ChS->>DB: INSERT ChannelMembership (if not exists)
+
+    CS->>PT: JoinChannel(username, channel)
+    PT-->>CS: isNewJoin?
+
+    alt First connection in this channel
+        CS->>DB: Fetch UserPresenceDto
+        CS->>CS: BroadcastToAllAsync(SendUserJoinedAsync)
+        par
+            CS->>SRB: SendUserJoinedAsync(channel, user, excludeConn)
+        and
+            CS->>IRCB: SendUserJoinedAsync(channel, user)
+        end
+    end
+
+    CS->>DB: Fetch message history
+    CS-->>Entry: (history, error)
+    Entry-->>Client: History messages
+```
+
+**Code references:**
+
+| Step | File | Location |
+|------|------|----------|
+| SignalR hub join | `src/EchoHub.Server/Hubs/ChatHub.cs` | Lines 59-81 |
+| IRC join | `src/EchoHub.Server.Irc/IrcCommandHandler.cs` | Lines 361-414 |
+| ChatService join | `src/EchoHub.Server/Services/ChatService.cs` | Lines 96-135 |
+| Presence join | `src/EchoHub.Server/Services/PresenceTracker.cs` | Lines 58-70 |
+| SignalR broadcast | `src/EchoHub.Server/Services/SignalRBroadcaster.cs` | Lines 26-32 |
+| IRC broadcast | `src/EchoHub.Server.Irc/IrcBroadcaster.cs` | Lines 34-41 |
+
+---
+
+## Leaving a Channel
+
+```mermaid
+sequenceDiagram
+    participant Client as Client
+    participant Entry as ChatHub / IrcCommandHandler
+    participant CS as ChatService
+    participant PT as PresenceTracker
+    participant SRB as SignalRBroadcaster
+    participant IRCB as IrcBroadcaster
+
+    Client->>Entry: LeaveChannel / PART #channel
+    Entry->>CS: LeaveChannelAsync(connectionId, username, channel)
+    CS->>PT: LeaveChannel(username, channel)
+    CS->>CS: BroadcastToAllAsync(SendUserLeftAsync)
+    par
+        CS->>SRB: SendUserLeftAsync(channel, username)
+    and
+        CS->>IRCB: SendUserLeftAsync(channel, username)
+    end
+```
+
+**Code references:**
+
+| Step | File | Location |
+|------|------|----------|
+| SignalR hub leave | `src/EchoHub.Server/Hubs/ChatHub.cs` | Lines 83-96 |
+| IRC part | `src/EchoHub.Server.Irc/IrcCommandHandler.cs` | Lines 416-435 |
+| ChatService leave | `src/EchoHub.Server/Services/ChatService.cs` | Lines 137-143 |
+| Presence leave | `src/EchoHub.Server/Services/PresenceTracker.cs` | Lines 72-81 |