🏋️ THE GRIND DESIGN

Version: V30.0 (Mobile UI Redesign) Status: Production Ready Last Updated: January 10, 2026

A clinical-grade Progressive Web App for evidence-based strength training management. Built with vanilla JavaScript, designed for both personal training and professional analytics.

✨ Key Features

V30.0: Mobile-First UI Redesign 🆕

🎨 Modern Dark Theme - OLED-friendly pure black background with teal accents
📱 Mobile-First Design - Optimized for 375px-428px viewports
🎯 Bottom Navigation - Thumb-zone optimized navigation bar
📊 Enhanced Analytics - Dark-themed Chart.js visualizations
💎 Teal Accent System - Medical/tech aesthetic with consistent color palette
⚡ Unified Navigation - Smooth view transitions (no modal overlays)
📈 Interactive Charts - Clinical-grade data visualization
🎨 Status-Coded Cards - Green/yellow/red ratio indicators
🩺 Clinical Insights - Severity-based styling for recommendations
💪 Stats Cards - Interactive weight and TDEE display

Core Training Management

📅 Smart Session Rotation - Auto-suggests next workout based on recovery time
🎯 Exercise Variants - Multiple equipment options per movement pattern
💪 Progressive Overload Tracking - Volume, intensity, RPE/RIR metrics
⚡ Plate Calculator - Auto-calculates barbell loading for target weights
🔄 Spontaneous Mode - Log off-program workouts without disrupting rotation

Clinical Analytics

📊 Volume Progression Charts - Track hypertrophy stimulus over time
🎨 Muscle Distribution Analysis - Identify training imbalances
📈 RPE/RIR Tracking - Monitor fatigue accumulation
🔬 Half-Set Rule - PRIMARY (1.0x) vs SECONDARY (0.5x) muscle contribution

V29.0: Advanced Analytics & Injury Prevention 🆕

🦵 Quad/Hamstring Balance - ACL injury prevention (optimal ratio: 0.6-0.8)
- Visual progress bar with danger/warning/optimal zones
- Volume breakdown display
- Automatic imbalance detection
⚖️ Push/Pull Balance - Shoulder health monitoring (optimal ratio: 1.0-1.2)
- Total, upper, and lower body ratios
- Collapsible breakdown view
- Prevents shoulder impingement
💪 Core Training Analysis - Spine stability assessment (target: 15-25 sets/week)
- Weekly volume tracking
- Frequency and variety metrics
- Dr. Stuart McGill's evidence-based thresholds
🤸 Bodyweight Exercise Integration - Load estimation using biomechanics research
- 30+ exercises with research-based multipliers (Pull Up: 100% BW, Push Up: 64% BW)
- User weight detection with smart fallback
- Training style identification
💡 Clinical Insights Engine - 3-7 prioritized evidence-based recommendations
- 🚨 Danger alerts (immediate injury risk)
- ⚠️ Warning notifications (imbalances detected)
- ℹ️ Optimization tips
- ✅ Success confirmations
🔬 Scientific Citation System - Research sources for all recommendations
- Interactive tooltips with full citations
- Croisier et al. (2008), NSCA Guidelines, Dr. Stuart McGill
- Complete methodology in SCIENTIFIC_BASIS.md

User Guide | Scientific Basis

AI Integration

🤖 AI Command Center - Integrated AI consultation with prompt library
- 12 built-in prompt templates (coaching, development, schema)
- Custom prompt creation with CRUD operations
- Smart placeholder replacement {% raw %}({{VERSION}}, {{CONTEXT}}, etc.){% endraw %}
- Export/Import prompt collections
- Dynamic context generation for AI conversations
🤖 Smart Merge Engine - AI (Gemini/GPT) can update programs via JSON
🔍 Fuzzy Exercise Matching - Auto-maps exercise name variations
📋 Conflict Detection - User control over AI-suggested changes
🛡️ Auto-Backup - Safety layer before AI merges

Data Integrity

💾 Offline-First - Works completely offline (PWA)
☁️ Google Drive Sync - Optional cloud backup/restore
🔐 LocalStorage Safety - LS_SAFE wrapper with error handling
📦 Backup System - Timestamped backups before destructive operations
✅ Canonical Exercise Names - Prevents fragmented analytics (V26.6+)

