gridpilot.gg/apps/website/docs/DEVELOPER_EXPERIENCE.md

Developer Experience Enhancement - Maximum Transparency

This document describes the enhanced developer experience features added to the GridPilot website for maximum transparency in development environments.

Overview

The enhanced developer experience provides comprehensive error handling, logging, monitoring, and replay capabilities specifically designed for development environments. All features are automatically disabled in production unless explicitly enabled.

Core Components

1. Global Error Handler (GlobalErrorHandler)

Location: lib/infrastructure/GlobalErrorHandler.ts

Features:

• Captures all uncaught JavaScript errors
• Handles unhandled promise rejections
• Overrides console.error for framework errors
• Enhanced stack traces with source map information
• Detailed error overlays in development
• Maximum logging verbosity in development

Usage:

import { getGlobalErrorHandler } from '@/lib/infrastructure/GlobalErrorHandler';

const handler = getGlobalErrorHandler();
handler.report(error, { customContext: 'value' });

Dev Overlay:

• Shows when uncaught errors occur
• Displays error type, message, stack trace
• Shows environment information
• Provides quick actions (copy, reload, log)
• Dismissible with ESC or ENTER

2. Enhanced React Error Boundary

Location: components/errors/EnhancedErrorBoundary.tsx

Features:

• Wraps React components with error handling
• Integrates with global error handler
• Shows React-specific error overlays
• Captures component stack traces
• Provides recovery mechanisms

Usage:

import { EnhancedErrorBoundary } from '@/components/errors/EnhancedErrorBoundary';

<EnhancedErrorBoundary enableDevOverlay={true}>
  <YourApp />
</EnhancedErrorBoundary>

3. API Request Logger (ApiRequestLogger)

Location: lib/infrastructure/ApiRequestLogger.ts

Features:

• Logs all API requests and responses
• Captures timing information
• Masks sensitive data automatically
• Tracks retry attempts
• Provides request history and statistics

Usage:

import { getGlobalApiLogger } from '@/lib/infrastructure/ApiRequestLogger';

const logger = getGlobalApiLogger();
const requestId = logger.logRequest(url, method, headers, body);
logger.logResponse(requestId, response, body, duration);

Auto-Interception:

// Automatically logs all fetch requests
const loggedFetch = logger.createLoggedFetch();
window.fetch = loggedFetch;

4. Debug Mode Toggle (DebugModeToggle)

Location: components/dev/DebugModeToggle.tsx

Features:

• Floating button to control debug features
• Shows real-time metrics (errors, API calls, failures)
• Quick access to test actions
• Persistent state in localStorage
• Global variable exposure

Quick Actions:

• Test Error: Triggers a test error
• Test API: Makes a failing API call
• Copy Info: Copies debug information
• Clear Logs: Clears all histories

Global Variables:

• window.__GRIDPILOT_GLOBAL_HANDLER__
• window.__GRIDPILOT_API_LOGGER__
• window.__GRIDPILOT_REACT_ERRORS__

5. Error Analytics Dashboard (ErrorAnalyticsDashboard)

Location: components/errors/ErrorAnalyticsDashboard.tsx

Features:

• Real-time error statistics
• API performance metrics
• Environment information
• Error timeline (last 10 minutes)
• Search and filter capabilities
• Export functionality

Tabs:

• Errors: Error types, recent errors, timeline
• API: Request stats, slowest requests
• Environment: Browser, platform, performance
• Raw: Export and maintenance tools

6. Error Replay System (ErrorReplay)

Location: lib/infrastructure/ErrorReplay.ts

Features:

• Captures complete error context
• Persists replays across sessions
• Replays errors with exact context
• Export replay data
• Auto-capture in development

Replay Context Includes:

• Error details and stack
• Environment (user agent, viewport, etc.)
• API request history
• React error history
• Timestamp and metadata

Usage:

import { getGlobalReplaySystem } from '@/lib/infrastructure/ErrorReplay';

const system = getGlobalReplaySystem();
const replay = system.captureReplay(error, context);
await system.replay(replay.metadata.replayId);

Integration in Layout

All components are automatically integrated in app/layout.tsx:

// Development-only initialization
if (process.env.NODE_ENV === 'development') {
  initializeGlobalErrorHandling({
    showDevOverlay: true,
    verboseLogging: true,
    captureEnhancedStacks: true,
  });
  initializeApiLogger({
    logToConsole: true,
    logBodies: true,
    logResponses: true,
  });
}

// Wrapped app with error boundaries
<EnhancedErrorBoundary enableDevOverlay={true}>
  {/* App content */}
  
  {/* Development tools */}
  {process.env.NODE_ENV === 'development' && (
    <>
      <DevToolbar />
      <DebugModeToggle />
      <ErrorAnalyticsDashboard refreshInterval={5000} />
    </>
  )}
</EnhancedErrorBoundary>

DevToolbar Integration

The existing DevToolbar now includes:

1. Notifications Section - Test notification system
2. API Status Section - Health checks and monitoring
3. Demo Login Section - Role-based testing
4. Replay Section - Error replay management

Environment Detection

All features respect the environment:

const isDev = process.env.NODE_ENV === 'development';

// Features only activate in development
if (isDev) {
  // Enable enhanced logging
  // Show dev overlays
  // Capture replays
}

Data Flow

1. Error Occurs → Global Handler captures it
2. Enhanced Logging → Detailed console output
3. Dev Overlay → Shows if enabled
4. Replay Capture → Auto-captured in dev
5. Analytics Update → Dashboard reflects changes
6. API Logger → Logs all requests/responses

Quick Debugging Workflow

Scenario 1: API Error

1. Error occurs → Dev overlay appears
2. Check overlay for details
3. Open Error Analytics Dashboard
4. View API tab for request details
5. Use Replay section to reproduce

Scenario 2: Component Crash

1. React Error Boundary catches it
2. Shows React-specific overlay
3. Check console for full stack
4. View Analytics Dashboard for context
5. Use Debug Mode Toggle to test fixes

Scenario 3: Performance Issue

1. Open Error Analytics Dashboard
2. Check API tab for slow requests
3. Use Debug Mode Toggle to trigger test calls
4. Monitor metrics in real-time

Production Considerations

All features are development-only by default:

• Global error handler: Only initializes in dev
• Dev overlays: Only show in dev
• Verbose logging: Only in dev
• Replay capture: Only in dev
• Analytics Dashboard: Hidden in production

To enable in production (use with caution):

<ErrorAnalyticsDashboard showInProduction={true} />

Performance Impact

• Development: Full logging and monitoring
• Production: Zero overhead (all features disabled)
• Memory: Limited history (max 100 items per type)
• Storage: Replays persisted in localStorage

Troubleshooting

Features Not Showing

• Check NODE_ENV is set to 'development'
• Verify components are wrapped in error boundaries
• Check browser console for initialization errors

Replay Not Working

• Ensure localStorage is available
• Check replay ID exists
• Verify error was captured

API Logging Not Working

• Confirm fetch override is applied
• Check request filter settings
• Verify logger is initialized

Best Practices

1. Use in Development: Keep all features enabled during development
2. Review Logs: Regularly check Analytics Dashboard
3. Test Replays: Use replay system to verify fixes
4. Export Data: Save important error states
5. Clear History: Periodically clear old data

Future Enhancements

Potential additions:

• External error reporting (Sentry integration)
• Real-time collaboration debugging
• Error trend analysis
• Automated replay testing
• Performance profiling integration

---

Note: All these features are designed to provide maximum transparency and debugging capabilities in development environments while maintaining zero overhead in production.