1. 📞 Customer calls Vonage number (+1-469-414-1700)
2. 🌐 Vonage routes audio via WebSocket to Voice Stream Server
3. 🔀 Voice Stream Server routes to Cartesia AI Agent
4. 👂 Cartesia Ink STT transcribes customer speech
5. 🤖 GROQ LLM (Llama 3.3-70b) processes intent:
   • Router Agent classifies intent (Llama 3.1-8b)
   • Specialized Agent generates response
   • N8N Tools called (slots, booking, etc.)
6. 🗣️ Cartesia Sonic TTS synthesizes response (Blake voice)
7. 🔊 Audio streamed back via WebSocket to customer
8. 📞 Customer hears natural AI voice response

💰 Cost: ~$0.065/minute (Vonage + Cartesia Agent)

.MTMM-variables.json  (Master - Private)
         │
         ▼ sync-web-variables.js
         │
.MTMM-web-variables.json  (Public-safe)
         │
         ▼ deploy.sh --sync-only
         │
┌────────┴────────┐
▼                 ▼
site-config.json  site-config.json
(Main Website)    (Team Portal)

{
  summary: "🔧 [Service] - [Customer Name]",
  description: [
    "📞 Phone: +1-xxx-xxx-xxxx",
    "🚗 Vehicle: 2018 Toyota Camry",
    "🔧 Service: Oil Change",
    "💰 Estimate: $75",
    "📍 Location: 123 Main St, Dallas TX",
    "📋 Notes: Customer notes..."
  ],
  start: { dateTime, timeZone },
  end: { dateTime, timeZone },
  location: "Customer address"
}

# Full deployment (config sync + file transfer)
cd vps-hosting && ./deploy.sh

# Sync config only (fast update)
./deploy.sh --sync-only

# Deploy N8N workflows
node deploy-n8n-workflows.js

# Deploy specific workflow
node deploy-assistant-workflow.js

1. 🔄 Run sync-web-variables.js
   └─ Generates .MTMM-web-variables.json

2. 📤 rsync to VPS
   └─ /opt/websites/sites/markthemobilemechanic.com/

3. 📋 Copy site-config.json
   └─ To main site and team portal

4. ✅ Verify deployment
   └─ Check file timestamps on VPS

Thanks for choosing Mark The Mobile Mechanic! 🔧

Your [SERVICE] is complete.
Total: $[AMOUNT]

⭐ Rate your experience:
[RATING_LINK]

Questions? Reply to this message or call +1-469-414-1700

https://markthemobilemechanic.optimus.systems/rate?
  job=[JOB_ID]
  &token=[SECURE_TOKEN]
  &mechanic=[MECHANIC_ID]

Example:
https://markthemobilemechanic.optimus.systems/rate?job=apt_123abc&token=xyz789&mechanic=m_barry

{
  "customerName": "John Smith",
  "customerPhone": "+1-555-123-4567",
  "customerEmail": "john@example.com",
  "vehicleYear": "2020",
  "vehicleMake": "Toyota",
  "vehicleModel": "Camry",
  "vin": "1HGBH41JXMN109186",
  "serviceAddress": "123 Main St, Dallas, TX 75201",
  "serviceId": "oil_change_standard",
  "requestedDate": "2025-01-15",
  "requestedTime": "10:00",
  "notes": "Gate code: 1234"
}

📊 SLOT AVAILABILITY CALCULATION

Business Hours: 8:00 AM - 6:00 PM (configurable)
Slot Duration: Based on service labor hours

For each mechanic:
  1. Fetch Google Calendar events for date
  2. Generate all possible slots in business hours
  3. Remove slots that overlap with:
     - Existing appointments
     - Buffer time (15 min before/after)
     - Blocked time (lunch, breaks)
  
  4. Apply dispatch constraints:
     - Service radius from customer location
     - Mechanic skills match service requirements
     - Mechanic active status

  5. Return merged available slots across all mechanics

📥 CUSTOMER REPLY KEYWORDS

"CONFIRM" / "YES" / "OK"
  └─ Mark appointment as confirmed
  └─ Reply: "Thank you! Your appointment is confirmed."

"CANCEL" / "STOP"
  └─ Initiate cancellation workflow
  └─ Reply: "Your appointment has been cancelled."

