Added AI porting comments

Author: rhamlett

src/PerfProblemSimulator/Controllers/ConfigController.cs

@@ -5,11 +5,42 @@
 namespace PerfProblemSimulator.Controllers;
 
 /// <summary>
-/// Provides client-side configuration settings.
+/// Provides client-side configuration settings to the dashboard UI.
 /// </summary>
 /// <remarks>
-/// This controller exposes non-sensitive configuration to the frontend,
-/// allowing dynamic customization via Azure App Service environment variables.
+/// <para>
+/// <strong>PURPOSE:</strong>
+/// This controller exposes non-sensitive configuration to the frontend JavaScript,
+/// allowing runtime customization without rebuilding the application. This is essential
+/// for environments like Azure App Service where environment variables are the primary
+/// configuration mechanism.
+/// </para>
+/// <para>
+/// <strong>FEATURE REQUIREMENTS:</strong>
+/// <list type="bullet">
+/// <item>Return the app title (customizable per deployment)</item>
+/// <item>Return optional page footer HTML (for branding/legal notices)</item>
+/// <item>All values should have sensible defaults if not configured</item>
+/// </list>
+/// </para>
+/// <para>
+/// <strong>PORTING TO OTHER LANGUAGES:</strong>
+/// <list type="bullet">
+/// <item>PHP: Use $_ENV or getenv() to read environment variables</item>
+/// <item>Node.js: Use process.env.VARIABLE_NAME</item>
+/// <item>Java: Use System.getenv() or Spring @Value annotations</item>
+/// <item>Python: Use os.environ.get('VARIABLE_NAME', 'default')</item>
+/// <item>Ruby: Use ENV['VARIABLE_NAME'] || 'default'</item>
+/// </list>
+/// </para>
+/// <para>
+/// <strong>RELATED FILES:</strong>
+/// <list type="bullet">
+/// <item>Models/ProblemSimulatorOptions.cs - Configuration model</item>
+/// <item>wwwroot/js/dashboard.js - Frontend consumer (fetchConfig function)</item>
+/// <item>All HTML pages - Footer display logic</item>
+/// </list>
+/// </para>
 /// </remarks>
 [ApiController]
 [Route("api/[controller]")]

src/PerfProblemSimulator/Controllers/MetricsController.cs

@@ -6,23 +6,44 @@
 namespace PerfProblemSimulator.Controllers;
 
 /// <summary>
-/// Controller for retrieving current metrics and health status.
+/// REST API endpoints for retrieving current metrics and health status.
 /// </summary>
 /// <remarks>
 /// <para>
-/// <strong>Educational Note:</strong>
+/// <strong>PURPOSE:</strong>
+/// Provides HTTP polling endpoints as an alternative to the real-time SignalR/WebSocket
+/// channel. While the dashboard uses SignalR for live updates, these REST endpoints serve:
 /// </para>
+/// <list type="bullet">
+/// <item>External monitoring systems that can't use WebSockets (Azure Monitor, Prometheus scrapers)</item>
+/// <item>Scripted health checks (curl, PowerShell, automation pipelines)</item>
+/// <item>Manual debugging and testing via browser or API tools</item>
+/// <item>Integration with Azure App Service health probes</item>
+/// </list>
 /// <para>
-/// This controller provides REST endpoints for polling metrics.
-/// While the dashboard uses SignalR for real-time updates, these endpoints
-/// are useful for:
+/// <strong>DESIGN DECISION - REST vs SignalR:</strong>
+/// The dashboard UI uses SignalR because it needs sub-second updates for visualizing
+/// performance problems in real-time. These REST endpoints return cached data (not live
+/// calculations) and are suitable for 5-30 second polling intervals.
 /// </para>
+/// <para>
+/// <strong>PORTING TO OTHER LANGUAGES:</strong>
 /// <list type="bullet">
-/// <item>External monitoring systems that can't use WebSockets</item>
-/// <item>Scripted health checks (curl, PowerShell, etc.)</item>
-/// <item>Debugging and manual testing</item>
-/// <item>Integration with Azure App Service health probes</item>
+/// <item>PHP: Standard REST controller returning JSON</item>
+/// <item>Node.js/Express: app.get('/api/metrics/current', ...)</item>
+/// <item>Java/Spring: @RestController with @GetMapping</item>
+/// <item>Python/Flask: @app.route('/api/metrics/current')</item>
+/// <item>Ruby/Rails: Standard controller action rendering JSON</item>
 /// </list>
+/// </para>
+/// <para>
+/// <strong>RELATED FILES:</strong>
+/// <list type="bullet">
+/// <item>Services/MetricsCollector.cs - Provides the cached metrics data</item>
+/// <item>Models/MetricsSnapshot.cs - Data structure returned</item>
+/// <item>Hubs/MetricsHub.cs - Real-time alternative (SignalR)</item>
+/// </list>
+/// </para>
 /// </remarks>
 [ApiController]
 [Route("api/[controller]")]

