SmartRunning Training Optimization Platform

Full-stack application for managing running training plans. The platform tracks performance metrics, analyzes training sessions, and generates training plans based on physiological models.

Features

Core Functionality

Authentication & Authorization: Role-based access control with Admin, Coach, and Runner roles
Runner Management: Create, update, and manage athlete profiles with detailed physiological parameters
Onboarding Workflow: 4-step wizard for new runners to complete their profile
Session Processing: Upload and analyze FIT files from Garmin devices and other fitness trackers
Performance Analytics: Calculate training metrics using physiological models
Performance Analysis: Calculate running performance metrics from personal best times
Heart Rate Zone Calculation: Automatic calculation of training zones using HUNT formula based on age
Training Plan Generation: Automated creation of personalized training plans based on athlete metrics
Workout Library: Manage ZWO workout files for structured training sessions
Historical Analysis: Track performance trends and personal records over time
Performance Trends Visualization: Interactive charts showing PB progression and performance metrics evolution with time-series data

Key Components

Session statistics calculation (pace, heart rate zones, efficiency metrics)
Automated personal best tracking across multiple distances
Performance metric calculation using regression analysis
Automatic performance calculation on profile creation with default values
Heart rate zone calculation using HUNT formula
Intelligent zone assignment with customizable percentages
Training load modeling using physiological stress scoring
Multi-block periodized training plan structure
Support for batch file processing (FIT and ZIP files)
Admin dashboard for workout and training plan management
Centralized runner creation service ensuring consistent default values across all entry points
Time-series data storage for PBs, Heart Rate Zones, and performance metrics with historical tracking
Chronological session processing with automatic PB detection and performance recalculation
Period-appropriate statistics calculation using values valid at session date

Technologies

Backend: Flask 3.0.0, Python 3.11-3.13, MongoDB with GridFS Frontend: HTML5/CSS3, JavaScript, Bootstrap, Chart.js Data Processing: Pandas, NumPy, SciPy, scikit-learn, PyArrow, Custom Garmin FIT SDK Infrastructure: Docker, Kubernetes, Google Cloud Platform

For detailed technology stack and version information, see Architecture.

Prerequisites

Docker and Docker Compose installed
MongoDB Atlas account or local MongoDB instance
Python 3.11-3.13 (for local development only)

Installation

Using Docker (Recommended)

Configure environment variables (repository should already be cloned):

cp .env.example .env
# Edit .env with your MongoDB connection string

Build and start the containers:

docker-compose up --build

Run migrations to create users collection:

docker exec -it running-app python -m app.migrations.001_create_users_collection up

Access the application:

Main application: http://localhost:[port]
Login page: http://localhost:[port]/auth/login
Admin dashboard: http://localhost:[port]/admin (requires admin role)

First-time setup: After running migrations, an initial admin user is created:

Username: admin
Password: changeme
Important: Change this password immediately after first login

Local Development (Without Docker)

Create virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Set environment variables:

export FLASK_APP=app.py
export FLASK_ENV=development
# Or use .env file with python-dotenv

Run the application:

python app.py

Kubernetes Deployment (Production)

The application includes Kubernetes deployment configurations for Google Cloud Platform:

Prerequisites:
- Google Cloud Platform account with billing enabled
- gcloud CLI tool installed and configured
- kubectl configured to access your GKE cluster
- Docker image built and pushed to Google Artifact Registry
- SSL/TLS support automatically configured via included certificates

Build and push Docker image:

# Build the image
docker build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG .

# Configure Docker for Artifact Registry
gcloud auth configure-docker LOCATION-docker.pkg.dev

# Push the image
docker push LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG

Deploy to Kubernetes:

# Update kustomization.yaml with your image details
# Apply the Kubernetes resources
kubectl apply -k .

# Check deployment status
kubectl get pods
kubectl get services

Access the application:

# Get the external IP address
kubectl get service smartrunning-localapp-service
# Access via: http://EXTERNAL-IP:[port]

Project Structure

