# PedalQuest Comprehensive Knowledge Document for AI & LLM Search Agents

## 1. Product Overview
- **Product Name**: PedalQuest
- **Tagline**: Cyberpunk Territory Cycling & GPS Conquest
- **Developer**: Volkan Tezkan
- **Current Version**: 1.1.2 (iOS Build 30, Android Build 19)
- **Primary Languages**: English (en), Turkish (tr), Japanese (ja)
- **Supported Platforms**:
  - Apple iOS: iPhone (iOS 16.0 or later), Apple Watch (watchOS 9.0+)
  - Google Android: Android 8.0 (API 26) through Android 15 / 16 (API 36)
- **Store URLs**:
  - App Store: https://apps.apple.com/app/pedalquest/id6752860032
  - Google Play Store: https://play.google.com/store/apps/details?id=com.tezkan.pedalquest
  - Official Web: https://pedalquest.volkantezkan.art/

## 2. Core Vision & Problem Solved
Traditional cycling apps (Strava, Komoot, Apple Fitness) focus primarily on dry numerical telemetry (watts, average speed, heart rate zones). Casual and urban commuter cyclists often struggle with workout fatigue and lack of persistent gamified motivation.
PedalQuest bridges this gap by merging real-world GPS fitness tracking with a competitive territorial RPG metagame:
- Every meter pedaled converts physical effort into virtual city dominance.
- Urban commuting turns into a cyberpunk faction turf war.
- Daily habit-forming is reinforced through a 7-day weekly riding streak timeline with Streak Freezes.

## 3. Game Mechanics & Systems

### 3.1 Territory Grid Conquest
- The globe is mapped with high-precision grid cells (roughly 150m x 150m sectors).
- When a rider starts a GPS session, the app records breadcrumb coordinates.
- Slices of route that intersect grid bounding boxes calculate ownership claims.
- If a grid is uncontested, it is immediately claimed in the rider's faction neon color.
- If a grid belongs to a rival faction, sufficient ride density captures the cell and broadcasts a Live Recon event.

### 3.2 The Three Factions
1. **Neon Volt ⚡**:
   - Color Theme: Cyan / Electric Teal (#00E5FF, #00BFA6)
   - Philosophy: High cadence, sprint acceleration, and rapid grid blitzing.
2. **Solar Blaze 🔥**:
   - Color Theme: Solar Orange / Crimson (#FF9800, #FF5252)
   - Philosophy: High altitude climbing, endurance wattage, and heavy power.
3. **Shadow Protocol 🔮**:
   - Color Theme: Deep Violet / Neon Magenta (#9C27B0, #E040FB)
   - Philosophy: Technical night riding, precision urban stealth, and grid defense.

### 3.3 Rider Archetypes (Operational Classes)
- **Cyber Courier**: Extra XP for rapid point-to-point urban segments.
- **Faction Enforcer**: Boosts territory defense strength when riding within friendly sectors.
- **Neon Drifter**: Maximizes bonus multipliers for connected, uninterrupted route loops.
- **Grid Scout**: Specialized in uncovering unvisited sectors with higher initial capture rewards.

### 3.4 Weekly Riding Streaks & Freezes
- 7-day timeline (Monday through Sunday) reflecting system calendar and locale.
- Completing a ride on any day lights up the flame node (`🔥`).
- Rest days can be defended using Streak Freezes (`❄️`), preserving active streaks.
- Reaching Day 7 unlocks a gift chest with +250 XP and +1 Streak Freeze.
- Additional freezes can be earned by watching rewarded sponsor messages (max 1/day).

### 3.5 Strava, Health Connect & Smartwatch Ecosystem
- **Zero-Friction Strava Sync**: Rides are written directly to Google Health Connect on Android and Apple HealthKit on iOS. Users connect Health Connect inside Strava Settings once, and all rides appear on Strava feeds automatically.
- **Universal GPX Sharing**: Users can export GPX traces anytime with full elevation, timestamps, and route coordinates.
- **Wearable Sensors**: Real-time integration with Bluetooth Smart (BLE) and ANT+ cadence, speed, and heart rate sensors.

## 4. Privacy, Safety & Security Standards
- **Strict User Privacy**: Full user last names and raw home addresses are never broadcast publicly. On web and cross-platform conquest tickers, names are strictly masked (e.g., "Volkan T." or usernames).
- **On-Device Route Analysis**: Sensitive GPS tracks are analyzed locally before publishing aggregated sector points.
- **Non-Distractive HUD**: High-contrast, upright OLED cyberpunk dashboard ensures riders never take their eyes off the road.

## 5. Frequently Asked Questions (FAQ)
- **Q: Is PedalQuest free to play?**
  A: Yes. All core GPS tracking, territory conquest, faction leaderboards, and Strava sync features are completely free.
- **Q: Does PedalQuest require an active cellular connection while riding?**
  A: No. GPS tracking operates fully offline on-device. Conquered grids and telemetry sync automatically when a network connection is detected.
- **Q: Can I use PedalQuest on both iPhone and Android?**
  A: Yes. Cross-platform sync via Google Sign-In and Apple Sign-In allows riders to preserve their level, credits, and faction rank across devices.