Implementation Guide: Transcribe service advisor walkarounds and generate repair order drafts for technician review

netspot --survey --export heatmap_service_lane.pdf

# SSH into UniFi Cloud Gateway or access via https://unifi.ui.com
# Create VLAN 20 for IoT/Capture devices
# Network > Settings > Networks > Create New:
#   Name: AI-Capture
#   VLAN ID: 20
#   Gateway/Subnet: 192.168.20.1/24
#   DHCP Range: 192.168.20.10 - 192.168.20.50

# Create SSID:
# WiFi > Create New:
#   Name: ShopName-AI-Capture
#   Security: WPA3-Personal
#   Password: [generate 20+ char password]
#   Network: AI-Capture (VLAN 20)
#   Band: 5 GHz preferred (force 5GHz if all tablets support it)
#   Minimum RSSI: -75 dBm

# Firewall rule — allow VLAN 20 outbound to internet (for API calls)
# Block VLAN 20 to VLAN 10 (isolate from DMS network)
# Settings > Firewall > Rules > Create:
#   Type: LAN In
#   Source: VLAN 20 (192.168.20.0/24)
#   Destination: VLAN 10 (192.168.10.0/24)
#   Action: Drop

-- Connect to Supabase SQL Editor and run:

-- Advisors table
CREATE TABLE advisors (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL,
  pin TEXT, -- optional 4-digit PIN for tablet login
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMPTZ DEFAULT now()
};

-- Walkarounds table (one per customer interaction)
CREATE TABLE walkarounds (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  advisor_id UUID REFERENCES advisors(id) NOT NULL,
  customer_name TEXT,
  vehicle_vin TEXT,
  vehicle_year INTEGER,
  vehicle_make TEXT,
  vehicle_model TEXT,
  vehicle_mileage INTEGER,
  audio_storage_path TEXT, -- Supabase Storage path
  audio_duration_seconds INTEGER,
  recording_started_at TIMESTAMPTZ,
  recording_ended_at TIMESTAMPTZ,
  consent_obtained BOOLEAN DEFAULT false,
  status TEXT DEFAULT 'recording' CHECK (status IN ('recording','transcribing','drafting','review','approved','rejected','pushed_to_dms')),
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now()
};

-- Transcripts table
CREATE TABLE transcripts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  walkaround_id UUID REFERENCES walkarounds(id) NOT NULL,
  raw_transcript JSONB NOT NULL, -- full Deepgram response with diarization
  formatted_text TEXT NOT NULL, -- human-readable transcript
  speaker_labels JSONB, -- mapping of speaker IDs to roles (advisor/customer)
  confidence_score NUMERIC(4,3),
  created_at TIMESTAMPTZ DEFAULT now()
};

-- Draft repair orders table
CREATE TABLE draft_repair_orders (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  walkaround_id UUID REFERENCES walkarounds(id) NOT NULL,
  customer_concern TEXT NOT NULL,
  technician_notes TEXT,
  vehicle_symptoms TEXT[],
  requested_services JSONB NOT NULL, -- array of {description, op_code, estimated_hours, parts_needed}
  recommended_services JSONB, -- advisor upsell suggestions from AI
  estimated_total_hours NUMERIC(5,2),
  priority TEXT DEFAULT 'normal' CHECK (priority IN ('low','normal','high','urgent')),
  advisor_edits JSONB, -- track what the advisor changed from AI draft
  dms_repair_order_id TEXT, -- ID returned from DMS after push
  approved_by UUID REFERENCES advisors(id),
  approved_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now()
};

-- Audit log for compliance
CREATE TABLE audit_log (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  walkaround_id UUID REFERENCES walkarounds(id),
  action TEXT NOT NULL, -- 'recording_started','consent_confirmed','transcript_created','ro_draft_created','ro_approved','ro_pushed_to_dms','audio_deleted'
  actor_id UUID REFERENCES advisors(id),
  metadata JSONB,
  created_at TIMESTAMPTZ DEFAULT now()
};

-- Enable RLS
ALTER TABLE walkarounds ENABLE ROW LEVEL SECURITY;
ALTER TABLE transcripts ENABLE ROW LEVEL SECURITY;
ALTER TABLE draft_repair_orders ENABLE ROW LEVEL SECURITY;

-- RLS Policies: advisors see only their own data
CREATE POLICY advisor_walkarounds ON walkarounds FOR ALL USING (advisor_id = auth.uid());
CREATE POLICY advisor_transcripts ON transcripts FOR ALL USING (
  walkaround_id IN (SELECT id FROM walkarounds WHERE advisor_id = auth.uid())
};
CREATE POLICY advisor_draft_ros ON draft_repair_orders FOR ALL USING (
  walkaround_id IN (SELECT id FROM walkarounds WHERE advisor_id = auth.uid())
};

-- Storage bucket for audio files
-- Create via Supabase Dashboard > Storage > New Bucket:
--   Name: walkaround-audio
--   Public: false
--   File size limit: 200MB
--   Allowed MIME types: audio/wav, audio/mp3, audio/m4a, audio/webm

# Initialize the project
mkdir walkaround-api && cd walkaround-api
npm init -y
npm install express multer @deepgram/sdk openai @supabase/supabase-js dotenv cors helmet express-rate-limit
npm install -D typescript @types/express @types/multer ts-node nodemon
npx tsc --init

