HRM (Heart Rate Monitor) Dashboard

A real-time heart rate monitoring dashboard built with Next.js, Material-UI, WebSockets, and Spotify integration. Features a custom Express server for stateful WebSocket connections, Tabata timer with audio feedback, and live HR zone visualization.

⚠️ Important: This project uses a custom server entry (server.ts) that runs Next.js, a persistent WebSocket server, and background services. The server is stateful and cannot be deployed on serverless platforms like Vercel.

Table of Contents

• HRM (Heart Rate Monitor) Dashboard
  • Table of Contents
  • Features
  • Quick Start
    • One-Click Start with DevContainer (Recommended)
    • Manual Setup
    • Production Build
  • Project Structure
  • Available Commands
    • Primary Scripts
    • Navigation Shortcuts
    • Testing & Verification
  • VS Code Integration
  • Environment Variables
    • Spotify Setup
    • Audio System
  • Documentation
  • Architecture Overview
    • Custom Stateful Server
    • Real-time Data Flow
    • Architecture Diagram
    • Key Services
  • Development Guidelines
  • Contributing
  • Production Readiness Focus
  • Recent Architecture Improvements
    • Audio System Integration
    • UI/UX Enhancements
    • Production Readiness
  • License
  • Acknowledgments

Features

• Real-time Heart Rate Monitoring - WebSocket streaming from Bluetooth HRM devices or mock client
• Dual-Mode Timer - Tabata (work/rest intervals) and Stopwatch (count-up) modes with 5-second prepare countdown
• Audio Feedback - Original HRM beep sounds for countdown (3-2-1) and phase transitions
• HR Zone Visualization - Large percentage tiles with color-coded zones and user names/ages
• Spotify Integration - Full playback control, device selection, volume control, and now-playing display
• Mock HRM Client - Test interface with zone buttons, device ID, and noise simulation (available at /client/mock)
• Control Panel - Mobile-optimized UI with timer controls, Spotify controls, and configuration steppers (available at /client/control)
• Bluetooth HRM Support - Real heart rate monitor connection via Web Bluetooth API (available at /client/connect)
• Visual Regression Tests - Playwright screenshot-based testing

🔒 Strava Compliance & Privacy

Data Usage Disclaimer: This application is a local data generator.

• Live Dashboard: The heart rate tiles and group displays shown in screenshots utilize direct Bluetooth sensor data. They do not display data fetched from Strava, complying with Strava API Brand Guidelines regarding user privacy.
• AI Features: Any AI/LLM integration (e.g., Gemini) analyzes strictly local project metadata or locally recorded Bluetooth logs. No data fetched from the Strava API is ever sent to AI models.
• Strava Integration: The Strava API is used strictly for uploading completed activities (Write-Only).

Quick Start

One-Click Start with DevContainer (Recommended)

This repository is configured with a VS Code DevContainer, which provides a fully automated, "one-click" setup.

1. Prerequisites:

   • Docker Desktop installed and running.
   • Visual Studio Code with the Dev Containers extension.

2. Launch:

   • Open the repository in VS Code.
   • Click the "Reopen in Container" button when prompted.

That's it. The container will build, install all dependencies (pnpm install and Playwright), and create a .env.local file for you. Once the container is ready, you can start the development server:

pnpm run dev

Manual Setup

If you are not using the DevContainer, you can set up the project manually:

Prerequisites

Before setting up the project locally, ensure you have the following installed on your system:

• Node.js (version 18.x or higher recommended)

  • Download from nodejs.org
  • Verify installation: node --version

• pnpm (Package Manager)

  • Install globally: npm install -g pnpm
  • Verify installation: pnpm --version

• Git

  • Download from git-scm.com
  • Verify installation: git --version

Step-by-Step Setup Instructions

1. Clone the Repository

# Clone the repository to your local machine
git clone https://github.com/arii/hrm.git

# Navigate to the project directory
cd hrm

2. Install pnpm (if not already installed)

# Install pnpm globally using npm
npm install -g pnpm

# Verify pnpm installation
pnpm --version

3. Install Project Dependencies

# Install all required dependencies using pnpm
pnpm install --frozen-lockfile

This will install all the Node.js packages required by the project and also set up pre-commit hooks using Husky to automatically lint and format your code when you commit.

4. Install Playwright Browser Dependencies

# Install Playwright browsers for testing
pnpm exec playwright install --with-deps

5. Set Up Environment Variables

# Create your local environment file from the example
cp .env.example .env.local

Then open .env.local and fill in the required values:

# Spotify OAuth credentials (get these from developer.spotify.com/dashboard)
SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here

# NextAuth.js configuration
NEXTAUTH_URL=http://127.0.0.1:3000
NEXTAUTH_SECRET=your_random_secret_here

To generate a secure NEXTAUTH_SECRET:

openssl rand -base64 32

6. Start the Development Server

# Start the custom server (Next.js + WebSocket + background services)
pnpm run dev

The server will start and you should see output indicating:

• Next.js app running on http://127.0.0.1:3000
• WebSocket server on ws://127.0.0.1:3000/ws
• Spotify polling service initialized
• Tabata timer service initialized

7. Verify the Setup

Open your browser and navigate to:

• Dashboard: http://127.0.0.1:3000
• Mock HRM Client: http://127.0.0.1:3000/mock
• Phone Controls: http://127.0.0.1:3000/phone
• Bluetooth Connection: http://127.0.0.1:3000/connect

You should see the HRM dashboard interface load successfully.

8. (Optional) Verify Spotify Integration

# Run the Spotify verification script
pnpm run verify:spotify

This will test your Spotify credentials and connection.

Troubleshooting Setup Issues

If you encounter issues during setup:

• Port 3000 already in use: Kill any process using port 3000, or use pnpm run pm2:stop if PM2 is running
• Module not found errors: Ensure all dependencies are installed with pnpm install --frozen-lockfile
• Playwright errors: Run pnpm exec playwright install --with-deps again
• Environment variable issues: Double-check that .env.local exists and contains valid values

For more detailed troubleshooting, see the Troubleshooting section below.

⚠️ Package Manager Change: This project now uses pnpm instead of npm. All npm commands are blocked to prevent package-lock.json creation.

# 1. Create your environment file from the example
cp .env.example .env.local

# 2. Fill in the required values in .env.local (see "Environment Variables" section)

# 3. Install pnpm if not already installed
npm install -g pnpm

# 4. Install dependencies using the lockfile
pnpm install --frozen-lockfile

# 5. Install Playwright's browser dependencies
pnpm exec playwright install --with-deps

# 6. Start the development server
pnpm run dev

Migration from npm: If you accidentally run npm install, the project will block it and show a helpful message. Use the wrapper script ./scripts/npm-to-pnpm.sh to automatically convert npm commands to pnpm equivalents.

The server will start with:

• Next.js app on http://127.0.0.1:3000
• WebSocket server on ws://127.0.0.1:3000/ws
• Spotify polling service
• Tabata timer service

Production Build

# Build TypeScript server and Next.js app (optional; pnpm run start auto-builds if needed)
pnpm run build

# Start with PM2 (requires .env.production)
pnpm run start

# View logs
pnpm run pm2:logs

pnpm run start now checks for .env.production and verifies build artifacts. When .next/ or dist/server.mjs are missing it runs pnpm run build before launching PM2, so manual builds are only required when you want to inspect the output ahead of time.

Project Structure

This project follows a standard Next.js application structure with a few key additions to support its real-time, stateful nature. For a detailed guide to the project's architecture, file organization, and component inventory, please see the documentation in the docs/ directory.

• File Structure Guide: A comprehensive overview of the directories and their purposes.
• Component Inventory: A map of the major UI components and their locations.

Key Directories

• /app: Core Next.js pages, layouts, and API routes.
• **