Exercise Library

📚 100+ Exercises - Comprehensive database with biomechanics notes
🏋️ Equipment Tags - [Barbell], [Machine], [DB], [Cable], [Bodyweight]
🔬 Clinical Notes - Safety warnings, contraindications, form cues
🎥 Video Links - YouTube demonstrations
🎯 Target Rep Ranges - Evidence-based recommendations

🏗️ Architecture (V29.0)

Modular Structure (13 files, ~13,600 lines total):

project-root/
├── index.html              (2,594 lines) - HTML skeleton + V29 analytics UI
├── exercises-library.js    (1,817 lines) - Exercise database
├── js/
│   ├── constants.js        (455 lines)   - PRESETS, STARTER_PACK, version metadata
│   ├── core.js            (344 lines)   - LS_SAFE, APP.state, APP.core
│   ├── validation.js      (491 lines)   - APP.validation
│   ├── data.js            (1,218 lines)  - APP.data, CRUD operations
│   ├── safety.js          (325 lines)   - APP.safety, backup/restore
│   ├── stats.js           (2,715 lines)  - APP.stats, analytics, V29 ratios
│   ├── session.js         (750 lines)   - APP.session management
│   ├── cardio.js          (111 lines)   - APP.cardio, APP.timer
│   ├── ui.js              (2,101 lines)  - APP.ui, rendering, V29 tooltips
│   ├── ai-bridge.js       (1,060 lines)  - APP.aiBridge, prompt library
│   ├── debug.js           (46 lines)    - APP.debug, error handling
│   ├── nav.js             (829 lines)   - APP.nav, APP.init
│   └── cloud.js           (195 lines)   - Google Drive integration
├── SCIENTIFIC_BASIS.md     (800 lines)  - V29 methodology & citations
├── ANALYTICS_GUIDE.md      (400 lines)  - V29 user guide
└── sw.js, manifest.json    - PWA configuration

Key Improvements:

✅ V27: 58% reduction in index.html size (9,000 → 2,203 lines)
✅ V28: AI Command Center with 12 built-in prompts + custom prompt management
✅ V29: Advanced Analytics - Injury risk detection, bodyweight integration, scientific citations
✅ Clear separation of concerns (module per namespace)
✅ Easier maintenance and AI context efficiency
✅ Git-friendly (cleaner diffs, parallel development)

🚀 Quick Start

1. Install as PWA

1. Open https://your-app-url.com in Chrome/Edge
2. Click "Install" button (or browser menu → Install)
3. App appears on home screen/desktop
4. Works offline after first load

2. Configure Profile

1. Open app → Click profile icon
2. Enter name, height, age, gender
3. Set activity factor (sedentary to very active)
4. Save → TDEE auto-calculated

3. Log First Workout

1. Dashboard → Click suggested "Next Workout"
2. Fill in weight, reps, RPE for each set
3. Use plate calculator (barbell exercises)
4. Click "Complete Workout"
5. View analytics in Stats tab

4. AI-Powered Program Updates (Optional)

1. Library → Copy workout JSON
2. Send to Gemini/GPT: "Analyze and update my program"
3. AI returns optimized JSON
4. Paste into "Apply AI Program"
5. Smart Merge auto-updates targets

📚 Documentation

Comprehensive documentation suite for developers and contributors:

Document	Purpose	Audience
SCIENTIFIC_BASIS.md 🆕	V29 clinical thresholds, calculations, research citations	Medical Professionals, Researchers
ANALYTICS_GUIDE.md 🆕	V29 user guide for Advanced Analytics dashboard	Users, Athletes, Coaches
ARCHITECTURE.md	System design, data flows, V27-V29 architecture	Developers, Contributors
CODING_GUIDELINES.md	Code standards, V27 module development rules	Developers, AI Assistants
KNOWN_ISSUES.md	Active bugs, V27 gotchas, workarounds	Users, Developers
CHANGELOG_DETAILED.md	Version history with technical context	All
DEBUGGING_PLAYBOOK.md	Step-by-step troubleshooting guide	Users, Support
EXERCISE_LIBRARY_GUIDE.md	How to add/modify exercises	Contributors
HANDOVER_V27.md	V27 complete story (phases, bugs, solutions)	Developers, AI Assistants