# Create .env file
cat > .env << 'EOF'
DEEPGRAM_API_KEY=your_deepgram_key_here
OPENAI_API_KEY=your_openai_key_here
SUPABASE_URL=https://yourproject.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key_here
PORT=3000
NODE_ENV=development
DMS_TYPE=tekmetric
DMS_API_BASE_URL=https://sandbox.tekmetric.com/api/v1
DMS_API_KEY=your_tekmetric_api_key_here
DMS_SHOP_ID=your_shop_id_here
EOF

# Start development server
npx nodemon src/index.ts

# Initialize React PWA
npx create-react-app walkaround-tablet --template typescript
cd walkaround-tablet
npm install @supabase/supabase-js axios react-router-dom @mui/material @mui/icons-material @emotion/react @emotion/styled

# Configure PWA manifest for kiosk-style tablet use
# Edit public/manifest.json:
cat > public/manifest.json << 'EOF'
{
  "short_name": "Walkaround",
  "name": "Service Walkaround AI",
  "icons": [{"src": "icon-192.png", "sizes": "192x192", "type": "image/png"}],
  "start_url": "/",
  "display": "standalone",
  "orientation": "portrait",
  "theme_color": "#1565C0",
  "background_color": "#FFFFFF"
}
EOF

# Build and deploy to Railway (same project as API, different service)
# Or deploy to Vercel for static hosting
npm run build
# Deploy via Railway CLI or Vercel CLI

# TEKMETRIC INTEGRATION (most common for independent shops):

# 1. Request API access from Tekmetric
# Visit https://www.tekmetric.com/partners or contact partner@tekmetric.com
# Provide: MSP company info, client shop name, use case description
# Receive: API key, shop_id, sandbox endpoint

# 2. Test API connection
curl -X GET 'https://sandbox.tekmetric.com/api/v1/shops/{shop_id}/repair-orders' \
  -H 'Authorization: Bearer {api_key}' \
  -H 'Content-Type: application/json'

# 3. Create a test repair order
curl -X POST 'https://sandbox.tekmetric.com/api/v1/shops/{shop_id}/repair-orders' \
  -H 'Authorization: Bearer {api_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": 12345,
    "vehicleId": 67890,
    "customerConcern": "Customer reports squealing noise from front brakes when stopping",
    "jobs": [
      {
        "name": "Front Brake Inspection",
        "laborHours": 0.5,
        "note": "Inspect front brake pads, rotors, and calipers. Measure pad thickness and rotor runout."
      }
    ]
  }'

# 4. Verify RO appears in Tekmetric sandbox dashboard
# 5. Switch to production endpoint when ready: https://shop.tekmetric.com/api/v1/

# SHOP-WARE INTEGRATION:
# Similar REST API — see https://developers.shop-ware.com/
# Register at developer portal, obtain OAuth2 credentials

# CDK FORTELLIS INTEGRATION:
# 1. Register at https://developer.fortellis.io/
# 2. Subscribe to 'Service Repair Order' API
# 3. Dealers must authorize your app in their Fortellis Marketplace
# This process can take 2-4 weeks for approval

# Install Railway CLI
npm install -g @railway/cli
railway login

# Link to project created in Step 3
cd walkaround-api
railway link

# Set environment variables in Railway
railway variables set DEEPGRAM_API_KEY=dg_live_xxxxx
railway variables set OPENAI_API_KEY=sk-proj-xxxxx
railway variables set SUPABASE_URL=https://abcdefg.supabase.co
railway variables set SUPABASE_SERVICE_ROLE_KEY=eyJxxxxx
railway variables set DMS_TYPE=tekmetric
railway variables set DMS_API_BASE_URL=https://shop.tekmetric.com/api/v1
railway variables set DMS_API_KEY=xxxxx
railway variables set DMS_SHOP_ID=xxxxx
railway variables set NODE_ENV=production
railway variables set SENTRY_DSN=https://xxxxx@sentry.io/xxxxx

# Deploy
railway up

# Verify deployment
curl https://walkaround-api-production.up.railway.app/health
# Expected response: {"status":"ok","deepgram":"connected","openai":"connected","supabase":"connected","dms":"connected"}

# Configure custom domain (optional)
railway domain add api.walkaround.clientdomain.com

# Build production PWA
cd walkaround-tablet
echo 'REACT_APP_API_URL=https://walkaround-api-production.up.railway.app' > .env.production
echo 'REACT_APP_SUPABASE_URL=https://abcdefg.supabase.co' >> .env.production
echo 'REACT_APP_SUPABASE_ANON_KEY=eyJxxxxx' >> .env.production
npm run build

# Deploy to Vercel
npm install -g vercel
vercel --prod

# Or deploy to Railway as a static site
# railway up (from the walkaround-tablet directory)

// src/pipelines/transcription.ts
import { createClient as createDeepgramClient } from '@deepgram/sdk';
import { createClient } from '@supabase/supabase-js';
import { Readable } from 'stream';
import fs from 'fs';

const deepgram = createDeepgramClient(process.env.DEEPGRAM_API_KEY!);
const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

export interface TranscriptionResult {
  walkaroundId: string;
  formattedText: string;
  rawResponse: any;
  speakerLabels: Record<number, string>;
  confidenceScore: number;
  durationSeconds: number;
}