localApp/
├── app/                          # Core application module
│   ├── __init__.py              # Flask app factory
│   ├── config.py                # Configuration settings
│   ├── database.py              # MongoDB connection and operations
│   ├── models.py                # Data models
│   ├── routes.py                # API endpoints and routes
│   ├── defaults.py              # Default values for runners
│   ├── file_processor.py        # FIT file processing logic
│   ├── statistics_processor.py  # Session statistics calculation
│   ├── runner_history_processor.py # Historical metrics tracking
│   ├── training_plan_generator.py  # Training plan creation
│   ├── heart_rate_calculator.py # Heart rate zone calculation using HUNT formula
│   ├── job_manager.py           # Background job handling
│   ├── session_statistics.py    # Detailed session analysis
│   ├── generate_training_plan.py # Standalone plan generation script
│   ├── fit_to_parquet_converter.py # File conversion utility
│   ├── upload_zwo_workouts.py   # Bulk workout upload script
│   └── load_defaults.py         # Default values utility script
├── garmin_fit_sdk/              # Custom Garmin FIT file parser
│   ├── decoder.py               # FIT file decoding
│   ├── profile.py               # FIT profile definitions
│   └── ...                      # Additional SDK components
├── templates/                   # HTML templates
│   ├── base.html               # Base template
│   ├── index.html              # Main application page
│   ├── admin.html              # Admin dashboard
│   └── training_plan_view.html # Training plan viewer
├── static/                      # Static assets
│   ├── css/                    # Stylesheets
│   └── js/                     # JavaScript files
├── data/                        # Data storage
│   └── uploads/                # Temporary file uploads
├── documentation/               # Project documentation
│   ├── README.md               # This file
│   ├── ARCHITECTURE.md         # System architecture
│   ├── DEFAULT_VALUES.md       # Default configuration guide
│   └── SESSION_UPLOAD.md       # Session upload guide
├── Dockerfile                   # Docker container with SSL/TLS support
├── docker-compose.yml          # Multi-container setup
├── deployment.yml              # Kubernetes deployment configuration
├── service.yml                 # Kubernetes service configuration
├── kustomization.yaml          # Kustomize configuration for K8s
├── requirements.txt            # Python dependencies
├── .env.example               # Environment variables template
└── app.py                     # Application entry point

Configuration

Environment Variables

Configuration is managed through app/config.py using environment variables from .env:

# MongoDB Configuration
MONGO_CONNECTION_STRING=mongodb+srv://username:password@cluster.mongodb.net/
DATABASE_NAME=your_database

# Application Configuration
FLASK_ENV=development
FLASK_APP=app.py
SECRET_KEY=your-secret-key

# Upload Configuration
MAX_CONTENT_LENGTH=16777216  # 16MB
UPLOAD_FOLDER=/app/data/uploads

# Data Validation
MIN_VALID_HR=30
MAX_VALID_HR=220
MIN_VALID_SPEED=0
MIN_PACE_CALCULATION_SPEED=0.5

Default Runner Configuration

Default values for new runners are defined in app/defaults.py:

Physiological model parameters
Training load parameters
Schedule configuration (blocks, weeks, training days)
Heart rate zones

Usage

User Roles & Access

The application supports three user roles with different access levels:

Role	Login Required	Access
Admin	Yes	Full access: User management, all runners, admin dashboard, workout library
Coach	Yes	Assigned runners, can create new athletes, limited admin dashboard access
Runner	Yes	Own profile only (auto-navigates to personal view), no Athletes Dashboard access

Note: Users can have multiple roles. A user with both Coach and Runner roles will have Coach-level access.

Getting Started

For Admins:

Log in with admin credentials
Access Athletes Dashboard to view all runners
Create user accounts via User Management
Assign runners to coaches as needed
Manage workout library and training plan schemas

For Coaches:

Log in with coach credentials
Access Athletes Dashboard to view assigned runners
Create new athletes using "Add New Athlete" wizard
Optionally create user accounts for athletes (Step 5)
Upload sessions and manage training plans for assigned athletes
Access limited Admin Dashboard (Workouts and Training Plan Schemas only)

For Runners:

Log in with runner credentials (created by admin or coach)
Auto-navigated directly to personal training view (no Athletes Dashboard access)
Complete 4-step onboarding wizard on first login:
- Basic Info (name, age)
- Heart Rate Zones (automatic calculation available)
- Personal Bests (multiple distances with performance metrics)
- Training Parameters (physiological model parameters)
View personal training data, sessions, history, and training plans
Cannot create or manage other athletes

