Desktop application to sync smartwatch workouts automatically to Fittrackee via USB connection.
- 🔌 USB Detection: Automatically detects when your smartwatch is connected in USB mode
- 🎯 Fittrackee Integration: OAuth 2.0 authentication with Fittrackee API
- 📊 Workout Sync: Automatic synchronization of recent workouts to your Fittrackee account
- 💾 Local Summary: View summary of recently synced workouts directly in the app
- Electron - Cross-platform desktop framework
- TypeScript - Type-safe development
- React + Vite - Modern frontend tooling
- TailwindCSS - Utility-first styling
- Node-USB - USB device detection
- Node.js 18+
- npm or yarn
- USB debugging enabled on your smartwatch (if applicable)
# 1. Clone the repository
git clone <repository-url>
cd workout-pulse
# 2. Install dependencies
npm install
# 3. Configure Fittrackee OAuth credentials
# Create a .env file in the root directory with:
# FITTRACKEE_CLIENT_ID=your_client_id
# FITTRACKEE_CLIENT_SECRET=your_client_secret
# (Or configure via app settings if using built-in auth)
# 4. Run in development mode
cd src/renderer && npm run dev
# Or from the root directory:
npm run dev# From project root
npm run build
# Create distributable packages (macOS, Windows, Linux)
npm run dist- Clone & Install:
git clone <repo> && cd workout-pulse && npm install - Configure OAuth: Set up Fittrackee credentials in
.envor app settings - Run Dev Server:
npm run dev - Connect Watch: Plug in your smartwatch via USB
- Sync Workouts: The app will automatically detect and sync recent workouts
workout-pulse/
├── src/
│ ├── main/ # Electron main process (USB detection, API calls)
│ └── renderer/ # React frontend UI
├── tests/ # Unit tests
├── package.json
└── vite.config.ts
The app uses Fittrackee's OAuth 2.0 flow for authentication. You'll need to:
- Register your application in Fittrackee (if required)
- Store client credentials securely
- Implement the OAuth callback handler
Currently using Node-USB for device detection. May need vendor-specific PID/VID configuration depending on your smartwatch brand.
- ✅ Implement robust USB device detection with fallback mechanisms - Completed: Multi-method detection (file watcher, mount scanning, polling), multi-brand support (Garmin/Fitbit/Apple Watch), error handling
- ✅ Complete Fittrackee OAuth 2.0 authentication flow - Completed: Full OAuth client with authorization URL generation, code exchange, token refresh, secure credential storage with encryption
- ✅ Build workout data extraction from smartwatch files - Completed: FIT/GPX file parsing with comprehensive data extraction (duration, distance, calories, heart rate)
- ✅ Create API client for Fittrackee workouts endpoint - Completed: Full API integration with upload, download, batch operations, duplicate detection
- ✅ Implement incremental sync logic (avoid duplicate entries) - Done via UUID checking in local database
- ✅ Add error handling and retry mechanisms for failed syncs - Implemented in API client with circuit breaker pattern
- ✅ Create local database/cache for offline workout storage - SQLite-based local workout database with full CRUD operations, filtering, statistics
- ✅ Design main dashboard with recent workouts overview - Completed: Modern dark-themed UI with statistics cards, connection status, activity distribution, and filtered workout list (All/Unsynced tabs)
- ✅ Build settings page for Fittrackee credentials configuration - Completed: OAuth modal integrated in dashboard
- ✅ Add visual feedback for USB connection status - Completed: Animated pulsing indicators, real-time detection state with spinning icons, enhanced header badge with color transitions
- ✅ Implement real-time sync progress indicator - Completed: Animated progress bar with percentage display, current/total counter, smooth CSS transitions, IPC event listeners for live updates
- ✅ Create workout details modal/view - Completed: Full-screen modal with comprehensive workout stats (duration, distance, calories, elevation, heart rate zones), device info, timeline, synced status indicator, responsive grid layout
- ✅ Add dark/light theme toggle with 3-state system - Completed: Auto/Dark/Light modes, system preference detection, smooth transitions between themes, full UI color adaptation for both light and dark modes
- Add dark/light theme toggle
- ✅ Write unit tests for workout parser - Completed: Jest test suite with 11 passing tests, 77% coverage on workout-parser.ts
- Write unit tests for USB detection logic
- Create integration tests for Fittrackee API calls (mocked)
- Add E2E tests with mocked smartwatch data
- ✅ Set up CI/CD pipeline - Completed: GitHub Actions workflow for automated testing on push
- ✅ Add detailed API documentation - Completed: Comprehensive API reference in docs/API_DOCUMENTATION.md including Fittrackee API integration, USB detection, workout parser, local database, OAuth client, security utilities, rate limiting, and logging
- ✅ Create troubleshooting guide for common issues - Completed: Detailed troubleshooting guide in docs/TROUBLESHOOTING_GUIDE.md covering USB detection errors, Fittrackee API issues, authentication problems, performance optimization, and debugging techniques
- ✅ Write contribution guidelines for future developers - Completed: Full contributing guide in docs/CONTRIBUTING.md with development setup, project structure, coding standards, testing guidelines, PR process, and documentation requirements
- Generate TypeScript type definitions
- Add inline code comments throughout the codebase
- ✅ Securely store OAuth credentials - Completed: AES-256-CBC encryption with PBKDF2 key derivation, system-specific master keys, secure file permissions (0o600), CredentialsManager class
- ✅ Implement input validation and sanitization - Completed: SecurityUtils module with email/URL/UUID validation, SQL injection detection, XSS pattern matching, workout data validation
- ✅ Add rate limiting for API requests - Completed: Token bucket algorithm integrated into FittrackeeApiClient (100 req/min), prevents abuse and ensures fair usage
- ✅ Set up logging with proper error tracking - Completed: Custom Logger class with file rotation, multi-level logging (debug/info/warn/error), daily log files in ~/.workout-pulse/logs/, structured JSON export capability
- ✅ Review and fix any security vulnerabilities - Completed: npm audit performed (13 vulnerabilities found in dependencies - electron-builder, tar, vite). Vulnerabilities are in build-time dependencies (electron-builder@26.8.1 requires breaking changes), not runtime code. Application-level security controls verified: encryption ✓, input validation ✓, rate limiting ✓. Sentry/LogRocket intentionally omitted for single-user scenario.
- Optimize USB polling interval to reduce CPU usage
- Implement lazy loading for large workout lists
- Add caching strategies for frequently accessed data
- Profile and optimize bundle size
MIT