export async function processWalkaroundAudio(
  walkaroundId: string,
  audioFilePath: string,
  advisorName: string
): Promise<TranscriptionResult> {
  // 1. Upload audio to Supabase Storage for archival
  const audioBuffer = fs.readFileSync(audioFilePath);
  const storagePath = `walkarounds/${walkaroundId}/${Date.now()}.wav`;
  
  const { error: uploadError } = await supabase.storage
    .from('walkaround-audio')
    .upload(storagePath, audioBuffer, {
      contentType: 'audio/wav',
      upsert: false
    });
  
  if (uploadError) {
    console.error('Audio upload failed:', uploadError);
    // Continue processing even if archival fails — transcription is higher priority
  }

  // Update walkaround record with storage path
  await supabase
    .from('walkarounds')
    .update({ audio_storage_path: storagePath, status: 'transcribing' })
    .eq('id', walkaroundId);

  // 2. Send audio to Deepgram Nova-3 for transcription
  const { result, error: dgError } = await deepgram.listen.prerecorded.transcribeFile(
    audioBuffer,
    {
      model: 'nova-3',
      smart_format: true,
      punctuate: true,
      diarize: true,
      diarize_version: '2024-02-01',
      paragraphs: true,
      utterances: true,
      language: 'en-US',
      // Automotive vocabulary hints improve accuracy
      keywords: [
        'brake:2', 'rotor:2', 'caliper:2', 'pad:2',
        'transmission:2', 'differential:2', 'CV joint:2',
        'catalytic converter:2', 'O2 sensor:2', 'MAF sensor:2',
        'check engine:2', 'ABS:2', 'TPMS:2', 'OBD:2',
        'VIN:3', 'mileage:2', 'odometer:2',
        'oil change:2', 'tire rotation:2', 'alignment:2',
        'coolant:2', 'antifreeze:2', 'serpentine belt:2',
        'timing belt:2', 'spark plug:2', 'ignition coil:2',
        'strut:2', 'shock:2', 'control arm:2', 'ball joint:2',
        'power steering:2', 'rack and pinion:2',
        'alternator:2', 'starter:2', 'battery:2'
      ]
    }
  );

  if (dgError) {
    await supabase
      .from('walkarounds')
      .update({ status: 'error' })
      .eq('id', walkaroundId);
    throw new Error(`Deepgram transcription failed: ${dgError.message}`);
  }

  // 3. Process diarized results into formatted text
  const utterances = result.results?.utterances || [];
  const channels = result.results?.channels || [];
  const duration = result.metadata?.duration || 0;
  
  // Build speaker-labeled transcript
  // Speaker 0 is usually the person closest to the mic (advisor)
  const speakerLabels: Record<number, string> = { 0: advisorName, 1: 'Customer' };
  
  let formattedText = '';
  for (const utterance of utterances) {
    const speaker = speakerLabels[utterance.speaker] || `Speaker ${utterance.speaker}`;
    formattedText += `${speaker}: ${utterance.transcript}\n\n`;
  }

  // Calculate average confidence
  const words = channels[0]?.alternatives[0]?.words || [];
  const avgConfidence = words.length > 0
    ? words.reduce((sum: number, w: any) => sum + w.confidence, 0) / words.length
    : 0;

  // 4. Store transcript in database
  const { error: insertError } = await supabase
    .from('transcripts')
    .insert({
      walkaround_id: walkaroundId,
      raw_transcript: result,
      formatted_text: formattedText,
      speaker_labels: speakerLabels,
      confidence_score: Math.round(avgConfidence * 1000) / 1000
    });

  if (insertError) {
    throw new Error(`Failed to store transcript: ${insertError.message}`);
  }

  // 5. Update walkaround status and log
  await supabase
    .from('walkarounds')
    .update({ status: 'drafting', audio_duration_seconds: Math.round(duration) })
    .eq('id', walkaroundId);

  await supabase.from('audit_log').insert({
    walkaround_id: walkaroundId,
    action: 'transcript_created',
    metadata: { confidence: avgConfidence, duration_seconds: duration, word_count: words.length }
  });

  return {
    walkaroundId,
    formattedText,
    rawResponse: result,
    speakerLabels,
    confidenceScore: avgConfidence,
    durationSeconds: Math.round(duration)
  };
}

// src/prompts/ro-extraction.ts