src/PerfProblemSimulator/Hubs/IMetricsClient.cs

@@ -4,21 +4,42 @@
 namespace PerfProblemSimulator.Hubs;
 
 /// <summary>
-/// Interface for SignalR metrics client methods.
+/// Contract defining real-time messages that can be pushed from server to connected dashboard clients.
 /// </summary>
 /// <remarks>
 /// <para>
-/// <strong>Educational Note:</strong>
+/// <strong>PURPOSE:</strong>
+/// This interface defines the "server-to-client" message contract for the real-time communication
+/// channel. Each method represents a distinct message type that the server can push to browsers.
+/// The dashboard JavaScript registers handlers for each message type.
 /// </para>
 /// <para>
-/// This interface defines the methods that can be called on connected clients.
-/// SignalR uses this for strongly-typed hub methods, providing compile-time
-/// safety instead of magic strings.
+/// <strong>MESSAGE TYPES:</strong>
+/// <list type="bullet">
+/// <item><term>ReceiveMetrics</term><description>Periodic metrics snapshot (CPU, memory, threads) - every 1 second</description></item>
+/// <item><term>ReceiveLatency</term><description>Health probe latency measurement - every 1 second</description></item>
+/// <item><term>SimulationStarted/Completed</term><description>Simulation lifecycle events (fire-and-forget)</description></item>
+/// <item><term>ReceiveSlowRequestLatency</term><description>Slow request completion with queue time breakdown</description></item>
+/// <item><term>ReceiveLoadTestStats</term><description>Load test statistics summary - every 60 seconds during load</description></item>
+/// </list>
 /// </para>
 /// <para>
-/// When the server calls <c>Clients.All.ReceiveMetrics(snapshot)</c>, SignalR
-/// automatically serializes the snapshot and sends it to all connected browsers
-/// via WebSockets (or fallback transports).
+/// <strong>PORTING TO OTHER LANGUAGES:</strong>
+/// <list type="bullet">
+/// <item>PHP: Not applicable - use REST polling or external WebSocket library</item>
+/// <item>Node.js/Socket.io: socket.emit('receiveMetrics', snapshot)</item>
+/// <item>Java/Spring: SimpMessagingTemplate.convertAndSend("/topic/metrics", snapshot)</item>
+/// <item>Python/Flask-SocketIO: socketio.emit('receive_metrics', snapshot)</item>
+/// <item>Ruby/ActionCable: MetricsChannel.broadcast_to(user, snapshot)</item>
+/// </list>
+/// </para>
+/// <para>
+/// <strong>RELATED FILES:</strong>
+/// <list type="bullet">
+/// <item>Hubs/MetricsHub.cs - The hub that sends these messages</item>
+/// <item>Services/MetricsBroadcastService.cs - Background service that triggers broadcasts</item>
+/// <item>wwwroot/js/dashboard.js - JavaScript handlers for each message type</item>
+/// </list>
 /// </para>
 /// </remarks>
 public interface IMetricsClient

src/PerfProblemSimulator/Hubs/MetricsHub.cs

@@ -5,46 +5,52 @@
 namespace PerfProblemSimulator.Hubs;
 
 /// <summary>
-/// SignalR hub for real-time metrics broadcasting to dashboard clients.
+/// WebSocket/SignalR hub for real-time metrics broadcasting to dashboard clients.
 /// </summary>
 /// <remarks>
 /// <para>
-/// <strong>Educational Note:</strong>
+/// <strong>PURPOSE:</strong>
+/// Provides a persistent bidirectional communication channel between the server and
+/// connected browser clients. This enables real-time dashboard updates without polling.
 /// </para>
 /// <para>
-/// SignalR provides real-time communication between server and browser clients.
-/// This hub pushes metrics to all connected dashboard instances automatically.
+/// <strong>ALGORITHM:</strong>
+/// <list type="number">
+/// <item>Browser connects to /hubs/metrics endpoint (WebSocket preferred, with fallbacks)</item>
+/// <item>On connect: immediately send current metrics so client doesn't wait for next tick</item>
+/// <item>Every 1 second: MetricsBroadcastService pushes metrics to all connected clients</item>
+/// <item>On simulation events: push notifications so UI can update status indicators</item>
+/// <item>On disconnect: clean up resources (automatic via framework)</item>
+/// </list>
 /// </para>
 /// <para>