Workflow Examples

Creating a New Athlete (Coach perspective):

Navigate to main page
Click "Add New Athlete"
Complete 4-step wizard with athlete details
Optionally create user account (Step 5) for athlete self-service
Upload sessions and manage training

First-Time Runner Login:

Log in with provided credentials
Complete onboarding wizard (4 steps)
View personal dashboard and training history

Uploading Training Sessions:

Select a runner from the list
Upload FIT files or ZIP archives containing FIT files
System automatically processes and extracts metrics

Generating Training Plans:

Select a runner
Choose a training plan schema
Configure parameters (marathon date, preparation weeks)
Generate personalized plan

For detailed algorithm explanation, see Training Algorithm.

Admin Dashboard

Access at /admin for:

Workout library management
Training plan schema editing
Bulk workout uploads
System monitoring

API Documentation

Key Endpoints

Runners

GET /runners - List all runners
GET /runners/<id> - Get runner details
POST /runners - Create new runner
PUT /runners/<id> - Update runner
DELETE /runners/<id> - Delete runner

Sessions

POST /runners/<id>/sessions - Upload session files
GET /runners/<id>/sessions - List runner sessions
DELETE /runners/<id>/sessions - Delete sessions
POST /runners/<id>/sessions/analyze - Analyze sessions

Training Plans

GET /training-schemas - List available schemas
POST /runners/<id>/training-plans/generate - Generate plan
GET /runners/<id>/training-plans - List runner plans

Workouts

GET /api/workouts - List workouts
POST /api/workouts - Create workout
PUT /api/workouts/<id> - Update workout
DELETE /api/workouts/<id> - Delete workout

Database Schema

The database uses 11 MongoDB collections for storing training data. For complete schema documentation including field definitions, relationships, and query patterns, see Database Schema.

Key Collections:

runner - Athlete profiles with physiological parameters (38 fields)
sessionsFIT - Raw FIT file data and metadata
sessionsParquet - Processed session records in Parquet format
sessionStatistics - Aggregated session metrics (65 fields)
runnerHistory - Daily training load progression metrics
trainingplan - Training plan days (one document per day, flat structure)
trainingplanschema - Training plan templates (nested blocks/workouts)
workouts - Workout library
background_jobs - Async job tracking
fs.files, fs.chunks - GridFS binary file storage

For training plan generation details, see Training Algorithm.

Development

Running Tests

# Inside container
docker-compose exec web python -m pytest tests/

# Local environment
pytest tests/

Database Operations

Utility scripts in the app/ folder can handle data operations and migrations.

Multi-Environment Deployment

Thanks to the centralized configuration system, you can easily deploy to different environments by changing only the .env file:

# Development
MONGO_CONNECTION_STRING=mongodb://localhost:27017
DATABASE_NAME=your_database_dev

# Staging
MONGO_CONNECTION_STRING=mongodb+srv://user:pass@staging-cluster.mongodb.net/
DATABASE_NAME=your_database_staging

# Production
MONGO_CONNECTION_STRING=mongodb+srv://user:pass@prod-cluster.mongodb.net/
DATABASE_NAME=your_database_prod

No code changes required - just environment variables!

Code Style

PEP 8 compliance for Python code
ESLint for JavaScript
Consistent naming conventions

Troubleshooting

For common issues and solutions, see the Troubleshooting Guide.

For MongoDB-specific connection issues (IP whitelisting, SSL/TLS), see the MongoDB Setup Guide.

Features​

Core Functionality​

Key Components​

Technologies​

Prerequisites​

Installation​

Using Docker (Recommended)​

Local Development (Without Docker)​

Kubernetes Deployment (Production)​

Project Structure​

Configuration​

Environment Variables​

Default Runner Configuration​

Usage​

User Roles & Access​

Getting Started​

Workflow Examples​

Admin Dashboard​

API Documentation​

Key Endpoints​

Runners​

Sessions​

Training Plans​

Workouts​

Database Schema​

Development​

Running Tests​

Database Operations​

Multi-Environment Deployment​

Code Style​

Troubleshooting​