export const RO_EXTRACTION_RESPONSE_SCHEMA = {
  type: 'object' as const,
  properties: {
    vehicle: {
      type: 'object' as const,
      properties: {
        vin: { type: ['string', 'null'] as const, description: 'Vehicle VIN if spoken in transcript. null if not mentioned.' },
        year: { type: ['integer', 'null'] as const },
        make: { type: ['string', 'null'] as const },
        model: { type: ['string', 'null'] as const },
        trim: { type: ['string', 'null'] as const },
        mileage: { type: ['integer', 'null'] as const },
        color: { type: ['string', 'null'] as const },
        license_plate: { type: ['string', 'null'] as const }
      },
      required: ['vin', 'year', 'make', 'model', 'mileage']
    },
    customer: {
      type: 'object' as const,
      properties: {
        name: { type: ['string', 'null'] as const },
        phone: { type: ['string', 'null'] as const },
        email: { type: ['string', 'null'] as const },
        is_waiter: { type: ['boolean', 'null'] as const, description: 'Whether customer is waiting for the vehicle' },
        promised_time: { type: ['string', 'null'] as const, description: 'Any promised completion time mentioned' }
      },
      required: ['name']
    },
    customer_concern_verbatim: {
      type: 'string' as const,
      description: 'The customer primary concern in their own words, as close to verbatim as possible'
    },
    line_items: {
      type: 'array' as const,
      items: {
        type: 'object' as const,
        properties: {
          description: { type: 'string' as const },
          category: { type: 'string' as const, enum: ['ENGINE_MECHANICAL','ENGINE_PERFORMANCE','COOLING_SYSTEM','ELECTRICAL','TRANSMISSION','BRAKES','STEERING_SUSPENSION','EXHAUST','HVAC','MAINTENANCE','TIRES','BODY_INTERIOR','DIAGNOSIS'] },
          estimated_hours: { type: 'number' as const },
          parts_needed: { type: 'array' as const, items: { type: 'string' as const } },
          priority: { type: 'string' as const, enum: ['urgent','high','normal','low'] },
          source: { type: 'string' as const, enum: ['customer_reported','advisor_recommended','advisor_observed'] }
        },
        required: ['description','category','estimated_hours','parts_needed','priority','source']
      }
    },
    advisor_notes: {
      type: 'string' as const,
      description: 'Any additional observations, context, or instructions the advisor mentioned that dont fit into line items'
    },
    safety_concerns: {
      type: 'array' as const,
      items: { type: 'string' as const },
      description: 'Any safety-related issues identified (worn tires, brake issues, fluid leaks, etc.)'
    },
    confidence_notes: {
      type: 'string' as const,
      description: 'Your assessment of transcript clarity and any items you are uncertain about. Flag anything that needs human verification.'
    }
  },
  required: ['vehicle','customer','customer_concern_verbatim','line_items','advisor_notes','safety_concerns','confidence_notes']
};

// Shop-specific op code mapping (customize per client during pilot phase)
export const OP_CODE_MAP: Record<string, Record<string, string>> = {
  // Format: category -> { description_keyword: op_code }
  // These are examples — replace with the actual client's op codes during setup
  MAINTENANCE: {
    'oil change': 'MAINT-OIL',
    'tire rotation': 'MAINT-ROTATE',
    'cabin filter': 'MAINT-CABIN',
    'air filter': 'MAINT-AIR',
    'spark plug': 'MAINT-SPARK',
    'transmission fluid': 'MAINT-TRANS',
    'coolant flush': 'MAINT-COOL',
    'brake fluid flush': 'MAINT-BRK-FL',
    'power steering flush': 'MAINT-PS-FL',
    'serpentine belt': 'MAINT-BELT',
  },
  BRAKES: {
    'brake inspection': 'BRK-INSP',
    'front brake': 'BRK-FRONT',
    'rear brake': 'BRK-REAR',
    'brake pad': 'BRK-PAD',
    'rotor': 'BRK-ROTOR',
    'caliper': 'BRK-CAL',
  },
  DIAGNOSIS: {
    'check engine': 'DIAG-CEL',
    'electrical diag': 'DIAG-ELEC',
    'noise diag': 'DIAG-NOISE',
    'vibration': 'DIAG-VIB',
    'leak': 'DIAG-LEAK',
  },
  // Add remaining categories during pilot tuning phase
};

// src/pipelines/ro-generation.ts
import OpenAI from 'openai';
import { createClient } from '@supabase/supabase-js';
import { RO_EXTRACTION_SYSTEM_PROMPT, RO_EXTRACTION_RESPONSE_SCHEMA, OP_CODE_MAP } from '../prompts/ro-extraction';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

interface RODraft {
  vehicle: {
    vin: string | null;
    year: number | null;
    make: string | null;
    model: string | null;
    trim: string | null;
    mileage: number | null;
    color: string | null;
    license_plate: string | null;
  };
  customer: {
    name: string | null;
    phone: string | null;
    email: string | null;
    is_waiter: boolean | null;
    promised_time: string | null;
  };
  customer_concern_verbatim: string;
  line_items: Array<{
    description: string;
    category: string;
    estimated_hours: number;
    parts_needed: string[];
    priority: string;
    source: string;
  }>;
  advisor_notes: string;
  safety_concerns: string[];
  confidence_notes: string;
}

