Nexus.Reader/.agent/skills/nexus-code-review/SKILL.md

name, description

name	description
nexus-code-review	Code Review Checklist and Standards for NexusReader SaaS

NexusReader Code Review Standards

When conducting or receiving a code review for NexusReader, ensure the implementation adheres to the following critical architectural and performance standards:

1. Architectural Boundaries (CQRS & Blazor Hybrid)

• Client vs. Server Execution: MediatR handlers that depend on server-side infrastructure (AppDbContext, IHubContext, secrets) MUST NOT be executed directly from client environments (WASM/MAUI).
• Dependency Leakage: Ensure NexusReader.Web.Client (WASM) does not reference NexusReader.Infrastructure if the infrastructure requires Microsoft.AspNetCore.App framework references.
• SignalR Bridges: Client-initiated state changes should be sent via SignalR SendAsync to a server Hub, which then dispatches the internal MediatR command.

2. Event Handling & Debouncing

• High-Frequency UI Events: UI actions like scrolling, resizing, or typing must be debounced.
• Trailing-Edge Debounce: Use a CancellationTokenSource and Task.Delay to ensure the last event in a rapid sequence is executed. Do not use simple time-window drops, as they result in lost final states.
• Async Void: Ensure UI event handlers do not use async void unless they are top-level framework event bindings, and even then, they must catch all exceptions.

3. SignalR & Real-Time Contexts

• Authentication Context: Do not rely on IHttpContextAccessor inside MediatR handlers triggered by SignalR Hubs. Use Context.UserIdentifier directly from the Hub and pass it as a command parameter.
• Connection State: Always check HubConnection.State == HubConnectionState.Connected before attempting to send messages from the client.
• Targeted Broadcasting: Use SignalR Groups (e.g., $"User_{userId}") to broadcast updates only to the devices owned by the relevant user.

4. Performance & Scalability

• Database Write Contention: High-frequency telemetry (like reading progress) should ideally be batched or cached in-memory before writing to SQL, unless real-time persistence is strictly required.
• Memory Leaks: Ensure all components and services that subscribe to events (e.g., OnProgressReceived, JS Observers) implement IDisposable or IAsyncDisposable and properly unsubscribe.

5. Standard Nexus Guidelines

• Result Pattern: Ensure all application logic returns Result or Result<T> via FluentResults. No exceptions for control flow.
• AI Prompts: Ensure changes to AI logic do not bypass the PromptRegistry or token estimation limits defined in AiSettings.