"RESCHEDULE" / "CHANGE"
  └─ Send booking link
  └─ Reply: "To reschedule, visit: [BOOKING_LINK]"

"HELP" / "?"
  └─ Reply: "Call us at +1-469-414-1700 or visit markthemobilemechanic.com"

"RUNNING LATE"
  └─ Log delay notification
  └─ Forward to assigned mechanic

📥 MECHANIC REPLY KEYWORDS

"OK" / "CONFIRMED"
  └─ Mark job as acknowledged

"EN ROUTE" / "OTW"
  └─ Trigger customer "mechanic en route" SMS
  └─ Update job status to "in_transit"

"ARRIVED"
  └─ Update job status to "in_progress"

"DONE" / "COMPLETE"
  └─ Trigger completion workflow

🗺️ POSITION DETECTION ALGORITHM

┌─────────────────────────────────────────────────────────────────┐
│  For accurate distance calculations, the system determines      │
│  where each mechanic will be at the requested appointment time  │
└─────────────────────────────────────────────────────────────────┘

Priority 1: CURRENT APPOINTMENT LOCATION
├── Check: Is mechanic at a job during/before requested time?
├── Use: That job's service address
└── Why: Most accurate for same-day scheduling

Priority 2: PREVIOUS APPOINTMENT LOCATION  
├── Check: Most recent completed appointment
├── Use: That job's service address
└── Why: Mechanic may still be in that area

Priority 3: BASE LOCATION (fallback)
├── Use: Mechanic's configured home/shop address
└── Why: Default starting point for new days

📊 EXAMPLE SCENARIO
────────────────────
Request: 2:00 PM appointment in Plano

Mechanic A:
  └─ Has 11:00 AM job in Frisco (15 min away)
  └─ Position used: Frisco address ✓

Mechanic B:  
  └─ No appointments today
  └─ Position used: Base location (Haslet) ✓

🎯 ROUTE CLUSTERING BONUS

When appointments are geographically clustered, mechanics receive
bonus points to encourage efficient routing:

┌─────────────────────────────────────────────────────────────────┐
│  Distance to Next Job    │  Clustering Bonus Points            │
├─────────────────────────────────────────────────────────────────┤
│  < 5 miles               │  +20 points                         │
│  5-10 miles              │  +15 points                         │
│  10-15 miles             │  +10 points                         │
│  15-20 miles             │  +5 points                          │
│  > 20 miles              │  No bonus                           │
└─────────────────────────────────────────────────────────────────┘

📈 REAL-WORLD IMPACT
────────────────────
Before clustering optimization:
  └─ Average deadhead miles: 45 miles/day
  
After clustering optimization:
  └─ Average deadhead miles: 28 miles/day
  └─ 🎉 38% reduction in non-billable driving!

💡 EXAMPLE CALCULATION
────────────────────────
Scenario: 2:00 PM oil change in Plano

Mechanic A (in Frisco):
  Base Score: 75
  Distance: 8 miles
  Cluster Bonus: +15 (within 10 miles of their next job)
  FINAL: 90 ✅ SELECTED

Mechanic B (in Fort Worth):
  Base Score: 82
  Distance: 32 miles  
  Cluster Bonus: +0
  FINAL: 82

// Hybrid Intelligent Strategy (default)
function calculateScore(mechanic, appointment) {
  const weights = {
    distance: 0.40,
    workload: 0.35,
    skills: 0.25
  };
  
  // Distance Score (0-100, closer = higher)
  const distanceScore = Math.max(0, 100 - (distance * 2));
  
  // Workload Score (0-100, fewer jobs = higher)
  const maxJobs = 8; // Daily capacity
  const workloadScore = ((maxJobs - todayJobs) / maxJobs) * 100;
  
  // Skills Score (0-100)
  const skillsScore = mechanic.skills.includes(service.category) 
    ? 100 : 60; // Penalty for non-specialist
  
  // Efficiency Multiplier
  const efficiencyMultiplier = mechanic.efficiency || 1.0;
  
  // Route Clustering Bonus
  const clusterBonus = calculateClusterBonus(mechanic, appointment);
  
  // Final Score
  const baseScore = (
    (distanceScore * weights.distance) +
    (workloadScore * weights.workload) +
    (skillsScore * weights.skills)
  ) * efficiencyMultiplier;
  
  return baseScore + clusterBonus;
}