export async function generateRODraft(
  walkaroundId: string,
  formattedTranscript: string,
  shopName?: string
): Promise<RODraft> {
  // 1. Build the user prompt with the transcript
  const userPrompt = `Here is the walkaround transcript from ${shopName || 'the shop'}. Please extract the repair order information.

--- TRANSCRIPT START ---
${formattedTranscript}
--- TRANSCRIPT END ---

Extract all repair order information following the schema. Be thorough — capture every service need mentioned, whether explicitly requested by the customer or recommended by the advisor.`;

  // 2. Call GPT-5.4 with structured output (JSON mode)
  let completion;
  let model = 'gpt-5.4';
  
  try {
    completion = await openai.chat.completions.create({
      model: 'gpt-5.4',
      messages: [
        { role: 'system', content: RO_EXTRACTION_SYSTEM_PROMPT },
        { role: 'user', content: userPrompt }
      ],
      response_format: {
        type: 'json_schema',
        json_schema: {
          name: 'repair_order_draft',
          strict: true,
          schema: RO_EXTRACTION_RESPONSE_SCHEMA
        }
      },
      temperature: 0.1, // Low temperature for consistent, factual extraction
      max_tokens: 4000
    });
  } catch (error: any) {
    // Fallback to GPT-5.4 mini if GPT-5.4 fails
    console.warn(`GPT-5.4 failed (${error.message}), falling back to GPT-5.4 mini`);
    model = 'gpt-5.4-mini';
    completion = await openai.chat.completions.create({
      model: 'gpt-5.4-mini',
      messages: [
        { role: 'system', content: RO_EXTRACTION_SYSTEM_PROMPT },
        { role: 'user', content: userPrompt }
      ],
      response_format: { type: 'json_object' },
      temperature: 0.1,
      max_tokens: 4000
    });
  }

  const responseText = completion.choices[0]?.message?.content;
  if (!responseText) {
    throw new Error('Empty response from OpenAI');
  }

  const roDraft: RODraft = JSON.parse(responseText);

  // 3. Post-process: map descriptions to shop-specific op codes
  const enrichedLineItems = roDraft.line_items.map(item => {
    const categoryOps = OP_CODE_MAP[item.category] || {};
    let matchedOpCode = null;
    const descLower = item.description.toLowerCase();
    
    for (const [keyword, opCode] of Object.entries(categoryOps)) {
      if (descLower.includes(keyword)) {
        matchedOpCode = opCode;
        break;
      }
    }
    
    return { ...item, op_code: matchedOpCode };
  });

  // 4. Calculate totals
  const totalEstimatedHours = enrichedLineItems.reduce(
    (sum, item) => sum + item.estimated_hours, 0
  );

  // 5. Store draft in database
  const customerConcern = roDraft.customer_concern_verbatim;
  const requestedServices = enrichedLineItems.filter(
    item => item.source === 'customer_reported'
  );
  const recommendedServices = enrichedLineItems.filter(
    item => item.source !== 'customer_reported'
  );

  const { error: insertError } = await supabase
    .from('draft_repair_orders')
    .insert({
      walkaround_id: walkaroundId,
      customer_concern: customerConcern,
      vehicle_symptoms: roDraft.safety_concerns,
      requested_services: requestedServices,
      recommended_services: recommendedServices,
      estimated_total_hours: totalEstimatedHours,
      technician_notes: roDraft.advisor_notes,
      priority: roDraft.safety_concerns.length > 0 ? 'urgent' : 'normal'
    });

  if (insertError) {
    throw new Error(`Failed to store RO draft: ${insertError.message}`);
  }

  // 6. Update walkaround status
  await supabase
    .from('walkarounds')
    .update({
      status: 'review',
      customer_name: roDraft.customer.name,
      vehicle_vin: roDraft.vehicle.vin,
      vehicle_year: roDraft.vehicle.year,
      vehicle_make: roDraft.vehicle.make,
      vehicle_model: roDraft.vehicle.model,
      vehicle_mileage: roDraft.vehicle.mileage
    })
    .eq('id', walkaroundId);

  // 7. Log for audit and cost tracking
  const usage = completion.usage;
  await supabase.from('audit_log').insert({
    walkaround_id: walkaroundId,
    action: 'ro_draft_created',
    metadata: {
      model,
      input_tokens: usage?.prompt_tokens,
      output_tokens: usage?.completion_tokens,
      total_tokens: usage?.total_tokens,
      line_items_count: enrichedLineItems.length,
      has_safety_concerns: roDraft.safety_concerns.length > 0
    }
  });

  return roDraft;
}

// src/integrations/dms.ts

interface DMSRepairOrder {
  customerId?: string;
  customerName: string;
  customerPhone?: string;
  vehicleVin?: string;
  vehicleYear?: number;
  vehicleMake?: string;
  vehicleModel?: string;
  vehicleMileage?: number;
  customerConcern: string;
  jobs: Array<{
    name: string;
    description: string;
    laborHours: number;
    opCode?: string;
    partsNeeded?: string[];
  }>;
  advisorNotes?: string;
  priority?: string;
}

interface DMSResponse {
  success: boolean;
  repairOrderId: string;
  repairOrderNumber: string;
  error?: string;
}

// Base interface for DMS adapters
interface DMSAdapter {
  createRepairOrder(ro: DMSRepairOrder): Promise<DMSResponse>;
  lookupCustomer(name: string, phone?: string): Promise<{ id: string; name: string } | null>;
  lookupVehicle(vin: string): Promise<{ id: string; year: number; make: string; model: string } | null>;
}

// TEKMETRIC ADAPTER
class TekmetricAdapter implements DMSAdapter {
  private baseUrl: string;
  private apiKey: string;
  private shopId: string;

  constructor() {
    this.baseUrl = process.env.DMS_API_BASE_URL || 'https://shop.tekmetric.com/api/v1';
    this.apiKey = process.env.DMS_API_KEY!;
    this.shopId = process.env.DMS_SHOP_ID!;
  }

