Home - Nick2bad4u/FitFileViewer GitHub Wiki

🎯 Project Overview

FitFileViewer is a powerful desktop application built with Electron, designed for individuals seeking to explore their fitness data in detail. Whether you're monitoring your running sessions, cycling paths, workout routines, this app enables you to view and analyze FIT files generated by watches, cycling computers, and other fitness devices.

This project has been a journey—extensive CI/CD pipelines, constant improvements, and full cross-platform support to make it seamless on Windows, macOS, and Linux.

🏗️ Architecture & Key Components

Core Architecture

• Electron Framework: Follows a structured security pattern (main/renderer/preload).
• Modular Design: Over 50 utility modules neatly organized in utils/.
• ES6 Modules: Clean JavaScript with explicit imports/exports.
• Security-First: Context isolation, sandboxing, and secure IPC communication.

Main Components

1. Main Process (main.js - 838 lines)

   • Handles app lifecycle, menus, and dialogs.
   • IPC setup for file operations and theme management.
   • Auto-updater pulls new versions from GitHub releases.

2. Renderer Process (renderer.js - 480 lines)

   • Loads and initializes modules efficiently.
   • Monitors performance and handles errors.
   • Detects development vs. production mode dynamically.

3. Preload Script (preload.js - 496 lines)

   • Acts as the secure bridge between main and renderer.
   • Defines safe IPC channels.
   • Enhances error handling and validation.

4. UI Management (main-ui.js - 531 lines)

   • Manages the tabbed interface and user interactions.
   • Centralized state management with AppState.

5. FIT Parser (fitParser.js - 146 lines)

   • Parses and decodes FIT files, even handling corrupt data.
   • Maps unknown message types dynamically.

🛠️ Technology Stack

Core Technologies

• Electron (desktop framework)
• JavaScript ES6+ (modern features)
• Node.js (backend API support)
• HTML5/CSS3 (flexible styling with CSS custom properties)

Key Libraries

• Data Visualization: Chart.js, Vega/Vega-Lite.
• Mapping: Leaflet + MapLibre GL.
• Data Processing: DataTables, Arquero.
• UI Enhancements: jQuery (legacy support), Hammer.js for touch inputs.
• File Handling: FIT parsing, GPX export, CSV generation.

Development Tools

• Linting: ESLint, StyleLint.
• Testing: Vitest/Jest.
• Code Formatting: Prettier.
• Packaging: Electron Builder for cross-platform builds.

🎨 Features & Capabilities

Core Features

• Interactive maps for GPS track visualization.
• Detailed activity metrics in structured tables.
• Performance charts for deep analysis.
• Export options: CSV, GPX, JSON.
• Light/Dark theme switching.

Advanced Features

• Customizable charts for tailored analysis.
• Quick file access (recent file tracking).
• Auto-updating via GitHub releases.
• Performance monitoring baked into the UI.

🔐 Security Model

• Context Isolation & Sandboxing: Ensuring safe interactions.
• Strict IPC Validation: Protecting communication channels.
• Renderer Node Integration Disabled: Security-first approach.
• URL Navigation Restrictions: Preventing unexpected behavior.

🎯 Development Practices

Code Quality

• CI/CD Automation: 30+ GitHub Actions workflows.
• Security Scanning: CodeQL, DevSkim, and more.
• Dependency Management: Automated updates & vulnerability checks.

Architecture Patterns

• Centralized AppState for responsive updates.
• Robust error boundaries to catch unexpected issues.
• Optimized rendering with lazy loading techniques.

📊 Project Maturity

• Version: 23.1.0 (actively maintained).
• Multi-platform builds with Electron Builder.
• Comprehensive documentation (README, changelogs).
• Accessibility-conscious design (ARIA labels, keyboard support).

🏆 Strengths

1. Solid architecture with modular design.
2. High test coverage for reliability.
3. Polished UI with theme support.
4. Optimized performance for smooth experience.
5. Cross-platform compatibility baked in.

---