Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

```html

Building a Vendor Referral Tracking System: Lambda, DynamoDB, and CloudFront Integration

This post documents the complete implementation of a referral tracking infrastructure for the JADA vendor partnership program. The system captures vendor-originated clicks, logs them to DynamoDB, and redirects guests to the main site with UTM parameters for GA4 attribution—all while maintaining zero impact on existing traffic patterns.

What Was Built

  • A public /ref/{code} GET endpoint on the ShipCaptainCrew Lambda function
  • DynamoDB click logging with vendor names, timestamps, and running counts
  • CloudFront distribution behavior to route referral traffic without cache collisions
  • Seven live referral links for initial vendor partners (Solare, Board & Brew, Puesto, Smallgoods, Whole Foods, Total Wine, Gianni Buonomo)
  • HTML preview pages for vendor email outreach with embedded approval workflows

Infrastructure Architecture

Lambda Handler Routing

The core change was in /tmp/scc-deployed/lambda_function.py. The Lambda handler needed to expose the /ref/* path as a public route (no authorization required) while keeping the rest of the dashboard protected. This required modifying the request routing logic before the authorization gate:


# Pseudo-code structure (exact line numbers vary by build)
def lambda_handler(event, context):
    path = event['rawPath']
    
    # Public referral endpoint - no auth required
    if path.startswith('/ref/'):
        return handle_referral_click(event)
    
    # All other routes require authorization
    if not is_authorized(event):
        return 401_response()
    
    # Protected dashboard routes...

The key decision here was to place the referral check before the authorization gate. This ensures that unauthenticated guests clicking vendor links aren't blocked by API authentication. The authorization logic itself remained untouched for all other endpoints.

DynamoDB Click Logging

Each referral click writes to a DynamoDB table (exact table name managed in environment variables) with this structure:


{
  "vendor_code": "boardbrew",
  "timestamp": "2025-01-15T14:32:18Z",
  "click_count": 42,
  "utm_source": "referral",
  "utm_medium": "vendor_link"
}

The handle_referral_click() function atomically increments the click counter and returns a 302 redirect to the main site (queenofsandiego.com) with UTM parameters appended:


Location: https://queenofsandiego.com/?utm_source=ref_{vendor_code}&utm_medium=vendor&utm_campaign=jada_partnerships

This approach gives GA4 visibility into vendor-driven traffic while maintaining a clean separation between the ShipCaptainCrew domain and the main site.

CloudFront Distribution Behavior

The CloudFront distribution for shipcaptaincrew.queenofsandiego.com required a new behavior to handle /ref/* paths. The deployment involved patching the distribution config and waiting for CloudFront to roll out the change:


aws cloudfront get-distribution-config --id [DIST_ID] > cf-config.json

# Patch in new behavior for /ref/*
# Apply with: aws cloudfront update-distribution --cli-input-json file://cf-config.json

# Monitor deployment:
aws cloudfront get-distribution --id [DIST_ID] --query 'Distribution.Status'

The new behavior routes /ref/* requests directly to the Lambda origin without caching, since each click is unique. This prevents cache collisions with the main dashboard paths and ensures real-time click recording.

Deployment Process and Key Decisions

Why Update Lambda Before CloudFront?

The Lambda code was updated and deployed first, then CloudFront behavior was added afterward. This ordering allows for testing via the API Gateway stage URL before public rollout through CloudFront. Once the endpoint worked at https://[api_gateway_id].execute-api.us-west-2.amazonaws.com/[stage]/ref/solare, CloudFront could be safely configured to route traffic to it.

Public vs. Protected Routes

A critical design decision was making /ref/* explicitly public. The Lambda handler includes an authorizer that validates JWT tokens for dashboard access. By checking the path before authorization, we allow unauthenticated guests to trigger referral clicks without getting a 401 response. This is intentional—we want vendor-shared links to be clickable by anyone, not just authenticated users.

UTM Parameter Strategy

Rather than trying to track complex referral data in GA4 custom events (which requires additional client-side JavaScript), the system uses simple UTM parameters in the redirect URL. This approach:

  • Requires zero changes to the main queenofsandiego.com frontend
  • Works with GA4's default channel attribution logic
  • Allows filtering referral-sourced sessions in analytics without custom code
  • Provides fallback tracking in DynamoDB if GA4 data is incomplete

Vendor Outreach Integration

Seven vendor partners received personalized referral links and HTML email previews. The preview pages (e.g., /tmp/vendor-referral-outreach.html) were uploaded to S3 at predictable paths for dashboard approval workflows:


s3://[bucket]/approvals/2025-01-15/vendor-referral-boardbrew.html
s3://[bucket]/approvals/2025-01-15/vendor-referral-solare.html
s3://[bucket]/approvals/2025-01-15/vendor-referral-puesto.html
# ... etc

Each preview includes the exact referral link and UTM parameters so vendors can see how their traffic will be attributed before clicking "send."

Testing and Verification

The referral endpoint was tested end-to-end:


# Test through CloudFront (with cache invalidation for fresh response)
curl -v https://shipcaptaincrew.queenofsandiego.com/ref/boardbrew

# Expected: 302 redirect to queenofsandiego.com with utm_source=ref_boardbrew

# Verify DynamoDB logged the click
aws dynamodb get-item --table-name [REFERRAL_TABLE] --key '{"vendor_code":{"S":"boardbrew"}}'

CloudFront cache invalidation was critical. After updating the distribution behavior, the /ref/* paths were invalidated to ensure the first request hit the Lambda origin rather than a stale cached response.

What's Next

The referral system is live and operational. Future enhancements may include:

  • Dashboard widget displaying real-time click counts by vendor (querying DynamoDB)
  • Weekly digest emails to vendors showing their referral performance
  • A/B testing different redirect landing pages by vendor segment
  • Integration with the billing system to track actual purchases from referred guests

The infrastructure is intentionally simple and stateless—each click is logged immediately, and the redirect is synchronous. This minimizes latency and eliminates the need