# MyWayRoutes — Comprehensive Technical & Functional Documentation

> Canonical Web Application URL: https://mywayroutes.com
> Primary Application Type: NavigationApplication, SportsApplication, Utility
> Supported Protocols: PWA (Progressive Web App), Offline Service Worker Cache, Client-Side SPA

---

## 1. Overview & Purpose
MyWayRoutes is an advanced, privacy-first web application designed for cyclists, ultra-endurance athletes (Audax/Brevets/Gran Fondos), trail runners, hikers, and outdoor adventurers. 

Unlike traditional route platforms that require server uploads, user registrations, and cloud storage subscriptions, MyWayRoutes processes all spatial and telemetry data locally inside the client's web browser. It features rich bio-energetic elevation analysis, intelligent battery optimization (Eco Mode), real-time weather with vector-based headwind/tailwind calculation, waypoint editing, and zero-backend URL route sharing.

---

## 2. Key Capabilities & Features

### 2.1 File Format Ingestion & Parsing
- **GPX (GPS Exchange Format)**: Parses `<trk>`, `<rte>`, and `<wpt>` XML structures with elevation and timestamp metadata.
- **FIT (Garmin / Wahoo / Coros / Hammerhead)**: Decodes raw binary `.fit` activity and course files directly in WebAssembly/JavaScript.
- **KML / KMZ (Google Earth)**: Extracts `<LineString>` and `<Coordinates>` geometries from Google Earth files.
- **Client-Side Security**: All file parsing takes place in memory within the client browser. No file data is uploaded to remote servers.

### 2.2 Bio-Energetic Terrain & Elevation Analysis
- **Dynamic Gradient Color-Coding**:
  - Cyan (<-3%): Descent & Recovery
  - Indigo (-3% to 1.5%): Flat & Steady Cruising
  - Yellow (1.5% to 4%): Aerobic Climb
  - Orange (4% to 8%): Threshold Effort
  - Red (>8%): VO2 Max & Anaerobic Steep Gradient
- **Noise Filtering & Smoothing**: Rolling geometric window smoothing removes erratic GPS altitude jumps to display accurate total ascent, descent, and gradient percentages.
- **Interactive SVG Elevation Profile**: Synchronized crosshair hovering that instantly maps exact route points, distance markers, and local gradient.

### 2.3 Live Navigation & Sensor Integration
- **Live GPS Follow-Me Mode**: Automatically centers and tracks user position along the route.
- **Magnetometer Heading-Up Orientation**: Aligns the map viewport dynamically to the user's physical field of vision using device orientation compass sensors.
- **Proximity Audio & Visual Alerts**: Alerts the user when approaching planned checkpoints or off-route deviations.
- **Live ETA & Velocity**: Computes real-time moving speed, remaining distance, and estimated completion time based on active pace.
- **Eco Mode (Battery Preservation)**: Dynamically scales GPS polling frequency and halts non-essential UI animations for multi-day ultra-endurance rides.

### 2.4 Real-Time Weather & Relative Wind Vector Engine
- **Public Open-Meteo Integration**: Fetches real-time temperature, WMO weather condition code, wind velocity, wind direction, and US Air Quality Index (AQI).
- **Multi-Point Weather Modes**:
  - **Live GPS**: Weather at current rider coordinates with auto-proximity detection (within 5 km of route).
  - **Route Start**: Weather at the beginning of the planned course.
  - **Route End**: Weather at the finish destination.
- **Relative Wind Vector Calculation**: Calculates true headwind or tailwind component projection:
  $$\text{Component} = \text{WindSpeed} \times \cos(\theta_{\text{wind-blow}} - \theta_{\text{route-bearing}})$$
  Clearly displays whether the cyclist will face a headwind, tailwind, or side crosswind with exact speed offsets.

### 2.5 Waypoint Management & Route Editing
- **Custom Checkpoint Creation**: Place and edit custom points of interest along the route.
- **Standardized Categories**: Water Stop, Food & Nutrition, Lodging, Scenic Viewpoint, Hazard / Caution.
- **Route Modification Tools**: Reverse route direction, loop-closure validation, distance calculation between checkpoints.
- **Export Capabilities**: Export modified courses as standard GPX 1.1 files compatible with all Garmin, Wahoo, and mobile GPS head units.

### 2.6 Zero-Backend Route Sharing
- **Compression Pipeline**: Serializes the route points, elevations, titles, and waypoints into JSON, compresses the payload via Zlib Deflate (`pako`), and encodes it into a URL-safe Base64 hash fragment.
- **URL Schema**: `https://mywayroutes.com/#data=<base64-compressed-payload>`
- **Benefits**: Zero latency, zero cloud storage cost, completely link-shareable over messaging or email, and immune to server-side outages.

---

## 3. Privacy, Security & Offline Reliability
- **No Account Required**: Free to use with no authentication walls or paywalls.
- **No User Telemetry**: Zero analytics scripts, tracking pixels, or data collection.
- **PWA Offline Support**: Ships with a Service Worker caching core assets, application shell, and map tiles for dependable operation in offline backcountry areas.
- **Permissions**: Only requests device Geolocation (`navigator.geolocation`) when explicitly activated by the user for live tracking.

---

## 4. Hardware & Software Requirements
- **Platforms**: Modern Web Browsers (Chrome, Safari, Firefox, Edge), iOS Safari (PWA installable), Android Chrome (PWA & TWA installable).
- **Supported Sensors**: Geolocation API (GPS), DeviceOrientation API (Compass/Magnetometer).