Matchmaker V3 Pipeline

Matchmaker · Pipeline V3

How V3 builds a tour

An autonomous Claude agent composes the route. A server that does not trust it routes every plan with GraphHopper and measures it against budget and direction before anything is returned.

data prep claude call revision loop fallback click a block to jump to it

Set the request

Every number and diagram below is computed with the pipeline's own formulas.

180 km
3 of 5

What goes in

The client request, the rider's records, three external services.

Client request

controllers/matchmaker.ts → matchTour

  • version: "v2"V3 still speaks the V2 contract.
  • target { mode, value }distance_km or duration_minutes.
  • directionnorth | east | south | west.
  • user_coordinatesStart and end of the loop.
  • difficulty, curvaturedifficulty becomes driving_level.
  • street_type, street_widthGerman strings → codes 0 / 1 / 2.
  • bike_override_id, start_at, locale, debugOptional.

Rider records

services/matchmaker.ts:727 · one deep query

  • active_bike + garagesStyles, types, tour lengths, equipment, tyres, model, brand.
  • user_profileMatchmaker styles, favourite weathers.
  • story historyOrdered ids — the novelty dimension.
  • passes, lakesAnchors, difficulty, gradient, coordinates.

External services

each one degrades instead of failing

  • ANTHROPIC_API_KEYMissing → 503. The only hard dependency.
  • MAPBOX_API_TOKENMissing → haversine radius instead.
  • OPENWEATHERMAP_API_KEYWeather signal and tool.
  • GraphHopperMeasures every plan, routes the fallback.
Request body for the current scenario 

    

  


  

    

      
What happens

      
Pick a stage — each one draws what it does.

    

    

      
      

    

  


  

    

      
What comes out

      
One array, one element, four side effects.

    

    

      

        
The returned tour object

        
mapMatchmakerV2GeneratedTourToLegacyShape → controller

        
    
          
  • isGenerated: trueAlways true on V3; storyId always null.
    • 
          
  • tourGraphHopper path: coordinates, distance, time, ascend, instructions.
    • 
          
  • editable_waypointsReverse-geocoded stops in riding order.
    • 
          
  • name / lead / descriptionMetadata model, request locale, ~400 words.
    • 
          
  • matchingScoreDisplay score 0–100, rounded, as a string.
    • 
          
  • reasoningOne localised sentence about the fit.
    • 
          
  • distance / timeMetres and seconds — as measured, never as planned.
    • 
          
  • passesFull records for submitted pass_ids, or null.
    • 
          
  • altitude, turnsAscend from the path; left/right turns from the curve calculator.
    • 
          
  • preview_mapUploaded static map URL.
    • 
          
  • diagnosticsOnly when debug: true.
    • 
          
  • agentCompositionAttached, then deleted by the controller. Lives in logs and snapshots, never in the response.
    • 
        

      

      

        

          
Side effects

          
    
            
  • result snapshotsSkipped when the caller sent is_matchmaker=true.
    • 
            
  • matchmaker-step-cost rowsOne per step; flushed in a finally, so failed runs still bill.
    • 
            
  • Mixpanel event"Generate tour story", pipeline: "v3".
    • 
            
  • pipeline_complete logLatency, tokens, turns, fallbackUsed, tool calls.
    • 
          

        

        

          
Failure modes

          
    
            
  • 400Contract violation.
    • 
            
  • 401No authenticated user.
    • 
            
  • 503ANTHROPIC_API_KEY missing.
    • 
            
  • neverAgent gives up, budget stays off, Mapbox or weather down — the run degrades and still returns a tour.
    •