docs: Update documentation for 145 files

Generated by AurionDocs
Job ID: 934f8c39-8082-4942-8d17-72ed8f5f8d50
Source commit: 40aea9a

docs/auriondocs/Code/src/EchoHub.Server/Services/Stats/ServerStatsCollector.cs.md

@@ -18,16 +18,10 @@ public sealed class ServerStatsCollector
 ```
 
 
-ServerStatsCollector is a thread-safe, in-memory accumulator for server activity counters that have no natural database timestamp (connections, disconnections, kicks, bans, and peak concurrency). It updates counters via lock-free increments and uses a periodic SnapshotAndReset to emit a windowed StatsCounters and prepare the next window, including resetting the peak to the current online count.
+The ServerStatsCollector is a thread-safe, in-memory accumulator for server-activity counters that have no natural database timestamp to query after the fact—such as session connects/disconnections, moderation actions, and peak concurrent users. It exposes methods to record connections, disconnections, kicks, and bans, and maintains a running, lock-free estimate of the current peak online. A periodic stats-reporting job calls SnapshotAndReset to atomically capture and reset the window’s counters, seeding the next window’s peak with the provided online count. It is registered as a singleton and is designed to be updated from hot paths like connect/disconnect.
 
 ## Remarks
-
-Because it is registered as a singleton, multiple threads can record events without blocking. The class uses Interlocked and Volatile to implement a lock-free maximum-tracking algorithm for PeakOnline; SnapshotAndReset atomically drains all counters and resets PeakOnline to the provided onlineNow, which defines the starting point for the next window. This design favors low-latency updates in hot paths while deferring aggregation to the reporting window.
-
-## Notes
-
-- The next window's PeakOnline baseline is reset to the supplied onlineNow; if that baseline is lower than the actual concurrency at snapshot time, the subsequent peak may undercount.
-- SnapshotAndReset resets the per-window counters to zero (except PeakOnline, which is reset to onlineNow); ensure you call it on the cadence that matches your reporting window to align with dashboards.
+Architecturally, it provides a low-latency in-memory sink that decouples event counting from persistence, enabling a single, atomic snapshot per reporting window for the server’s activity data. The snapshot resets all counters and optically seeds the next window’s peak with the current online count, maintaining continuity of peak tracking across windows.
 
 ---
 
@@ -55,21 +49,14 @@ public readonly record struct StatsCounters(
 | `PeakOnline` | `int` | — |
 
 
-StatsCounters is an immutable snapshot of the counters held by ServerStatsCollector. It captures the total connections, disconnections, kicks, bans, and the peak online count at a single moment, enabling safe sharing and logging without mutating the underlying counters.
+StatsCounters is an immutable snapshot of the counters held by `ServerStatsCollector`. It records the current values of the counters `Connections`, `Disconnections`, `Kicks`, `Bans`, and the peak online figure `PeakOnline` at the moment of creation. Use this type when you need a read-only view of these statistics or to pass them between components without exposing mutable state.
 
 ## Remarks
-StatCounters uses a readonly record struct to provide value semantics, meaning two instances with the same values compare equal and it can be passed by value without side effects. It is intended to be produced by the ServerStatsCollector and consumed by telemetry, dashboards, or loggers that need a stable view of current activity. Because it is immutable, readers can snapshot and transport it across threads without additional synchronization concerns.
+By design, `StatsCounters` decouples consumers from the mutable internal state of `ServerStatsCollector`, offering a stable, shareable view of statistics. As a `readonly record struct`, it provides value-based equality and cheap copies, ensuring a snapshot can be produced and transported without synchronization concerns.
 
-## Example
-```csharp
-// Create a snapshot of current counters
-var snapshot = new StatsCounters(Connections: 1024, Disconnections: 64, Kicks: 3, Bans: 0, PeakOnline: 128);
-
-// Deconstruct to access individual values
-var (connections, disconnections, kicks, bans, peakOnline) = snapshot;
-```
-
-## Dependencies
-- ServerStatsCollector
+## Notes
+- This type is immutable; you cannot modify its fields after construction. If you need an updated view, obtain a new `StatsCounters` from the collector.
+- Copying a `StatsCounters` instance is cheap because it is a value type, making it safe to pass across threads or components without locking.
+- A snapshot reflects the state at the moment it was created; subsequent updates to the collector will not affect already-captured instances.
 
 ---

docs/auriondocs/Code/src/EchoHub.Server/Services/Stats/ServerStatsReportService.cs.md

@@ -8,12 +8,11 @@ public sealed class ServerStatsReportService : BackgroundService
 ```
 
 
-ServerStatsReportService is a background task that periodically snapshots server activity over the current reporting window, logs the snapshot as pretty-printed JSON (visible in the live server-logs room), and persists a ServerStatsReport to the database for historical trend analysis. The cadence and retention are controlled by StatsOptions; if IntervalHours is non-positive the service uses a 6-hour default.
+Background service that periodically snapshots server activity over a rolling window, logs a pretty-printed JSON snapshot (which surfaces in the live server-logs room), and persists the results to the database for historical trends. It reads cadence and retention from [`StatsOptions`](../../Config/StatsOptions.cs.md) and coordinates with [`PresenceTracker`](../PresenceTracker.cs.md), [`ServerStatsCollector`](ServerStatsCollector.cs.md), and [`EchoHubDbContext`](../../Data/EchoHubDbContext.cs.md) to compute windowed metrics such as messages sent, active members, attachments uploaded, and user counts.
 
 ## Remarks
-To achieve this, the service reads the online user count from PresenceTracker, captures in-memory statistics from ServerStatsCollector, and then opens a scoped EchoHubDbContext to compute metrics such as messages sent, active members, files uploaded, and new users within the reporting window. A fresh DI scope is created per report to ensure proper EF Core lifetimes and isolation between reports. The reporting window is defined by _periodStart and periodEnd to align live counters with database-derived metrics, ensuring the report reflects the same time span across in-memory and persisted data. The pretty-printed JSON log enhances operational visibility by surfacing structured data in the logs.
+This symbol acts as an orchestration point between live state, in-memory counters, and durable storage to provide a stable, windowed view of server activity. It builds a [`ServerStatsReport`](../../../EchoHub.Core/Models/ServerStatsReport.cs.md) for each interval and uses a dedicated scope to query [`EchoHubDbContext`](../../Data/EchoHubDbContext.cs.md), ensuring isolation from other requests. By anchoring the window to `_periodStart` and `periodEnd`, it aligns in-memory counters with database-derived counts to avoid drift.
 
 ## Notes
-- The background loop honors cancellation by awaiting Task.Delay with the provided CancellationToken and catching OperationCanceledException to exit promptly.
-- IntervalHours is validated: non-positive values fall back to 6 hours, and the interval is floored at 1 second to avoid a spinning loop.
-- Each report uses its own DbContext scope (via _scopeFactory.CreateScope()) to query the database and persist the resulting ServerStatsReport, ensuring clean lifetimes and minimal cross-report contention.
+- The interval is computed from `StatsOptions.IntervalHours`; non-positive values default to 6 hours and the interval is clamped to at least 1 second to prevent a runaway loop.
+- Restarting the service resets the reporting window; data prior to the restart belongs to the previous period and will not be included in the new interval unless recalculated by the next run.