Coding standards, domain knowledge, and preferences.

• Root directory: Main project configuration and documentation
• electron-app/: Core Electron application code
  • main.js - Main Electron process with IPC handlers and app lifecycle
  • renderer.js - Renderer process entry point and initialization
  • preload.js - Security bridge between main and renderer processes
  • main-ui.js - UI management and tab interactions
  • utils/ - Modular utility functions (50+ modules)
  • windowStateUtils.js - Window state persistence
  • fitParser.js - FIT file parsing logic
  • index.html - Main application HTML template
  • style.css - Application styling and theme system

• fit-test-files/ - Test data files
• vscode-extension/ - Separate VS Code extension project
• vis/ - Visualization experiments
• libs/ - Third-party libraries (read-only)
• Any test, demo, or experimental folders

• Main Process (main.js): Application lifecycle, menus, file dialogs, auto-updater
• Renderer Process (renderer.js): UI initialization, module loading, error handling
• Preload Script (preload.js): Secure IPC communication bridge
• Modular Utils: 50+ specialized utility modules in utils/ directory

• Module System: ES6 modules with explicit imports/exports
• Event-Driven: IPC communication between main and renderer processes
• State Management: Centralized AppState object with reactive updates
• Theme System: Dynamic light/dark theme switching with persistence
• Performance Monitoring: Built-in timing and metrics collection
• Error Boundaries: Comprehensive error handling at all levels

• Context isolation enabled (contextIsolation: true)
• Node integration disabled (nodeIntegration: false)
• Sandbox mode enabled (sandbox: true)
• Secure IPC channels with validation
• URL navigation restrictions for security

• Electron: Desktop app framework (main/renderer/preload pattern)
• JavaScript ES6+: Modern JS with modules, async/await, destructuring
• Node.js: Backend APIs (file system, path manipulation, crypto)
• HTML5/CSS3: Modern web standards with CSS custom properties

• Data Visualization: Chart.js, Vega/Vega-Lite for advanced charts
• Mapping: Leaflet with MapLibre GL, GPS track visualization
• Data Processing: DataTables, Arquero for data manipulation
• UI Libraries: jQuery (legacy support), Hammer.js for touch
• File Formats: FIT file parsing, GPX export, CSV generation
• Theming: CSS custom properties with dynamic theme switching

• ESLint: Multi-language linting (JS, JSON, CSS, Markdown)
• Electron Builder: Multi-platform packaging and distribution
• Auto-updater: GitHub releases integration
• Testing: Vitest/Jest for unit testing

// Use modern ES6+ features
import { functionName } from "./utils/moduleName.js";
const { prop1, prop2 } = objectDestructuring;
const result = await asyncFunction();

// Error handling with try-catch
try {
    const data = await processFile(filePath);
    return { success: true, data };
} catch (error) {
    console.error("[Component] Operation failed:", error);
    return { success: false, error: error.message };
}

// Use JSDoc for documentation
/**
 * Processes FIT file data and extracts metrics
 * @param {ArrayBuffer} fileBuffer - Raw FIT file data
 * @param {Object} options - Processing options
 * @returns {Promise<Object>} Processed data with metrics
 */
async function processFitFile(fileBuffer, options = {}) {
    // Implementation
}

• Single Responsibility: Each utility module has one clear purpose
• Explicit Exports: Use named exports with descriptive names
• Import Paths: Always include .js extension for relative imports
• Error Handling: Each module should handle its own errors gracefully

// Centralized state pattern
const AppState = {
    globalData: {},
    isChartRendered: false,
    eventListeners: new Map(),
};

// Reactive updates with property descriptors
Object.defineProperty(window, "globalData", {
    get() {
        return AppState.globalData;
    },
    set(value) {
        AppState.globalData = value;
    },
});

• Lazy Loading: Load expensive components only when needed
• Event Cleanup: Always clean up event listeners to prevent memory leaks
• Performance Monitoring: Use PerformanceMonitor for timing critical operations
• Background Processing: Use Web Workers for CPU-intensive tasks

• Use createErrorHandler() wrapper for all async operations
• Implement proper window validation before IPC communication
• Follow theme synchronization pattern between main and renderer
• Use structured logging with logWithContext()

• Initialize components in proper dependency order
• Use performance monitoring for startup metrics
• Implement graceful degradation for missing dependencies
• Follow the established error handling patterns