-/// <strong>How it works:</strong>
-/// </para>
-/// <list type="number">
-/// <item>Browser connects to /hubs/metrics via WebSocket (with fallback)</item>
-/// <item>MetricsCollector fires MetricsCollected event every second</item>
-/// <item>This hub broadcasts the snapshot to all connected clients</item>
-/// <item>Browser JavaScript receives the data and updates charts</item>
+/// <strong>WHY REAL-TIME vs POLLING:</strong>
+/// <list type="bullet">
+/// <item>Sub-second updates are essential for visualizing performance problems as they happen</item>
+/// <item>Push-based is more efficient than clients polling every second</item>
+/// <item>Connection state enables cleanup when browsers close</item>
+/// <item>Transport fallback (WebSocket → SSE → Long Polling) ensures broad compatibility</item>
 /// </list>
+/// </para>
 /// <para>
-/// <strong>Why SignalR over polling?</strong>
+/// <strong>PORTING TO OTHER LANGUAGES:</strong>
+/// <list type="bullet">
+/// <item>PHP: Use Ratchet or ReactPHP for WebSocket server, or external service like Pusher</item>
+/// <item>Node.js: Use Socket.IO - nearly identical concept with io.on('connection', socket => ...)</item>
+/// <item>Java/Spring: Use @MessageMapping with SimpMessagingTemplate for WebSocket STOMP</item>
+/// <item>Python: Use Flask-SocketIO with @socketio.on('connect') handlers</item>
+/// <item>Ruby: Use ActionCable with channel subscriptions</item>
+/// </list>
 /// </para>
+/// <para>
+/// <strong>RELATED FILES:</strong>
 /// <list type="bullet">
-/// <item>
-/// <term>Efficiency</term>
-/// <description>Single connection, push-based updates</description>
-/// </item>
-/// <item>
-/// <term>Real-time</term>
-/// <description>Sub-second latency vs polling intervals</description>
-/// </item>
-/// <item>
-/// <term>Scalability</term>
-/// <description>SignalR handles connection management</description>
-/// </item>
-/// <item>
-/// <term>Transport flexibility</term>
-/// <description>WebSocket → Server-Sent Events → Long Polling fallback</description>
-/// </item>
+/// <item>Hubs/IMetricsClient.cs - Message contract (what can be sent to clients)</item>
+/// <item>Services/MetricsBroadcastService.cs - Background service that triggers broadcasts</item>
+/// <item>wwwroot/js/dashboard.js - JavaScript SignalR client connection</item>
+/// <item>Program.cs - Hub endpoint mapping (/hubs/metrics)</item>
 /// </list>