  private async fetch(path: string, options: RequestInit = {}): Promise<any> {
    const url = `${this.baseUrl}/shops/${this.shopId}${path}`;
    const response = await fetch(url, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });
    if (!response.ok) {
      const errorBody = await response.text();
      throw new Error(`Tekmetric API error ${response.status}: ${errorBody}`);
    }
    return response.json();
  }

  async lookupCustomer(name: string, phone?: string) {
    try {
      const params = new URLSearchParams();
      if (phone) params.set('phone', phone);
      else params.set('search', name);
      const result = await this.fetch(`/customers?${params.toString()}`);
      if (result.content && result.content.length > 0) {
        return { id: result.content[0].id.toString(), name: `${result.content[0].firstName} ${result.content[0].lastName}` };
      }
      return null;
    } catch {
      return null;
    }
  }

  async lookupVehicle(vin: string) {
    try {
      const result = await this.fetch(`/vehicles?vin=${vin}`);
      if (result.content && result.content.length > 0) {
        const v = result.content[0];
        return { id: v.id.toString(), year: v.year, make: v.make, model: v.model };
      }
      return null;
    } catch {
      return null;
    }
  }

  async createRepairOrder(ro: DMSRepairOrder): Promise<DMSResponse> {
    try {
      // Try to find existing customer and vehicle
      let customerId = ro.customerId;
      let vehicleId: string | undefined;

      if (!customerId && ro.customerName) {
        const customer = await this.lookupCustomer(ro.customerName, ro.customerPhone);
        if (customer) customerId = customer.id;
      }

      if (ro.vehicleVin) {
        const vehicle = await this.lookupVehicle(ro.vehicleVin);
        if (vehicle) vehicleId = vehicle.id;
      }

      const body: any = {
        customerConcern: ro.customerConcern,
        jobs: ro.jobs.map(job => ({
          name: job.name,
          note: job.description + (job.partsNeeded?.length ? `\nParts needed: ${job.partsNeeded.join(', ')}` : ''),
          laborHours: job.laborHours,
          authorized: false // Draft status — technician must authorize
        }))
      };

      if (customerId) body.customerId = parseInt(customerId);
      if (vehicleId) body.vehicleId = parseInt(vehicleId);

      const result = await this.fetch('/repair-orders', {
        method: 'POST',
        body: JSON.stringify(body)
      });

      return {
        success: true,
        repairOrderId: result.id.toString(),
        repairOrderNumber: result.repairOrderNumber || result.id.toString()
      };
    } catch (error: any) {
      return {
        success: false,
        repairOrderId: '',
        repairOrderNumber: '',
        error: error.message
      };
    }
  }
}

// SHOP-WARE ADAPTER
class ShopWareAdapter implements DMSAdapter {
  private baseUrl: string;
  private apiKey: string;

  constructor() {
    this.baseUrl = process.env.DMS_API_BASE_URL || 'https://api.shop-ware.com/api/v1';
    this.apiKey = process.env.DMS_API_KEY!;
  }

  // Similar structure — implement based on Shop-Ware API docs
  // https://developers.shop-ware.com/
  async lookupCustomer(name: string, phone?: string) { return null; /* implement */ }
  async lookupVehicle(vin: string) { return null; /* implement */ }
  async createRepairOrder(ro: DMSRepairOrder): Promise<DMSResponse> {
    // Implement per Shop-Ware API docs
    return { success: false, repairOrderId: '', repairOrderNumber: '', error: 'Shop-Ware adapter not yet implemented' };
  }
}

// Factory function
export function createDMSAdapter(): DMSAdapter {
  const dmsType = process.env.DMS_TYPE || 'tekmetric';
  switch (dmsType) {
    case 'tekmetric': return new TekmetricAdapter();
    case 'shopware': return new ShopWareAdapter();
    default: throw new Error(`Unsupported DMS type: ${dmsType}`);
  }
}

// Main function called when advisor approves an RO draft
export async function pushApprovedROToDMS(
  walkaroundId: string,
  draftRO: any, // draft_repair_orders row from Supabase
  walkaround: any // walkarounds row from Supabase
): Promise<DMSResponse> {
  const adapter = createDMSAdapter();

  const dmsRO: DMSRepairOrder = {
    customerName: walkaround.customer_name || 'Walk-in Customer',
    vehicleVin: walkaround.vehicle_vin,
    vehicleYear: walkaround.vehicle_year,
    vehicleMake: walkaround.vehicle_make,
    vehicleModel: walkaround.vehicle_model,
    vehicleMileage: walkaround.vehicle_mileage,
    customerConcern: draftRO.customer_concern,
    jobs: [
      ...(draftRO.requested_services || []).map((s: any) => ({
        name: s.description.substring(0, 100),
        description: s.description,
        laborHours: s.estimated_hours,
        opCode: s.op_code,
        partsNeeded: s.parts_needed
      })),
      ...(draftRO.recommended_services || []).map((s: any) => ({
        name: `[RECOMMENDED] ${s.description.substring(0, 80)}`,
        description: s.description,
        laborHours: s.estimated_hours,
        opCode: s.op_code,
        partsNeeded: s.parts_needed
      }))
    ],
    advisorNotes: draftRO.technician_notes,
    priority: draftRO.priority
  };

  return adapter.createRepairOrder(dmsRO);
}

// src/index.ts
import express from 'express';
import multer from 'multer';
import cors from 'cors';
import helmet from 'helmet';
import rateLimit from 'express-rate-limit';
import { createClient } from '@supabase/supabase-js';
import { processWalkaroundAudio } from './pipelines/transcription';
import { generateRODraft } from './pipelines/ro-generation';
import { pushApprovedROToDMS } from './integrations/dms';
import * as Sentry from '@sentry/node';
import dotenv from 'dotenv';

dotenv.config();

const app = express();
const port = process.env.PORT || 3000;

// Initialize Sentry
if (process.env.SENTRY_DSN) {
  Sentry.init({ dsn: process.env.SENTRY_DSN });
  app.use(Sentry.Handlers.requestHandler());
}

