fitness/DEPLOYMENT_GUIDE.md

Fitness Tracking App - Production Deployment Guide

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Flutter Mobile App                        │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │         GetX Controller (State Management)              │ │
│  │  - WorkoutController: Orchestrates tracking logic      │ │
│  │  - LocationService: SQLite background storage         │ │
│  └─────────────────────────────────────────────────────────┘ │
│                           │                                   │
│  ┌─────────────────────────┴──────────────────────────────┐ │
│  │         Views & UI Components                          │ │
│  │  - WorkoutTrackingScreen: MapLibre map + stats       │ │
│  │  - Real-time GPS overlay on MapLibre                 │ │
│  │  - Polyline encoding for route submission            │ │
│  └─────────────────────────────────────────────────────────┘ │
│                           │                                   │
│         ┌─────────────────┴──────────────────┐               │
│         │  HMAC-SHA256 Signature Generator  │               │
│         └─────────────────┬──────────────────┘               │
│                           ▼                                   │
└───────────────────────────────────────────────────────────────┘
                           │ HTTPS
                           │ HMAC-SHA256 Authenticated
                           ▼
┌───────────────────────────────────────────────────────────────┐
│              PHP Backend (REST API)                            │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  Authentication Layer                                  │  │
│  │  - HMAC-SHA256 Signature Verification                 │  │
│  │  - Timestamp Validation (Replay Attack Prevention)    │  │
│  │  - Rate Limiting & API Key Management                │  │
│  └─────────────────────────────────────────────────────────┘  │
│                           │                                   │
│  ┌─────────────────────────┴──────────────────────────────┐  │
│  │  /api/v1/workouts (POST)                              │  │
│  │  - WorkoutValidator: Validates payload structure      │  │
│  │  - PolylineUtility: Decodes & validates routes       │  │
│  │  - Database: Stores workouts & coordinates          │  │
│  └─────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌───────────────────────────────────────────────────────────────┐
│              MySQL Database                                    │
│  ┌──────────────┐  ┌─────────────┐  ┌──────────────────┐    │
│  │  users       │  │  workouts   │  │  api_logs        │    │
│  │  - id        │  │  - id       │  │  - user_id       │    │
│  │  - api_key   │  │  - distance │  │  - endpoint      │    │
│  │  - api_secret│  │  - polyline │  │  - status_code   │    │
│  └──────────────┘  │  - duration │  └──────────────────┘    │
│                    │  - calories │                            │
│                    │  - metadata │                            │
│                    └─────────────┘                            │
└───────────────────────────────────────────────────────────────┘

Backend Setup Instructions

1. Database Initialization

# Connect to MySQL server
mysql -u root -p

# Execute the schema creation
source backend/schema.sql

# Verify tables were created
USE fitness_app;
SHOW TABLES;

2. Database User Configuration

-- Create dedicated database user
CREATE USER 'fitness_app_user'@'localhost' IDENTIFIED BY 'your_secure_password_here';

-- Grant privileges
GRANT SELECT, INSERT, UPDATE, DELETE ON fitness_app.* TO 'fitness_app_user'@'localhost';
GRANT CREATE, ALTER ON fitness_app.* TO 'fitness_app_user'@'localhost';
FLUSH PRIVILEGES;

3. Update PHP Configuration

Edit backend/Database.php:

private $db_host = 'your-db-host.com';
private $db_user = 'fitness_app_user';
private $db_pass = 'your_secure_password_here';
private $db_name = 'fitness_app';
private $db_port = 3306;

4. Deploy PHP Files

