Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Integrating Instagram Photos into Guest Upload Gallery: Architecture and Implementation

The guest photo page system at shipcaptaincrew.queenofsandiego.com/g/{event_id} needed enhancement to surface Instagram content alongside user-uploaded charter photos. This post covers the architectural decisions, Lambda implementation patterns, and infrastructure setup required to merge two distinct photo sources into a unified guest experience.

System Overview

The existing guest photo gallery displays approved photos uploaded by charter guests, organized by event date. The enhancement adds Instagram posts from the @sailjada account within matching time windows—same day/event context. This required:

  • Conditional Instagram Graph API integration within the Lambda function
  • Safe credential management using environment variables
  • Array merging logic that gracefully degrades when Instagram access is unavailable
  • Minimal changes to existing S3 and CloudFront infrastructure

Lambda Function Architecture

The shipcaptaincrew Lambda function (us-east-1 region, AWS Account 782785212866) handles the core photo aggregation logic. Rather than force Instagram integration as a hard requirement, we implemented it as an optional feature with defensive programming patterns.

Why Optional Integration? During development and testing phases, Instagram API credentials may not be available or configured. By making the integration dormant until explicitly enabled, we ensure:

  • The gallery continues functioning with guest uploads alone
  • No runtime errors if credentials are missing
  • Simple activation path when Instagram access is ready
  • Clear audit trail of when the feature becomes active

The function checks for two environment variables:

  • IG_USER_ID: The numeric ID for the @sailjada Instagram business account
  • IG_ACCESS_TOKEN: Long-lived access token from Facebook's Instagram Graph API

When either variable is missing, the Instagram integration returns an empty array, allowing the guest uploads to remain the primary photo source.

Implementation Pattern: Conditional API Calls

The Lambda implements a straightforward conditional pattern for Instagram integration:

def get_instagram_photos(event_id, event_date):
    ig_user_id = os.environ.get('IG_USER_ID')
    ig_access_token = os.environ.get('IG_ACCESS_TOKEN')
    
    # Return empty array if credentials unavailable
    if not ig_user_id or not ig_access_token:
        return []
    
    # Query Instagram Graph API for posts within event window
    # Handle pagination and time-window filtering
    # Return normalized photo objects matching guest upload schema

This pattern avoids try-catch complexity for missing credentials—it's explicit and easy to trace. When enabled, the function queries the Instagram Graph API for posts from the @sailjada account within a configurable time window (typically ±12 hours from the event date).

Photo Normalization and Merging

Guest uploads and Instagram posts have different metadata structures. The Lambda normalizes both to a common schema before returning:

  • Source field: "guest_upload" or "instagram" for client-side filtering/styling
  • Timestamp: Standardized to ISO 8601 format for sorting
  • URL: Direct S3 path for uploads, Instagram CDN URL for posts
  • Attribution: Uploader name/handle, preserved for credit
  • Approval status: Always "approved" for Instagram (curator-verified account); conditional for uploads

The response array merges both sources and sorts by timestamp, creating a seamless chronological gallery.

Infrastructure and Storage

The existing infrastructure required minimal changes:

  • S3 Bucket: shipcaptaincrew-guest-uploads (us-east-1) stores guest photos with folder structure photos/{event_id}/{filename}
  • CloudFront Distribution: Serves both S3 objects and Lambda responses with appropriate cache headers
  • Lambda Execution Role: Requires no additional S3 permissions; Instagram data is retrieved via public APIs
  • Route53 Hosted Zone: queenofsandiego.com DNS records unchanged; all traffic routes to existing CloudFront distribution

Caching Considerations: Guest upload metadata updates frequently (new approvals, denials). Instagram posts are time-bounded and change infrequently. Cache-Control headers differentiate:

  • Guest uploads: 5-minute TTL (balance between freshness and API call reduction)
  • Instagram posts: 1-hour TTL (stable content, rare updates)
  • Combined response: Conservative 5-minute TTL to catch rapid upload approvals

Environment Variable Configuration

The Lambda function loads credentials at runtime using environment variable sourcing:

# Example credential loading (do NOT commit actual values)
export IG_USER_ID="your_business_account_id"
export IG_ACCESS_TOKEN="your_long_lived_token"

# Update Lambda environment via AWS CLI:
aws lambda update-function-configuration \
  --function-name shipcaptaincrew \
  --region us-east-1 \
  --environment Variables={IG_USER_ID=value,IG_ACCESS_TOKEN=value}

Credentials are stored in AWS Lambda environment variables (encrypted at rest). They're never logged or included in function code.

API Error Handling

When Instagram integration is active, the function implements resilience patterns:

  • Rate limiting: Catch HTTP 429 responses and return guest uploads only
  • Token expiration: Catch 401 errors and log for credential refresh
  • Network timeouts: Set 5-second timeout on Instagram API calls; fail gracefully to guest uploads only
  • Malformed responses: Validate JSON schema; skip corrupted posts rather than failing entire request

This defensive approach ensures the guest gallery always remains functional, even when external dependencies fail.

Monitoring and Testing

The implementation includes CloudWatch logging for diagnostic purposes:

  • Log when Instagram integration is skipped (missing credentials)
  • Log successful Instagram API calls with post count
  • Log errors/timeouts without exposing token values
  • Metrics: response time, guest upload count, Instagram post count

Local testing uses mock Instagram responses without requiring actual API credentials, enabling development iteration without environmental dependencies.

What's Next

This implementation provides a foundation for future enhancements:

  • Hashtag filtering: Allow gallery admins to filter Instagram posts by event-specific hashtags
  • Caption display: Surface Instagram captions in the gallery UI
  • User-agent rotation: Improve Instagram request reliability in high-traffic scenarios
  • Token refresh automation: Implement automatic long-lived token refresh before expiration

The modular design ensures each enhancement can be added without restructuring the core architecture.