• Each utility should be self-contained and testable
• Use consistent error handling and validation
• Export functions with clear, descriptive names
• Include JSDoc documentation for public APIs

• Follow the tabbed interface pattern established in the app
• Use the centralized theme system for styling
• Implement proper loading states and error feedback
• Support both keyboard and mouse interactions

• Use the established fitParser.js for FIT file parsing
• Implement proper error handling for corrupted files
• Support both encrypted and unencrypted FIT files
• Cache parsed data to avoid repeated processing

• Follow the established chart rendering patterns
• Support dynamic theme switching for all visualizations
• Implement proper data validation before rendering
• Use consistent color schemes and styling

• Support multiple export formats (CSV, GPX, JSON)
• Implement progress indicators for large exports
• Validate export data before file generation
• Provide user feedback for export success/failure

• Use CSS custom properties for theme variables
• Support system theme detection and manual override
• Persist theme preference in localStorage
• Propagate theme changes to all components including maps and charts

/* Dark theme example */
:root[data-theme="dark"] {
    --bg-primary: #1a1a1a;
    --text-primary: #ffffff;
    --accent-color: #3b82f6;
}

/* Light theme example */
:root[data-theme="light"] {
    --bg-primary: #ffffff;
    --text-primary: #000000;
    --accent-color: #2563eb;
}

• Expose debug utilities on window.__renderer_dev
• Enable verbose logging and performance metrics
• Provide development helper functions for testing
• Support hot reload and quick iteration

• Use structured error objects with context
• Implement global error boundaries
• Log errors with sufficient context for debugging
• Provide user-friendly error messages

• Write unit tests for utility functions
• Test error conditions and edge cases
• Mock external dependencies appropriately
• Test cross-platform compatibility

• Validate all IPC messages and parameters
• Use whitelisted channels for communication
• Sanitize file paths and user inputs
• Implement proper error boundaries

• Validate file types and extensions
• Implement size limits for uploaded files
• Use secure temporary file handling
• Clean up temporary files after processing

• Support keyboard navigation for all features
• Provide proper ARIA labels and roles
• Ensure sufficient color contrast for themes
• Support screen readers where applicable

• Provide loading indicators for long operations
• Show progress for file processing
• Implement proper error recovery
• Use consistent UI patterns throughout the app

When suggesting code changes or new features:

1. Follow established patterns in the existing codebase
2. Use the modular architecture - create new utilities in utils/ when appropriate
3. Implement proper error handling with try-catch and user feedback
4. Support the theme system for any UI changes
5. Consider performance implications and use monitoring where needed
6. Test cross-platform compatibility (Windows, macOS, Linux)
7. Document public APIs with JSDoc comments
8. Follow the established import/export patterns

• utils/theme.js - Theme management and switching
• utils/showNotification.js - User notifications
• utils/formatDistance.js / utils/formatDuration.js - Data formatting
• utils/renderChart.js / utils/renderMap.js - Visualization
• utils/handleOpenFile.js - File operations
• utils/rendererUtils.js - Common renderer utilities
• preload.js - IPC communication patterns

Always prioritize code quality, security, and user experience when making suggestions. Focus on maintainable, testable code that follows the established architectural patterns.

Utils list:

electron-app\utils\_loadOverlayFiles.js
electron-app\utils\_loadSingleOverlayFile.js
electron-app\utils\_openFileSelector.js
electron-app\utils\aboutModal.js
electron-app\utils\addChartHoverEffects.js
electron-app\utils\addExitFullscreenOverlay.js
electron-app\utils\addFullScreenButton.js
electron-app\utils\arrayBufferToBase64.js
electron-app\utils\backgroundColorPlugin.js
electron-app\utils\buildAppMenu.js
electron-app\utils\capitalize.js
electron-app\utils\CHANGELOG.md
electron-app\utils\chartFields.js
electron-app\utils\chartOptionsConfig.js
electron-app\utils\chartThemeListener.js
electron-app\utils\chartThemeUtils.js
electron-app\utils\convertDistanceUnits.js
electron-app\utils\convertTemperatureUnits.js
electron-app\utils\convertTimeUnits.js
electron-app\utils\convertValueToUserUnits.js
electron-app\utils\copyTableAsCSV.js
electron-app\utils\createAddFitFileToMapButton.js
electron-app\utils\createChartCanvas.js
electron-app\utils\createElevationProfileButton.js
electron-app\utils\createEnhancedChart.js
electron-app\utils\createExportGPXButton.js
electron-app\utils\createMapThemeToggle.js
electron-app\utils\createMarkerCountSelector.js
electron-app\utils\createPrintButton.js
electron-app\utils\createSettingsHeader.js
electron-app\utils\createShownFilesList.js
electron-app\utils\createUserDeviceInfoBox.js
electron-app\utils\displayTables.js
electron-app\utils\drawMapForLap.js
electron-app\utils\enableTabButtons.js
electron-app\utils\ensureAboutModal.js
electron-app\utils\ensureChartSettingsDropdowns.js
electron-app\utils\exportAllCharts.js
electron-app\utils\ExportUtils.js
electron-app\utils\extractDeveloperFieldsList.js
electron-app\utils\formatDistance.js
electron-app\utils\formatDuration.js
electron-app\utils\formatHeight.js
electron-app\utils\formatManufacturer.js
electron-app\utils\formatSensorName.js
electron-app\utils\formatSpeedTooltip.js
electron-app\utils\formatTime.js
electron-app\utils\formatTooltipData.js
electron-app\utils\formatTooltipWithUnits.js
electron-app\utils\formatUtils.js
electron-app\utils\formatWeight.js
electron-app\utils\generate-prettier-sarif.js
electron-app\utils\getActiveTabContent.js
electron-app\utils\getCurrentSettings.js
electron-app\utils\getFieldColor.js
electron-app\utils\getLapNumForIdx.js
electron-app\utils\getOverlayFileName.js
electron-app\utils\getThemeColors.js
electron-app\utils\getUnitSymbol.js
electron-app\utils\handleOpenFile.js
electron-app\utils\injectModalStyles.js
electron-app\utils\keyboardShortcutsModal.js
electron-app\utils\lastAnimLog.js
electron-app\utils\listeners.js
electron-app\utils\LoadingOverlay.js
electron-app\utils\loadSharedConfiguration.js
electron-app\utils\loadVersionInfo.js
electron-app\utils\mapActionButtons.js
electron-app\utils\mapBaseLayers.js
electron-app\utils\mapColors.js
electron-app\utils\mapFullscreenControl.js
electron-app\utils\mapIcons.js
electron-app\utils\mapLapSelector.js
electron-app\utils\mapMeasureTool.js
electron-app\utils\mpsToKmh.js
electron-app\utils\mpsToMph.js
electron-app\utils\openZoneColorPicker.js
electron-app\utils\overlayColorPalette.js
electron-app\utils\patchSummaryFields.js
electron-app\utils\recentFiles.js
electron-app\utils\removeExitFullscreenOverlay.js
electron-app\utils\renderAltitudeProfileChart.js
electron-app\utils\renderChart.js
electron-app\utils\renderChartJS.js
electron-app\utils\rendererUtils.js
electron-app\utils\renderEventMessagesChart.js
electron-app\utils\renderGPSTrackChart.js
electron-app\utils\renderLapZoneChart.js
electron-app\utils\renderLapZoneCharts.js
electron-app\utils\renderMap.js
electron-app\utils\renderPerformanceAnalysisCharts.js
electron-app\utils\renderPowerVsHeartRateChart.js
electron-app\utils\renderSingleHRZoneBar.js
electron-app\utils\renderSinglePowerZoneBar.js
electron-app\utils\renderSpeedVsDistanceChart.js
electron-app\utils\renderSummary.js
electron-app\utils\renderSummaryHelpers.js
electron-app\utils\renderTable.js
electron-app\utils\renderTimeInZoneCharts.js
electron-app\utils\renderZoneChart.js
electron-app\utils\setActiveTab.js
electron-app\utils\setupTabButton.js
electron-app\utils\setupTheme.js
electron-app\utils\setupWindow.js
electron-app\utils\setupZoneData.js
electron-app\utils\shouldShowRenderNotification.js
electron-app\utils\showFitData.js
electron-app\utils\showNotification.js
electron-app\utils\showUpdateNotification.js
electron-app\utils\syncControlsState.js
electron-app\utils\theme.js
electron-app\utils\toggleTabVisibility.js
electron-app\utils\updateChartAnimations.js
electron-app\utils\updateMapTheme.js
electron-app\utils\updateSystemInfo.js
electron-app\utils\zoneColorUtils.js
electron-app\utils\zoomResetPlugin.js