+/// </para>
 /// </remarks>
 public class MetricsHub : Hub<IMetricsClient>
 {

src/PerfProblemSimulator/Middleware/ProblemEndpointGuard.cs

@@ -10,20 +10,41 @@ namespace PerfProblemSimulator.Middleware;
 /// </summary>
 /// <remarks>
 /// <para>
-/// <strong>Educational Note:</strong> This middleware implements a safety mechanism that allows
-/// the application to be deployed in production-like environments without the risk of
-/// accidentally triggering performance problems. This is a common pattern for feature flags
-/// and kill switches in production systems.
+/// <strong>PURPOSE:</strong> Implements a "kill switch" pattern that allows deploying the app
+/// to production-like environments without risk of accidentally triggering performance problems.
+/// This is a common pattern for feature flags and kill switches in production systems.
+/// </para>
+/// <para>
+/// <strong>ALGORITHM:</strong>
+/// 1. Check if request path matches guarded prefixes (/api/trigger-*, /api/allocate-*, /api/release-*)
+/// 2. If guarded AND DISABLE_PROBLEM_ENDPOINTS=true, return 403 Forbidden with JSON error body
+/// 3. Otherwise, pass request to next middleware in pipeline
 /// </para>
 /// <para>
 /// The middleware checks the environment variable at request time, not at startup, which
-/// allows for dynamic enabling/disabling without restarting the application. However,
-/// for most deployment scenarios, the value would be set at deployment time.
+/// allows for dynamic enabling/disabling without restarting the application.
+/// </para>
+/// <para>
+/// <strong>PORTING TO OTHER LANGUAGES:</strong>
+/// This middleware pattern exists in all major web frameworks:
+/// <list type="bullet">
+/// <item>PHP/Laravel: Create a middleware class, register in Kernel.php</item>
+/// <item>Node/Express: app.use((req, res, next) => { if (blocked) res.status(403).json(...); else next(); })</item>
+/// <item>Java/Spring: @Component implementing Filter, check path in doFilter()</item>
+/// <item>Python/Flask: @app.before_request decorator, return Response if blocked</item>
+/// <item>Ruby/Rails: Rack middleware or before_action in ApplicationController</item>
+/// </list>
+/// Key concepts to port: RequestDelegate (_next) = next middleware function,
+/// InvokeAsync = the filter method, short-circuit by not calling _next.
 /// </para>
 /// <para>
 /// <strong>Azure App Service Note:</strong> In Azure App Service, you can set this
 /// environment variable in the Configuration blade under Application Settings.
 /// </para>
+/// <para>
+/// <strong>RELATED FILES:</strong>
+/// Program.cs (middleware registration), Models/ErrorResponse.cs (JSON response format)
+/// </para>
 /// </remarks>
 public class ProblemEndpointGuard
 {

src/PerfProblemSimulator/Models/DetailedMetrics.cs

@@ -3,6 +3,22 @@ namespace PerfProblemSimulator.Models;
 /// <summary>
 /// Detailed CPU metrics for the health status endpoint.
 /// </summary>
+/// <remarks>
+/// <para>
+/// <strong>PURPOSE:</strong>
+/// Provides CPU-specific metrics for the /api/metrics/health endpoint.
+/// These values help diagnose whether the application is CPU-bound or I/O-bound.
+/// </para>
+/// <para>
+/// <strong>PORTING TO OTHER LANGUAGES:</strong>
+/// <list type="bullet">
+/// <item>PHP: Use sys_getloadavg() on Linux or exec('wmic cpu') on Windows</item>
+/// <item>Node.js: Use os.cpus() and calculate usage from idle/total times</item>
+/// <item>Java: Use OperatingSystemMXBean.getProcessCpuLoad()</item>
+/// <item>Python: Use psutil.cpu_percent() and psutil.cpu_count()</item>
+/// </list>
+/// </para>
+/// </remarks>
 public class CpuMetrics
 {
     /// <summary>

src/PerfProblemSimulator/Models/MemoryReleaseResult.cs

@@ -3,6 +3,31 @@ namespace PerfProblemSimulator.Models;
 /// <summary>
 /// Result of releasing allocated memory blocks.
 /// </summary>
+/// <remarks>
+/// <para>
+/// <strong>PURPOSE:</strong>
+/// Response model for the memory release endpoint. Confirms how much memory was freed
+/// and whether garbage collection was triggered. This helps users understand memory
+/// management behavior when releasing pressure.
+/// </para>
+/// <para>
+/// <strong>WHY TRACK RELEASED BLOCKS:</strong>
+/// <list type="bullet">
+/// <item>Confirms the release actually happened (blocks weren't already freed)</item>
+/// <item>Shows bytes freed so user can verify expected amount</item>
+/// <item>Indicates whether GC was forced (affects timing of actual memory return to OS)</item>
+/// </list>
+/// </para>
+/// <para>
+/// <strong>PORTING TO OTHER LANGUAGES:</strong>
+/// <list type="bullet">
+/// <item>PHP: Memory is automatically freed when variables go out of scope</item>
+/// <item>Node.js: Set arrays to null and optionally call global.gc() if --expose-gc flag set</item>
+/// <item>Java: Clear references and call System.gc() (advisory)</item>
+/// <item>Python: del references and call gc.collect()</item>
+/// </list>
+/// </para>
+/// </remarks>
 public class MemoryReleaseResult
 {
     /// <summary>

src/PerfProblemSimulator/Models/ProblemSimulatorOptions.cs

@@ -1,9 +1,40 @@
 namespace PerfProblemSimulator.Models;
 
 /// <summary>
-/// Configuration options for the Performance Problem Simulator.
-/// Loaded from the "ProblemSimulator" section of appsettings.json.
+/// Application-wide configuration options loaded from appsettings.json or environment variables.
 /// </summary>
+/// <remarks>
+/// <para>
+/// <strong>PURPOSE:</strong>
+/// Centralized configuration that can be customized per deployment environment.
+/// Follows the Options pattern for dependency injection.
+/// </para>
+/// <para>
+/// <strong>CONFIGURATION SOURCES (in priority order):</strong>
+/// <list type="number">
+/// <item>Environment variables (highest priority, e.g., ProblemSimulator__AppTitle)</item>
+/// <item>appsettings.{Environment}.json (Development, Production)</item>
+/// <item>appsettings.json (base settings)</item>
+/// <item>Default values in this class (lowest priority)</item>
+/// </list>
+/// </para>
+/// <para>
+/// <strong>AZURE APP SERVICE CONFIGURATION:</strong>
+/// In Azure Portal > App Service > Configuration > Application settings:
+/// - Name: ProblemSimulator__AppTitle
+/// - Value: "My Custom Title"
+/// The double underscore (__) translates to colon (:) for nested JSON properties.
+/// </para>
+/// <para>
+/// <strong>PORTING TO OTHER LANGUAGES:</strong>
+/// <list type="bullet">
+/// <item>PHP: Use $_ENV or .env files with vlucas/phpdotenv</item>
+/// <item>Node.js: Use dotenv package and process.env</item>
+/// <item>Java/Spring: Use @ConfigurationProperties or application.properties</item>
+/// <item>Python: Use python-dotenv and os.environ</item>
+/// </list>
+/// </para>
+/// </remarks>
 public class ProblemSimulatorOptions
 {
     /// <summary>