🧪 Use Cases

For Athletes

Track progressive overload scientifically
Monitor fatigue to prevent overtraining
Optimize volume distribution across muscle groups
Log spontaneous workouts without disrupting program

For Coaches

AI-assisted program updates via JSON
Client progress tracking with clinical metrics
Export data for analysis in external tools
Template programs for multiple clients

For Researchers

Export workout data to CSV/JSON
Analyze volume-fatigue relationships
Study RPE-RIR correlations
Long-term strength progression analysis

🔐 Privacy & Data

Data Storage

Primary: Browser LocalStorage (5-10MB limit)
Location: Your device only (no server transmission)
Backup: Optional Google Drive sync (requires manual auth)

Privacy Guarantees

✅ No analytics tracking
✅ No user accounts required
✅ No data sent to servers
✅ No cookies (except localStorage)
✅ Works completely offline

Data Portability

Export full backup to JSON file
Import from JSON (migration support)
Google Drive backup/restore
No vendor lock-in

📊 Version History Highlights

Version	Date	Major Changes
V29.0	Jan 2026	Advanced Analytics - Injury risk detection, bodyweight integration, scientific citations (5 checkpoints, 1,638 lines)
V28.0	Jan 2026	AI Command Center - 12 built-in prompts, custom prompt CRUD, smart placeholders
V27.0	Jan 2026	Modular architecture - 12 modules, 8-phase refactoring, 11 bugs fixed
V26.6	Dec 2025	Data integrity hotfix - canonical exercise naming enforcement
V26.5	Dec 2025	Library expansion - 40+ machine variations with clinical notes
V25.0	Oct 2025	Smart Merge Engine - AI program integration
V24.0	Sep 2025	PWA optimization - installable, offline-capable
V23.0	Aug 2025	Clinical analytics - RPE/RIR tracking, fatigue monitoring
V22.0	Jul 2025	Google Drive backup/restore
V21.0	Jun 2025	Exercise library foundation (100+ exercises)
V20.0	May 2025	Spontaneous mode

Full changelog: See CHANGELOG_DETAILED.md

🐛 Known Issues

Active Issues:

Console validation warning flood (cosmetic) - See KNOWN_ISSUES.md
Fuzzy match ambiguity with short queries - See KNOWN_ISSUES.md
LocalStorage quota limit on 3+ years of data - See KNOWN_ISSUES.md

V27 Architectural Gotchas:

Arrow functions capture closure scope - See KNOWN_ISSUES.md
Module load order is non-negotiable - See KNOWN_ISSUES.md
Object.assign vs direct assignment - See KNOWN_ISSUES.md

For troubleshooting: See DEBUGGING_PLAYBOOK.md

🤝 Contributing

Adding Exercises

See EXERCISE_LIBRARY_GUIDE.md for detailed instructions.

Quick guide:

// 1. Add to EXERCISE_TARGETS (exercises-library.js)
"[Machine] New Exercise": [{ muscle: "chest", role: "PRIMARY" }]

// 2. Add to EXERCISES_LIBRARY.chest
{
  n: "[Machine] New Exercise",
  t_r: "8-12",
  bio: "Biomechanics explanation...",
  note: "Execution tips<br><br>⚠️ CLINICAL: Safety notes",
  vid: ""
}

Code Contributions (V27+)

Read CODING_GUIDELINES.md first
Follow V27 module development rules
Test edge cases (empty data, invalid input, offline mode)
Create backup before data mutations: APP.safety.createBackup("operation")
Submit pull request with clear description

V27 Module Requirements:

✅ Use IIFE pattern: (function() { ... })()
✅ Add namespace guard: if (!window.APP) window.APP = {};
✅ Use window.APP.* for cross-module calls
✅ Add load confirmation: console.log("[MODULE] ✅ Loaded")
✅ Update ARCHITECTURE.md with dependencies

Bug Reports

Include:

Browser version (Chrome, Safari, Firefox, etc.)
Steps to reproduce
Console errors (screenshot or copy/paste)
LocalStorage export (if relevant)
Check KNOWN_ISSUES.md first

