A comprehensive workout randomizer application built with Qwik that gamifies your fitness routine!

Spin the wheel to randomly select your next workout challenge from multiple curated categories. Perfect for fitness enthusiasts who want to add variety to their training, discover new exercises, and stay motivated with a gamified approach to fitness.

Visit the live application: Wheel of Gains

• 🎮 Interactive spinning wheel with smooth animations and sound effects
• 💪 Multiple workout categories: Classic Mix, Beginner, Intermediate, Advanced, Cardio, and Strength
• 🎯 Dedicated pages for each workout category with specialized exercises
• ➕ Add and manage custom workouts with URLs for reference
• 🔢 Workout multipliers for adjusting exercise frequency
• 📱 Fully responsive design optimized for all devices
• 🎨 Modern UI with Tailwind CSS v4 styling
• 💾 Local storage persistence for custom workouts and preferences
• 📊 Spin history tracking with previous results
• 🔗 Direct workout links that open in new tabs
• ⚡ Fast page loads with Qwik's resumability
• 🎛️ Category filtering and workout management
• ♿ Accessibility features with proper ARIA labels and keyboard navigation

See the Development Roadmap below for upcoming enhancements.

• Frontend: Qwik Framework with TypeScript
• Styling: Tailwind CSS v4
• Build Tool: Vite
• Development: Qwik City for routing and SSR
• Deployment: GitHub Pages (Static Site Generation)
• Canvas: HTML5 Canvas for wheel animations
• Testing: Storybook 8.x + Playwright for component testing
• CI/CD: GitHub Actions with automated testing and deployment
• Quality Assurance: ESLint, Prettier, TypeScript compiler
• Documentation: Storybook for component documentation

This project has evolved from a Proof of Concept (POC) to a production-ready application. Here's our development journey:

• Create proper HTML structure for GitHub Pages deployment
• Migrate from React CDN to Qwik framework with TypeScript
• Set up file-based routing with Qwik City
• Configure Vite build system and development server
• Implement component architecture with reusable UI components
• Add Tailwind CSS v4 for modern styling

• #2: Implement Data Persistence with localStorage
• #3: Add Responsive Design Improvements
• #4: Implement Workout Categories and Filtering
• #5: Add PWA Capabilities for Mobile
• #6: Implement Accessibility Improvements
• Add multiple workout category pages (Beginner, Intermediate, Advanced, Cardio, Strength)
• Implement spin history tracking and results management
• Add workout management with custom workout creation

• #65: Upgrade to Storybook 9.x with Playwright Tests
• #71: CI/CD Testing Integration
• #78: Create Comprehensive Test Plan
• #61: Application Testing in Storybook
• Add comprehensive testing framework (Storybook + Playwright)
• Implement automated testing and quality assurance
• Add performance monitoring and build optimization
• #9: Add Analytics and User Tracking
• #10: Implement Advanced Animation Effects
• Add workout progress tracking and statistics
• Implement social sharing features
• Add workout timer and guided sessions

• #80: CI/CD Pipeline Setup and Fixes
• #84: DevOps Infrastructure Improvements
• Set up CI/CD Pipeline with GitHub Actions
• Add automated testing and deployment validation
• Implement comprehensive monitoring and error handling
• Add build optimization and artifact management
• #12: Add Contribution Guidelines and Documentation
• Implement user feedback collection
• Add performance analytics and monitoring dashboards

1. Choose Your Category: Select from Classic Mix, Beginner, Intermediate, Advanced, Cardio, or Strength workouts using the dropdown menu or visit dedicated category pages
2. Spin the Wheel: Click the "SPIN" button to randomly select a workout from your chosen category
3. Start Your Workout: Click "Start Workout!" to open the exercise reference in a new tab
4. Track Your Progress: View your spin history in the "Previous Results" section
5. Customize Your Arsenal: Use the "Edit Workouts" button to add, modify, or remove exercises
6. Adjust Intensity: Set multiplier values for individual workouts to increase their frequency on the wheel

Simply visit the live application and start spinning!

• Node.js: v20.19.4+ (tested version, see engines)
• npm: 10.8.2+ (latest stable recommended)

1. Clone the repository:

   git clone https://github.com/SergeiGolos/wheel-of-gains.git
   cd wheel-of-gains

2. Install dependencies (takes ~60 seconds, expect deprecated warnings):

   npm install

3. Start development server:

   npm run dev

4. Open in browser: Navigate to http://localhost:5173/

# Development
npm run dev               # Start dev server (localhost:5173/)
npm run start            # Alternative dev server with auto-open

# Code Quality
npm run fmt              # Format code with Prettier (5 seconds)
npm run fmt.check        # Check formatting without changes
npm run lint             # ESLint code checking (2 seconds)

# Building & Testing
npm run build            # Build for production (10 seconds)
npm run preview          # Preview production build (localhost:4173/wheel-of-gains/)
npm run build.types      # TypeScript type checking

# Testing & Quality Assurance
npm run test:playwright        # Run Playwright tests
npm run test:playwright:ui     # Run tests with UI mode
npm run test:playwright:headed # Run tests with browser visible
npm run analyze               # Generate code complexity analysis

# Storybook (Component Documentation & Testing)
npm run storybook            # Start Storybook dev server (localhost:6006)
npm run build-storybook      # Build Storybook for production
npm run playwright:install   # Install Playwright browsers (for CI/CD)

1. Before starting: Run npm run fmt && npm run lint to establish clean baseline
2. During development: Keep npm run dev running for hot reload
3. Before committing:
   • npm run fmt - Format all code
   • npm run lint - Check for errors
   • npm run build - Verify production build works
   • Test core functionality manually by spinning the wheel