// Middleware
app.use(helmet());
app.use(cors({ origin: process.env.ALLOWED_ORIGINS?.split(',') || '*' }));
app.use(express.json());
app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 })); // 100 req/15min

// File upload config (max 200MB for long walkaround recordings)
const upload = multer({ dest: '/tmp/uploads/', limits: { fileSize: 200 * 1024 * 1024 } });

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

// Health check
app.get('/health', async (req, res) => {
  try {
    const { error: dbErr } = await supabase.from('advisors').select('id').limit(1);
    res.json({
      status: 'ok',
      deepgram: process.env.DEEPGRAM_API_KEY ? 'configured' : 'missing',
      openai: process.env.OPENAI_API_KEY ? 'configured' : 'missing',
      supabase: dbErr ? 'error' : 'connected',
      dms: process.env.DMS_API_KEY ? 'configured' : 'missing'
    });
  } catch (err) {
    res.status(500).json({ status: 'error', error: String(err) });
  }
});

// POST /walkarounds - Create a new walkaround session
app.post('/walkarounds', async (req, res) => {
  const { advisor_id, consent_obtained } = req.body;
  if (!advisor_id) return res.status(400).json({ error: 'advisor_id required' });
  if (!consent_obtained) return res.status(400).json({ error: 'consent_obtained must be true' });

  const { data, error } = await supabase
    .from('walkarounds')
    .insert({
      advisor_id,
      consent_obtained,
      status: 'recording',
      recording_started_at: new Date().toISOString()
    })
    .select()
    .single();

  if (error) return res.status(500).json({ error: error.message });

  await supabase.from('audit_log').insert({
    walkaround_id: data.id,
    action: 'recording_started',
    actor_id: advisor_id,
    metadata: { consent_obtained }
  });

  res.json({ walkaround_id: data.id, status: 'recording' });
});

// POST /walkarounds/:id/audio - Upload audio and trigger pipeline
app.post('/walkarounds/:id/audio', upload.single('audio'), async (req, res) => {
  const walkaroundId = req.params.id;
  const audioFile = req.file;
  if (!audioFile) return res.status(400).json({ error: 'audio file required' });

  try {
    // Update walkaround with recording end time
    await supabase
      .from('walkarounds')
      .update({ recording_ended_at: new Date().toISOString() })
      .eq('id', walkaroundId);

    // Get advisor info for speaker labeling
    const { data: walkaround } = await supabase
      .from('walkarounds')
      .select('*, advisors(name)')
      .eq('id', walkaroundId)
      .single();

    const advisorName = (walkaround as any)?.advisors?.name || 'Advisor';

    // Step 1: Transcribe
    const transcription = await processWalkaroundAudio(
      walkaroundId,
      audioFile.path,
      advisorName
    );

    // Step 2: Generate RO draft
    const roDraft = await generateRODraft(
      walkaroundId,
      transcription.formattedText
    );

    // Clean up temp file
    const fs = require('fs');
    fs.unlinkSync(audioFile.path);

    res.json({
      walkaround_id: walkaroundId,
      status: 'review',
      transcript_preview: transcription.formattedText.substring(0, 500),
      draft_ro: roDraft,
      confidence: transcription.confidenceScore
    });
  } catch (error: any) {
    Sentry.captureException(error);
    console.error('Pipeline error:', error);
    res.status(500).json({ error: error.message, walkaround_id: walkaroundId });
  }
});

// GET /walkarounds/:id - Get walkaround details including transcript and draft RO
app.get('/walkarounds/:id', async (req, res) => {
  const { data: walkaround, error } = await supabase
    .from('walkarounds')
    .select('*, transcripts(*), draft_repair_orders(*), advisors(name)')
    .eq('id', req.params.id)
    .single();

  if (error || !walkaround) return res.status(404).json({ error: 'Not found' });
  res.json(walkaround);
});

// GET /walkarounds - List walkarounds for an advisor
app.get('/walkarounds', async (req, res) => {
  const advisorId = req.query.advisor_id as string;
  const status = req.query.status as string;
  let query = supabase
    .from('walkarounds')
    .select('id, customer_name, vehicle_make, vehicle_model, status, created_at')
    .order('created_at', { ascending: false })
    .limit(50);

  if (advisorId) query = query.eq('advisor_id', advisorId);
  if (status) query = query.eq('status', status);

  const { data, error } = await query;
  if (error) return res.status(500).json({ error: error.message });
  res.json(data);
});