⚠️ Important Rules (For Developers/AI)

NEVER:

❌ Use localStorage directly → Always use LS_SAFE wrapper
❌ Use \n for line breaks → Always use <br> (HTML-safe)
❌ Delete data without backup → Always APP.safety.createBackup()
❌ Skip input validation → Always use APP.validation methods
❌ Use window.APP = APP → Always use Object.assign(window.APP, APP) (V27+)
❌ Use local APP in closures → Always use window.APP.* for cross-module (V27+)

ALWAYS:

✅ Validate user inputs before processing
✅ Use canonical exercise names (fuzzy matching)
✅ Preserve backward compatibility
✅ Test localStorage edge cases
✅ Follow module load order (V27+)
✅ Add defensive error handling (V27+)

See CODING_GUIDELINES.md for complete rules.

🎓 Learning Resources

For New Developers:

Read HANDOVER_V28.md - V28 complete story
Read ARCHITECTURE.md - System design
Read CODING_GUIDELINES.md - Code patterns
Study modules in order (core → validation → data → ui → nav)

Critical Concepts:

IIFE module pattern (V27+)
Closure scoping (window.APP vs local APP)
Object.assign merge pattern
Module load order dependencies
LS_SAFE wrapper pattern

📝 License

[Not yet]

👥 Credits

Development Team

Lead Project Manager: sand01chi

Vision & direction
Requirements definition
Product roadmap

Design Architect: Claude.ai

Technical specifications
Architecture design
Feature planning

Design Auditor: Gemini

Architecture validation
Risk assessment
Design review

Lead Coder: Claude Code

Implementation in VS Code
Code quality
Production deployment

Version Highlights

V28.0 (AI Command Center):

12 built-in AI prompts
Custom prompt CRUD operations
Smart placeholder system
Duration: ~8.5 hours

V27.0 (Modular Architecture):

8-phase refactoring
12 modules created
11 critical bugs solved
Duration: 3 days

Built with ❤️ for evidence-based strength training

END OF README.md

Name		Name	Last commit message	Last commit date
Latest commit History 284 Commits
.claude		.claude
.vscode		.vscode
docs/handovers		docs/handovers
js		js
ANALYTICS_GUIDE.md		ANALYTICS_GUIDE.md
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG_DETAILED.md		CHANGELOG_DETAILED.md
CODING_GUIDELINES.md		CODING_GUIDELINES.md
DEBUGGING_PLAYBOOK.md		DEBUGGING_PLAYBOOK.md
EXERCISE_LIBRARY_GUIDE.md		EXERCISE_LIBRARY_GUIDE.md
HANDOVER_V30.md		HANDOVER_V30.md
KNOWN_ISSUES.md		KNOWN_ISSUES.md
QUICK_START.md		QUICK_START.md
README.md		README.md
SCIENTIFIC_BASIS.md		SCIENTIFIC_BASIS.md
SYNC_REPORT_V30.8.md		SYNC_REPORT_V30.8.md
WORKOUT_LOGGING_GUIDE.md		WORKOUT_LOGGING_GUIDE.md
app-logo.png		app-logo.png
exercises-library.js		exercises-library.js
gitignore		gitignore
index.html		index.html
manifest.json		manifest.json
sw.js		sw.js

Folders and files

Latest commit

History

Repository files navigation

🏋️ THE GRIND DESIGN

✨ Key Features

V30.0: Mobile-First UI Redesign 🆕

Core Training Management

Clinical Analytics

V29.0: Advanced Analytics & Injury Prevention 🆕

AI Integration

Data Integrity

Exercise Library

🏗️ Architecture (V29.0)

🚀 Quick Start

1. Install as PWA

2. Configure Profile

3. Log First Workout

4. AI-Powered Program Updates (Optional)

📚 Documentation

🧪 Use Cases

For Athletes

For Coaches

For Researchers

🔐 Privacy & Data

Data Storage

Privacy Guarantees

Data Portability

📊 Version History Highlights

🐛 Known Issues

🤝 Contributing

Adding Exercises

Code Contributions (V27+)

Bug Reports

⚠️ Important Rules (For Developers/AI)

🎓 Learning Resources

📝 License

👥 Credits

Development Team

Version Highlights

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages