Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

Building a Referral Tracking System for the JADA Vendor Program: Lambda, DynamoDB, and CloudFront Integration

What Was Done

We implemented a complete referral tracking infrastructure for the Queen of San Diego vendor outreach program. The system captures click events from vendor-shared links, logs them to DynamoDB, and redirects guests to the main site with UTM parameters for analytics attribution. This required deploying a new Lambda endpoint, configuring CloudFront behaviors, managing DNS routing, and building an approval workflow dashboard.

Core Architecture: The /ref Endpoint

The referral system centers on a simple but effective pattern: a parameterized GET endpoint on the ShipCaptainCrew Lambda that intercepts vendor-shared links before redirecting the user.

Endpoint Pattern:

GET https://shipcaptaincrew.queenofsandiego.com/ref/{code}

Live referral codes deployed include: solare, smallgoods, puesto, boardbrew, wholefoods, totalwine, and gbvintners.

Lambda Implementation Details

The handler lives in /tmp/scc-deployed/lambda_function.py. The critical section implements a public (unauthenticated) route for /ref/* paths that bypasses the API Gateway authorizer.

The implementation follows this logic:

  • Route Matching: Check if the path starts with /ref/ before the authorization gate
  • Vendor Code Extraction: Parse the vendor code from the path (e.g., /ref/boardbrew → boardbrew)
  • DynamoDB Logging: Insert a record into the referral tracking table with vendor name, timestamp, and incrementing click count
  • HTTP 302 Redirect: Return a temporary redirect to https://queenofsandiego.com with UTM parameters: utm_source=vendor_referral&utm_medium=referral&utm_campaign={vendor_code}

This unauthenticated route was essential because external vendors cannot obtain API keys. By placing the route check before the authorization gate, we ensure vendor links work without credentials while keeping the rest of the API protected.

DynamoDB Tracking Table

Click events are persisted in a DynamoDB table configured with:

  • Partition Key: vendor_code (e.g., "boardbrew")
  • Sort Key: timestamp (ISO 8601 format)
  • Attributes:
    • vendor_name: Human-readable vendor name (e.g., "Board & Brew")
    • click_count: Running tally of clicks for that vendor
    • utm_source, utm_medium, utm_campaign: GA4 attribution parameters

This schema allows us to query click history by vendor and timestamp, making it trivial to generate reports or detect anomalies.

CloudFront Configuration

The ShipCaptainCrew domain is served through a CloudFront distribution. We added a new behavior to route /ref/* requests to the API Gateway origin instead of the S3 static site origin.

Behavior Configuration:

  • Path Pattern: /ref/*
  • Origin: API Gateway (SCC's API Gateway ID)
  • Viewer Protocol Policy: Redirect HTTP to HTTPS
  • Cache TTL: 0 seconds (no caching — each click must hit Lambda)
  • Allowed Methods: GET, HEAD, OPTIONS

The zero TTL is critical: referral clicks must always execute the Lambda function to ensure accurate DynamoDB logging. Caching would create stale entries and miss concurrent clicks.

DNS and Routing

No Route53 changes were required. The shipcaptaincrew.queenofsandiego.com subdomain was already aliased to the CloudFront distribution. The new CloudFront behavior routes /ref/* traffic to the correct origin transparently.

Deployment and Testing

After deploying the Lambda changes and CloudFront behavior, we tested the end-to-end flow:

curl -L https://shipcaptaincrew.queenofsandiego.com/ref/boardbrew -v

This returns a 302 redirect to https://queenofsandiego.com?utm_source=vendor_referral&utm_medium=referral&utm_campaign=boardbrew. The -L flag follows the redirect and confirms the guest lands on the main site. Lambda CloudWatch logs confirm the DynamoDB write.

After deployment, we invalidated the CloudFront cache for /ref/* to ensure edge nodes immediately route new requests to the Lambda origin rather than serving stale content.

HTML Preview and Dashboard Integration

To streamline vendor outreach, we created an HTML preview page (/tmp/vendor-referral-outreach.html) embedding all vendor email templates. This preview is served from S3 and linked from a dashboard task card for approval workflow.

The preview page includes:

  • Vendor name and referral code
  • Full HTML email template
  • Copy-paste-friendly referral link
  • Expected UTM parameters

The S3 bucket is configured with:

  • Bucket: queenofsandiego-dashboards
  • Object Key: vendor-referral/outreach-preview.html
  • Public Read: Yes (for dashboard deep links)
  • MIME Type: text/html; charset=utf-8

A corresponding dashboard task card was created via the update_dashboard.py API with:

  • Card Type: Approval (requires manual action)
  • Title: "Vendor Referral Program Outreach"
  • Deep Link: Direct URL to the S3-hosted preview page
  • Status: Pending approval

Why This Architecture

Lambda for /ref: Serverless execution eliminates operational overhead. Redirects are stateless and lightweight — perfect for Lambda's execution model. DynamoDB writes are atomic and indexed for fast queries.

Public Route Before Auth: Vendors cannot authenticate. Placing the /ref check before the authorization gate ensures external users can click shared links without API credentials, while keeping the rest of the API protected.