# Copy PHP files to web server
cp backend/*.php /var/www/html/api/v1/

# Set permissions
chmod 644 /var/www/html/api/v1/*.php
chown www-data:www-data /var/www/html/api/v1/

5. Configure Web Server (Apache or Nginx)

Apache (.htaccess)

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /api/v1/
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)$ index.php?url=$1 [QSA,L]
</IfModule>

# Enable HTTPS only
<VirtualHost *:443>
    SSLEngine on
    SSLCertificateFile /path/to/cert.crt
    SSLCertificateKeyFile /path/to/key.key
    # ... additional SSL config
</VirtualHost>

Nginx

server {
    listen 443 ssl http2;
    server_name api.fitness-app.com;

    ssl_certificate /path/to/cert.crt;
    ssl_certificate_key /path/to/key.key;
    ssl_protocols TLSv1.2 TLSv1.3;

    location /api/v1/ {
        try_files $uri $uri/ @rewrite;
    }

    location @rewrite {
        rewrite ^/api/v1/(.*)$ /api/v1/index.php?url=$1 last;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

Mobile Setup Instructions

1. Flutter Project Setup

# Create Flutter project
flutter create fitness_tracker

# Navigate to project
cd fitness_tracker

# Replace pubspec.yaml
cp mobile/pubspec.yaml ./

# Get dependencies
flutter pub get

2. Install Dependencies

# All dependencies are specified in pubspec.yaml
flutter pub get

# For iOS
cd ios && pod install && cd ..

# For Android - ensure minimum SDK is 21
# Check android/app/build.gradle:
# minSdkVersion 21
# targetSdkVersion 34

3. Set MapLibre Tile Server

Update mobile/workout_tracking_screen.dart:

MapLibreMap(
    styleString: 'https://map-saas.intaleqapp.com/styles/basic-preview/style.json',
    // ...
)

4. Configure Native Permissions

iOS (ios/Runner/Info.plist)

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs location access to track your workouts</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs location access to track your workouts</string>
<key>NSMotionUsageDescription</key>
<string>This app needs motion data to enhance workout tracking</string>

Android (android/app/src/main/AndroidManifest.xml)

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.INTERNET" />

<service
    android:name=".LocationService"
    android:foregroundServiceType="location"
    android:enabled="true"
    android:exported="true" />

5. Generate API Credentials for Testing

# On server, generate test credentials
php -r "
require 'backend/AuthenticationHandler.php';
\$creds = AuthenticationHandler::generateApiCredentials();
echo 'API Key: ' . \$creds['api_key'] . PHP_EOL;
echo 'API Secret: ' . \$creds['api_secret'] . PHP_EOL;
"

Insert into database:

INSERT INTO users (uuid, username, email, password_hash, api_key, api_secret, full_name, is_active)
VALUES (
    UUID(),
    'testuser',
    'test@example.com',
    '$2y$12$...',  -- bcrypt hash of password
    'your_generated_api_key',
    'your_generated_api_secret',
    'Test User',
    TRUE
);

6. Test API Endpoint

#!/bin/bash

API_KEY="your_api_key"
API_SECRET="your_api_secret"
TIMESTAMP=$(date +%s)
ENDPOINT="https://your-api.com/api/v1/workouts"

PAYLOAD='{
  "workout_type": "running",
  "distance_meters": 5000,
  "duration_seconds": 1800,
  "elevation_gain_meters": 150,
  "elevation_loss_meters": 100,
  "calories_burned": 350,
  "max_speed_mps": 4.5,
  "route_polyline": "abc123def456",
  "start_time": "2026-04-21T10:00:00Z",
  "end_time": "2026-04-21T10:30:00Z",
  "weather_condition": "sunny",
  "temperature_celsius": 22.5,
  "notes": "Great run!",
  "is_public": false
}'

MESSAGE="${TIMESTAMP}|${API_KEY}|${PAYLOAD}"
SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $NF}')

curl -X POST "$ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -d "$PAYLOAD"

Security Checklist

• HTTPS/TLS 1.2+ enforced on all endpoints
• HMAC-SHA256 signatures verified on every request
• Timestamp validation (5-minute window) prevents replay attacks
• Passwords hashed with bcrypt (cost=12)
• API secrets stored securely (never logged)
• Database credentials not in version control
• Flutter app uses flutter_secure_storage for credentials
• Rate limiting implemented per API key
• SQL injection prevented via prepared statements
• CORS properly configured for cross-origin requests
• Input validation on all endpoints
• Error messages don't leak sensitive information
• Regular security audits scheduled
• Audit logs maintained in api_logs table
• API keys rotated periodically

Performance Optimization

Database Indexes

All critical queries have indexes:

• users(api_key) - API authentication
• workouts(user_id, created_at) - User workout history
• api_logs(user_id, created_at) - Audit logging

Caching Strategy

• User stats cached in user_stats_cache table
• Cache invalidated on new workout submission
• Consider Redis for high-traffic scenarios

Mobile Optimization

• GPS coordinates batched before SQLite insertion
• Polyline encoding reduces payload size by ~75%
• Map updates throttled to prevent UI jank
• Background location updates configurable

Monitoring & Analytics

Key Metrics to Track

1. API Performance

   • Average response time per endpoint
   • 95th percentile latency
   • Request volume and patterns

2. User Activity

   • Active users (DAU/MAU)
   • Workouts submitted per day
   • Average workout distance/duration

3. System Health

   • Database connection pool status
   • Server CPU/memory usage
   • Error rate and types

Logging

• All API requests logged in api_logs table
• Failed authentication attempts tracked
• Unusual access patterns monitored

Deployment Checklist

Pre-Deployment

• All tests passing
• Code review completed
• Security scan completed
• Performance tested under load
• Backup strategy in place
• Rollback plan documented

Deployment

• Database migrations executed
• PHP files deployed and tested
• SSL certificates valid
• API credentials generated
• Monitoring configured
• Alerts set up

Post-Deployment

• Smoke tests passed
• API response times acceptable
• Database queries optimized
• Logs reviewed for errors
• Metrics collected and analyzed

Troubleshooting

Common Issues

Invalid Signature Error

• Verify API key and secret are correct
• Check timestamp is within 5 minutes
• Ensure payload JSON is not modified after signing
• Verify HMAC algorithm is SHA256

Database Connection Error

• Check MySQL server is running
• Verify credentials in Database.php
• Ensure firewall allows connection
• Check max_connections limit

Location Tracking Not Working

• Verify location permissions on device
• Check GPS is enabled
• Ensure app has foreground/background permission
• Check location_service package initialization

Map Not Displaying

• Verify MapLibre tile server is accessible
• Check API key for tile server
• Ensure device has internet connection
• Verify style JSON URL is correct

Scaling Considerations

For production deployments with 100k+ users:

1. Database

   • Implement read replicas for analytics queries
   • Archive old workout data to separate table
   • Implement partitioning by user_id

2. API Server

   • Deploy multiple PHP instances behind load balancer
   • Implement API gateway with rate limiting
   • Use CDN for static assets

3. Caching

   • Implement Redis for session/stats caching
   • Cache user stats for 1 hour
   • Cache API responses for 5 minutes

4. Background Jobs

   • Use queue system for async processing
   • Recalculate user stats in background
   • Generate reports/analytics offline

Support & Maintenance

Regular Maintenance Tasks

• Monitor API logs for errors
• Review security audit logs
• Update dependencies monthly
• Performance tuning as needed
• Database optimization (ANALYZE/OPTIMIZE)
• Backup verification

Contact

For issues or questions, contact: support@fitness-app.com