docs: Update documentation for 145 files

Generated by AurionDocs Job ID: c99fff50-67a3-4294-b4df-3e73f4f12de9 Source commit: 4dcb480
2026-09-04 16:46:08 +02:00 · 2026-07-23 08:10:35 +02:00
parent 4dcb480d1d
commit f8f4e03ddd
145 changed files with 22779 additions and 0 deletions
@@ -0,0 +1,18 @@
+# Attachment
+
+> **File:** `src/EchoHub.Core/Models/Attachment.cs`  
+> **Kind:** class
+
+```csharp
+public class Attachment
+```
+
+
+Represents a file attached to a message, such as an image, audio, or document. A message may carry zero or more attachments alongside its text content (Discord-style).
+
+## Remarks
+Decouples attachment data from the message to allow independent storage and retrieval while keeping a lightweight reference to the owning message. The Url provides the relative download path (for example, /api/files/{fileId}) and FileName preserves the original filename. FileSize stores the stored blob size in bytes, which corresponds to ciphertext size when database encryption is enabled. AsciiPreview offers a rendered ASCII-art preview for images in color-tag format and is null for non-image attachments; it is stored encrypted-at-rest and, in end-to-end encrypted channels, remains room-encrypted.
+
+## Notes
+- AsciiPreview is only populated for image attachments; for other kinds of attachments it is null.
+- The Message navigation property may be null if the related Message entity isn't loaded; use MessageId for persistence and rely on Message when the relationship is loaded.
@@ -0,0 +1,39 @@
+# AttachmentKind
+
+> **File:** `src/EchoHub.Core/Models/AttachmentKind.cs`  
+> **Kind:** enum
+
+```csharp
+public enum AttachmentKind
+{
+    Image,
+    Audio,
+    File
+}
+```
+
+
+AttachmentKind enumerates the possible types of a message attachment and signals how the client should render it. Use this enum when you know the specific attachment kind (image, audio, or file) so the UI can render an ASCII preview, a playback control, or a download option instead of a generic attachment rendering.
+
+## Remarks
+This enum centralizes the presentation logic for attachments and serves as a simple discriminator that decouples the attachment data from its rendering. By representing the modality with a single value, components can switch on kind to choose the appropriate UI affordance without inspecting the content payload. It helps maintain a clean separation between the data model (what the attachment is) and the presentation (how it should be shown).
+
+## Example
+```csharp
+AttachmentKind kind = AttachmentKind.Image;
+switch (kind)
+{
+    case AttachmentKind.Image:
+        Console.WriteLine("Render as ASCII image preview");
+        break;
+    case AttachmentKind.Audio:
+        Console.WriteLine("Render with audio controls");
+        break;
+    case AttachmentKind.File:
+        Console.WriteLine("Render as downloadable file");
+        break;
+}
+```
+
+## Notes
+- If the enum is extended in the future, ensure all switch expressions include a default/fallback to handle unknown values gracefully.
@@ -0,0 +1,11 @@
+# Channel
+
+> **File:** `src/EchoHub.Core/Models/Channel.cs`  
+> **Kind:** class
+
+```csharp
+public class Channel
+```
+
+
+Represents a chat channel (room) within EchoHub's domain model. It stores the channel's identity, metadata for access control, an optional topic, and the collection of messages that belong to the channel, as well as an encryption envelope used for end-to-end security. Use this type to model a distinct conversation space that can be public or restricted, with the possibility of system-managed channels that are auto-created and not user-initiated. The class ties together the channel's identity (Id, Name), its description (Topic), its visibility (IsPublic) and authentication data (PasswordHash), its system-channel semantics (IsSystem), its client-managed encryption data (EncryptionSalt, WrappedRoomKey), creation auditing (CreatedAt, CreatedByUserId), and the message history (Messages).
@@ -0,0 +1,28 @@
+# ChannelMembership
+
+> **File:** `src/EchoHub.Core/Models/ChannelMembership.cs`  
+> **Kind:** class
+
+```csharp
+public class ChannelMembership
+```
+
+
+ChannelMembership is a lightweight data container that models the association between a user and a channel, recording when the user joined. It is intended for persistence and transport of membership data; instantiate and persist this model when recording channel participation rather than scattering ad-hoc data structures.
+
+## Remarks
+ChannelMembership encapsulates the many-to-many relationship between users and channels along with a join timestamp, enabling straightforward CRUD operations, serialization, and display of membership data. As a plain DTO, it contains no behavior beyond storage of UserId, ChannelId, and JoinedAt; it complements User and Channel entities by representing their linkage. The JoinedAt default is DateTimeOffset.UtcNow at construction, which is convenient for new memberships but should be overridden or preserved from storage when loading existing records.
+
+## Example
+```csharp
+var membership = new ChannelMembership
+{
+    UserId = Guid.NewGuid(),
+    ChannelId = Guid.NewGuid()
+    // JoinedAt defaults to DateTimeOffset.UtcNow
+};
+```
+
+## Notes
+- The default JoinedAt value applies only to newly created instances; deserialization from a data store will populate JoinedAt from the stored value.
+- This class is a plain data holder with no validation or invariants; enforce domain rules at a higher layer when necessary.
@@ -0,0 +1,36 @@
+# InviteCode
+
+> **File:** `src/EchoHub.Core/Models/InviteCode.cs`  
+> **Kind:** class
+
+```csharp
+public class InviteCode
+```
+
+
+Represents a registration invitation code used to gate account creation when the server's registration mode is set to invite. An InviteCode captures the unique identifier, the actual code string, who created it, and when it was created, plus optional expiration and per-invite usage constraints. When a new REST or IRC account is created and the system is configured for invite-based registration, the incoming code must match an existing InviteCode that has not expired and that has remaining uses.
+
+## Remarks
+InviteCode acts as a persistence-side contract for invitation-based onboarding. It separates the concerns of registration gating from user data and provides a straightforward way to enforce expiration and single-use or limited-use policies at the data layer. The server's registration flow should consult these properties to validate a code before creating a new account and to record each use via UseCount, potentially preventing additional uses after MaxUses is reached.
+
+## Example
+```csharp
+// Example usage: initialize a new invite code that will expire in 7 days and allow up to 5 uses
+Guid adminUserId = Guid.NewGuid();
+var invite = new InviteCode
+{
+    Id = Guid.NewGuid(),
+    Code = "INVITE-2026-ACME",
+    CreatedByUserId = adminUserId,
+    CreatedByUsername = "admin",
+    CreatedAt = DateTimeOffset.UtcNow,
+    ExpiresAt = DateTimeOffset.UtcNow.AddDays(7),
+    MaxUses = 5,
+    UseCount = 0
+};
+```
+
+## Notes
+- Use of 'required' Code property ensures that a code value is provided when constructing instances; compile-time enforcement.
+- ExpiresAt null means never expires; If ExpiresAt is not set, the code is perpetual.
+- The class does not implement persistence or concurrency control; UseCount and MaxUses must be enforced by the application or data layer.
@@ -0,0 +1,14 @@
+# Message
+
+> **File:** `src/EchoHub.Core/Models/Message.cs`  
+> **Kind:** class
+
+```csharp
+public class Message
+```
+
+
+Message is the persistence model for a chat message in EchoHub, capturing who sent it, when, where, and what was said. Content is required text (which may be empty if the message carries only attachments), with an optional EmbedJson and a list of Attachments for attached files; SenderUserId/SenderUsername identify the author and ChannelId/Channel locate the conversation. Messages may reply to another message via ReplyToMessageId. It also includes legacy pre-attachments fields (Type, AttachmentUrl, AttachmentFileName, AttachmentFileSize) retained to support a one-time startup migration that folds old single-attachment messages into Attachments; new code never writes these and they are nulled after migration and not exposed in DTOs.
+
+## Remarks
+Architecturally, Message acts as the persistence model for chat messages, combining the modern Attachments collection with legacy fields retained to support a one-time startup data migration. New code never writes the legacy fields; they are nulled after migration and are not exposed in DTOs.
@@ -0,0 +1,24 @@
+# MessageType
+
+> **File:** `src/EchoHub.Core/Models/MessageType.cs`  
+> **Kind:** enum
+
+```csharp
+public enum MessageType
+{
+    Text,
+    Image,
+    File,
+    Audio
+}
+```
+
+
+Represents the category of a message in EchoHub. MessageType defines the four concrete payload kinds that a message can carry: Text, Image, File, or Audio. Use this enum whenever a component, data model, or API needs to convey which kind of content is attached to a message so consumers can handle, display, or validate it in a type-safe way instead of relying on strings or magic numbers.
+
+## Remarks
+Centralizes classification: this enum provides a single source of truth for message content kinds, enabling consistent routing, rendering, and validation across the system. It helps collaborators—models, serializers, and UI layers—make decisions based on content type without duplicating logic for string constants. By using an enum, you get compile-time checks and clearer intent.
+
+## Notes
+- When stored or transferred, the underlying value defaults to int (0-3) in the order shown; changing the sequence or renaming members may break persisted data.
+- If external systems expect string representations, consider mapping to/from MessageType names to avoid breaking compatibility.
@@ -0,0 +1,14 @@
+# RefreshToken
+
+> **File:** `src/EchoHub.Core/Models/RefreshToken.cs`  
+> **Kind:** class
+
+```csharp
+public class RefreshToken
+```
+
+
+RefreshToken is a persistence model that represents a refresh token tied to a user. It stores a hashed token (TokenHash), the associated user via UserId, and validity information such as ExpiresAt and CreatedAt (which defaults to the current UTC time), plus an optional RevokedAt timestamp. It exposes IsExpired, IsRevoked, and IsActive to quickly assess the token’s state. A developer would create and persist these tokens when issuing refresh tokens in an authentication flow, check IsActive (or IsExpired/IsRevoked) when validating a refresh attempt, and use RevokedAt to mark a token as revoked.
+
+## Remarks
+This class serves as a persistence-facing token entity with a foreign key to User and a corresponding navigation property, enabling lifecycle management (creation, expiry, revocation) at the data layer while providing simple state checks for business logic.
@@ -0,0 +1,44 @@
+# ServerRole
+
+> **File:** `src/EchoHub.Core/Models/ServerRole.cs`  
+> **Kind:** enum
+
+```csharp
+public enum ServerRole
+{
+    Member = 0,
+    Mod = 1,
+    Admin = 2,
+    Owner = 3
+}
+```
+
+
+Represents the role assigned to a member within a server context in EchoHub. It defines four distinct levels of authority: Member, Mod (moderator), Admin, and Owner. Use this enum whenever you need to distinguish capabilities, gate UI or actions, or persist role information instead of relying on magic numbers.
+
+## Remarks
+By centralizing roles in a single enum, the codebase can map each role to its corresponding permissions in one place, enabling consistent authorization checks across services. The explicit integer values also support stable serialization and interop when persisting or transmitting role data, without forcing string-based representations.
+
+## Example
+```csharp
+var role = ServerRole.Admin;
+switch (role)
+{
+    case ServerRole.Owner:
+    case ServerRole.Admin:
+        // elevated permissions
+        break;
+    case ServerRole.Mod:
+        // moderation tasks
+        break;
+    case ServerRole.Member:
+        // regular user actions
+        break;
+}
+Console.WriteLine($"User role: {role}"); // prints Owner, Admin, Mod, or Member
+```
+
+## Notes
+- Do not treat ServerRole as a Flags enum; do not combine roles with bitwise operators.
+- Prefer using the named constants in checks; avoid relying on numeric ordering for access decisions.
+- Changing the underlying values (0–3) can affect serialized data; coordinate evolution across all consumers to preserve compatibility.
@@ -0,0 +1,20 @@
+# ServerStatsReport
+
+> **File:** `src/EchoHub.Core/Models/ServerStatsReport.cs`  
+> **Kind:** class
+
+```csharp
+public class ServerStatsReport
+```
+
+
+Represents a snapshot of server activity for a single reporting window, produced periodically by the stats-report background job. It captures timing data (PeriodStart, PeriodEnd, WindowHours, GeneratedAt) and per-window metrics (MessagesSent, FilesUploaded, BytesUploaded, NewMembers, ActiveMembers, Connections, Disconnections, Kicks, Bans) as well as end-of-window totals (TotalMembers, OnlineNow, PeakOnline) for persistence as pretty-printed JSON.
+
+## Remarks
+Serves as a stable, serializable container for periodic server activity, enabling dashboards and trend analyses to compare windows over time. By separating window semantics (start/end, duration) from generation time, it supports reliable aggregation and rhythm-based alerts when metrics diverge.
+
+## Notes
+- GeneratedAt is intended to equal PeriodEnd; ensure synchronization when populating the model. The default initializer uses DateTimeOffset.UtcNow, which may diverge if PeriodEnd is set to a different value.
+
+## Dependencies
+- DateTimeOffset (System) — used for all timestamp properties on the model.
@@ -0,0 +1,21 @@
+# User
+
+> **File:** `src/EchoHub.Core/Models/User.cs`  
+> **Kind:** class
+
+```csharp
+public class User
+```
+
+
+The User class is a domain model that represents a person using EchoHub, encapsulating identity (Id, Username, PasswordHash), profile details (DisplayName, Bio, NicknameColor, AvatarAscii), presence (Status, StatusMessage), role-based access (Role), moderation flags (IsMuted, MutedUntil, IsBanned), and auditing timestamps (CreatedAt, LastSeenAt). Username and PasswordHash are required to create a usable user, while other fields are optional to support rich profiles; defaults establish an online, member-facing user with current timestamps when a new instance is created.
+
+## Remarks
+
+This class serves as a central data container used across authentication, user management, presence rendering, and authorization checks. It’s designed to be lightweight and serializable for persistence, while keeping domain concerns cohesive with a single user entity. The defaults for Status and Role, along with the auditing timestamps, provide a sensible initial state for newly created users.
+
+## Notes
+
+- The required fields (Username and PasswordHash) enforce that essential credentials are provided when constructing a user instance.
+- PasswordHash should be treated as sensitive data; avoid exposing it in logs or API responses and ensure the persistence layer handles security appropriately.
+- If hydrating from storage, ensure CreatedAt and LastSeenAt reflect the persisted values rather than new defaults.
@@ -0,0 +1,17 @@
+# UserStatus
+
+> **File:** `src/EchoHub.Core/Models/UserStatus.cs`  
+> **Kind:** enum
+
+```csharp
+public enum UserStatus
+{
+    Online,
+    Away,
+    DoNotDisturb,
+    Invisible
+}
+```
+
+
+Represents the current presence state of a user in EchoHub, used by UI presence indicators and presence logic throughout the app. Use Online when the user is connected and active, Away when the user is idle, DoNotDisturb to signal notifications should be minimized, and Invisible when the user should not appear online to others.