The project uses comprehensive testing with:

• Storybook: Component documentation and interactive testing
• Playwright: End-to-end testing of component behavior
• Manual Testing: Core wheel functionality validation
• CI/CD Integration: Automated testing on every push/PR

See TESTING.md for detailed testing documentation.

This project includes automated complexity analysis to help maintain code quality:

npm run analyze

This generates a comprehensive COMPLEXITY_ANALYSIS.md report that identifies:

• High complexity components that may need refactoring
• Detailed metrics for each file (lines of code, functions, dependencies)
• Recommendations for improving code maintainability

The analysis is particularly useful for this "heavily vibe coded" project to identify technical debt and prioritize refactoring efforts.

This project includes comprehensive documentation for different audiences:

Central hub for all project documentation with organized navigation by audience and topic.

• Main README - This file, project overview and getting started
• Live Application - Try the app directly

• Testing Guide - Comprehensive testing with Storybook and Playwright
• Storybook Documentation - Component documentation and interactive testing
• Complexity Analysis - Code quality metrics and maintenance guidelines
• Test Plans - Detailed testing strategies and coverage

• CI/CD Testing Integration - Automated testing pipeline documentation
• DevOps Improvements - Pipeline fixes and infrastructure updates
• Playwright Fix Documentation - Technical fixes for testing infrastructure

• Issue Templates - Templates for different types of contributions
• GitHub Actions Workflow - Automated deployment and testing

• Component Library (Storybook) - Interactive component documentation
• Project Hub - Central access to app and documentation

We welcome contributions! This project is designed to be beginner-friendly with well-defined issues, comprehensive testing, and detailed documentation.

1. Explore the codebase:

   • Check out the live application
   • Review component documentation in Storybook
   • Read the testing documentation

2. Find an issue:

   • Browse open issues for tasks ranging from beginner to advanced
   • Each issue includes detailed acceptance criteria and implementation guidance
   • Look for issues labeled good first issue and help wanted

3. Set up development environment:

   • Follow the developer setup instructions above
   • Ensure all tests pass: npm run test:playwright
   • Verify build works: npm run build

4. Make your contribution:

   • Fork the repository and create a feature branch
   • Follow the development workflow (format, lint, build, test)
   • Add or update tests for your changes in Storybook
   • Update documentation if needed

5. Submit your changes:

   • Submit a Pull Request with your changes
   • All PRs trigger automated testing via GitHub Actions
   • Manual review ensures code quality and functionality

• Code Quality: All code must pass linting (npm run lint) and formatting (npm run fmt)
• Testing: New features should include Storybook stories and Playwright tests
• Documentation: Update relevant documentation for significant changes
• Build Verification: All changes must pass production build (npm run build)

Before submitting, ensure:

1. Automated tests pass: npm run test:playwright
2. Manual testing works: Spin the wheel and test core functionality
3. Storybook stories updated: Add stories for new components
4. Build succeeds: npm run build completes without errors

See TESTING.md for comprehensive testing guidelines.

Perfect starting points for new contributors:

Look for issues labeled good first issue and help wanted for beginner-friendly tasks.

wheel-of-gains/
├── src/
│   ├── components/          # Reusable Qwik components
│   │   ├── workout/        # Workout-specific components
│   │   ├── ui/             # UI components (buttons, forms, etc.)
│   │   ├── navigation/     # Navigation components
│   │   ├── icons/          # SVG icon components
│   │   └── router-head/    # SEO and meta tag management
│   ├── routes/             # File-based routing
│   │   ├── index.tsx       # Home page (Classic Mix)
│   │   ├── beginner/       # Beginner workouts page
│   │   ├── intermediate/   # Intermediate workouts page
│   │   ├── advanced/       # Advanced workouts page
│   │   ├── cardio/         # Cardio workouts page
│   │   ├── strength/       # Strength workouts page
│   │   └── zip/            # Dynamic workout loading from compressed data
│   ├── utils/              # Utility functions and data
│   ├── global.css          # Global styles
│   └── root.tsx            # Root application component
├── .storybook/             # Storybook configuration
├── tests/                  # Playwright test files
├── scripts/                # Build and utility scripts
├── public/                 # Static assets
├── docs/                   # Additional documentation
├── package.json            # Dependencies and scripts
├── vite.config.ts         # Vite configuration
├── tsconfig.json          # TypeScript configuration
├── playwright.config.js   # Playwright testing configuration
├── tailwind.config.js     # Tailwind CSS configuration
├── README.md              # This file
├── STORYBOOK.md           # Storybook documentation
├── TESTING.md             # Testing documentation and guides
├── CI_CD_TESTING.md       # CI/CD testing integration guide
├── DEVOPS_IMPROVEMENTS.md # DevOps pipeline improvements
└── .github/
    ├── workflows/
    │   └── pages.yml      # GitHub Pages deployment with testing
    └── ISSUE_TEMPLATE/    # Issue templates for contributors

• Simplicity: Easy to use with minimal learning curve
• Motivation: Gamify fitness routine selection
• Accessibility: Works for users of all technical levels
• Extensibility: Easy to add new features and workouts

Transform this simple workout spinner into a comprehensive fitness companion featuring:

• Workout history and progress tracking
• Social features for sharing challenges
• Integration with fitness APIs
• Personalized workout recommendations
• Mobile app with offline capabilities

This project is open source and available under the MIT License.

• Original concept inspired by fitness gamification
• UI design using Tailwind CSS component patterns
• React community for excellent documentation and examples

Ready to spin your way to gains? Try it now! 🚀