// POST /walkarounds/:id/approve - Approve draft RO and push to DMS
app.post('/walkarounds/:id/approve', async (req, res) => {
  const walkaroundId = req.params.id;
  const { advisor_id, edits } = req.body; // edits = any changes the advisor made

  try {
    // Get the draft RO
    const { data: draftRO } = await supabase
      .from('draft_repair_orders')
      .select('*')
      .eq('walkaround_id', walkaroundId)
      .single();

    const { data: walkaround } = await supabase
      .from('walkarounds')
      .select('*')
      .eq('id', walkaroundId)
      .single();

    if (!draftRO || !walkaround) {
      return res.status(404).json({ error: 'Walkaround or draft RO not found' });
    }

    // Apply advisor edits if any
    const finalRO = edits ? { ...draftRO, ...edits } : draftRO;

    // Push to DMS
    const dmsResult = await pushApprovedROToDMS(walkaroundId, finalRO, walkaround);

    if (dmsResult.success) {
      // Update records
      await supabase.from('draft_repair_orders').update({
        approved_by: advisor_id,
        approved_at: new Date().toISOString(),
        advisor_edits: edits || null,
        dms_repair_order_id: dmsResult.repairOrderNumber
      }).eq('walkaround_id', walkaroundId);

      await supabase.from('walkarounds').update({
        status: 'pushed_to_dms'
      }).eq('id', walkaroundId);

      await supabase.from('audit_log').insert({
        walkaround_id: walkaroundId,
        action: 'ro_pushed_to_dms',
        actor_id: advisor_id,
        metadata: { dms_ro_id: dmsResult.repairOrderNumber, had_edits: !!edits }
      });

      res.json({
        success: true,
        dms_repair_order_number: dmsResult.repairOrderNumber,
        message: `Repair order ${dmsResult.repairOrderNumber} created in DMS`
      });
    } else {
      res.status(502).json({
        success: false,
        error: dmsResult.error,
        message: 'Failed to push to DMS — draft saved for manual entry'
      });
    }
  } catch (error: any) {
    Sentry.captureException(error);
    res.status(500).json({ error: error.message });
  }
});

// Sentry error handler
if (process.env.SENTRY_DSN) {
  app.use(Sentry.Handlers.errorHandler());
}

app.listen(port, () => {
  console.log(`Walkaround API server running on port ${port}`);
});

// src/jobs/compliance-manager.ts
import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

const RETENTION_DAYS = parseInt(process.env.AUDIO_RETENTION_DAYS || '90');

export async function runRetentionCleanup(): Promise<{
  filesDeleted: number;
  errors: string[];
}> {
  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - RETENTION_DAYS);

  // Find walkarounds older than retention period with audio files
  const { data: expiredWalkarounds, error } = await supabase
    .from('walkarounds')
    .select('id, audio_storage_path')
    .lt('created_at', cutoffDate.toISOString())
    .not('audio_storage_path', 'is', null);

  if (error || !expiredWalkarounds) {
    return { filesDeleted: 0, errors: [error?.message || 'Query failed'] };
  }

  let filesDeleted = 0;
  const errors: string[] = [];

  for (const w of expiredWalkarounds) {
    try {
      // Delete audio file from storage
      const { error: deleteError } = await supabase.storage
        .from('walkaround-audio')
        .remove([w.audio_storage_path]);

      if (deleteError) {
        errors.push(`Failed to delete ${w.audio_storage_path}: ${deleteError.message}`);
        continue;
      }

      // Clear the storage path reference
      await supabase
        .from('walkarounds')
        .update({ audio_storage_path: null })
        .eq('id', w.id);

      // Audit log
      await supabase.from('audit_log').insert({
        walkaround_id: w.id,
        action: 'audio_deleted',
        metadata: {
          reason: 'retention_policy',
          retention_days: RETENTION_DAYS,
          original_path: w.audio_storage_path
        }
      });

      filesDeleted++;
    } catch (err: any) {
      errors.push(`Error processing ${w.id}: ${err.message}`);
    }
  }

  return { filesDeleted, errors };
}

export async function generateComplianceReport(startDate: Date, endDate: Date) {
  // Total walkarounds in period
  const { count: totalWalkarounds } = await supabase
    .from('walkarounds')
    .select('*', { count: 'exact', head: true })
    .gte('created_at', startDate.toISOString())
    .lte('created_at', endDate.toISOString());

  // Consent rate
  const { count: consentedWalkarounds } = await supabase
    .from('walkarounds')
    .select('*', { count: 'exact', head: true })
    .gte('created_at', startDate.toISOString())
    .lte('created_at', endDate.toISOString())
    .eq('consent_obtained', true);

  // ROs successfully pushed to DMS
  const { count: pushedToDMS } = await supabase
    .from('walkarounds')
    .select('*', { count: 'exact', head: true })
    .gte('created_at', startDate.toISOString())
    .lte('created_at', endDate.toISOString())
    .eq('status', 'pushed_to_dms');

  // Audio files currently stored
  const { count: audioFilesStored } = await supabase
    .from('walkarounds')
    .select('*', { count: 'exact', head: true })
    .not('audio_storage_path', 'is', null);

  // Audio files deleted this period
  const { count: audioFilesDeleted } = await supabase
    .from('audit_log')
    .select('*', { count: 'exact', head: true })
    .eq('action', 'audio_deleted')
    .gte('created_at', startDate.toISOString())
    .lte('created_at', endDate.toISOString());

  return {
    report_period: { start: startDate.toISOString(), end: endDate.toISOString() },
    total_walkarounds: totalWalkarounds || 0,
    consent_rate: totalWalkarounds ? ((consentedWalkarounds || 0) / totalWalkarounds * 100).toFixed(1) + '%' : 'N/A',
    ros_pushed_to_dms: pushedToDMS || 0,
    audio_files_currently_stored: audioFilesStored || 0,
    audio_files_deleted_this_period: audioFilesDeleted || 0,
    retention_policy_days: RETENTION_DAYS,
    generated_at: new Date().toISOString()
  };
}

// Schedule this to run daily at 2 AM via Railway cron or a simple setInterval
// In production, add this to your Express server:
// import cron from 'node-cron';
// cron.schedule('0 2 * * *', () => runRetentionCleanup());
// cron.schedule('0 3 * * 1', () => generateComplianceReport(lastWeekStart, lastWeekEnd));