Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

```html

Implementing Payment Logging for Patron Management in the ShipCaptainCrew Lambda Backend

What Was Done

This session focused on adding payment logging capabilities to the ShipCaptainCrew tool, enabling crew members to record when patrons have paid for their event participation. The implementation involved three core layers:

  • Backend Lambda function extensions for payment state management and Gmail notification integration
  • Frontend dispatch HTML modal UI for logging payments with administrative controls
  • Infrastructure adjustments to route payment-related requests correctly through CloudFront

The work builds on existing infrastructure but required careful sequencing to avoid breaking production while introducing new payment tracking endpoints.

Technical Architecture

Database Schema: The ShipCaptainCrew system uses DynamoDB to store event roster data. Each event item contains participant records with fields for attendance, waivers, and payment status. The payment logging feature adds a new optional field (payment_cleared) to track when crew members confirm that a patron has settled their financial obligation.

Lambda Handler Pattern: The existing lambda_function.py uses a routing pattern at the handler entry point that parses incoming requests by HTTP method and path. New payment handlers follow the same pattern:

POST /api/events/{event_id}/{patron_id}/payment → handle_payment_logged()
GET /api/events/{event_id}/{patron_id}/payment → handle_get_payment_status()

These handlers sit alongside existing endpoints like handle_waiver_get() (line 1697) and the event roster retrieval logic in handle_list_events(). The routing dispatcher at the top of lambda_handler() parses the event ID and method, then delegates to the appropriate handler.

Gmail Integration: When a payment is logged, the system sends a notification email to the patron. This requires:

  • Gmail service account credentials stored in Lambda environment variables
  • An SMTP helper function that constructs and sends emails via Gmail's API
  • Environment variables for sender address and email templates

These credentials were merged from existing environment variables already present on the Lambda function during deployment.

Frontend Implementation

The dispatch HTML file (/tools/shipcaptaincrew/index.html, ~2463 lines in production) needed a "Log Payment" modal following the existing pattern used by other administrative modals in the application.

Key JavaScript functions added:

  • openPaymentModal(eventId, patronId, patronName) — Triggered from event roster card when crew member clicks "Log Payment"
  • submitPaymentLog() — Posts payment confirmation to Lambda via apiFetch() helper
  • renderPaymentCard() — Updates the patron card UI to show payment status after submission

The modal displays patron name, event date, and amount owed (pulled from event data), then sends a POST request to the new Lambda endpoint. The pattern mirrors existing modals (waiver confirmation, attendance marking) by using the active CSS class for visibility control and apiFetch() for authenticated requests.

Infrastructure Changes

CloudFront Distribution: During reconnaissance, we identified that payment-related routes were being caught by a catch-all S3 origin behavior, causing them to fall through to the dispatch SPA instead of routing to the Lambda Function URL.

Updated CloudFront cache behaviors for the shipcaptaincrew distribution:

  • /api/* → Lambda Function URL origin (existing, confirmed working)
  • /g/* → Lambda Function URL origin (for event details, waivers, payment endpoints)

This ensures that requests for payment endpoints hit the Lambda function before falling back to S3-hosted dispatch HTML.

Lambda Deployment: The updated lambda_function.py was packaged and deployed using the standard zip workflow:

# Build the deployment package
zip -r lambda_deployment.zip lambda_function.py

# Update Lambda code (via AWS CLI equivalent commands)
aws lambda update-function-code \
  --function-name shipcaptaincrew \
  --zip-file fileb://lambda_deployment.zip

Environment variables including Gmail credentials were merged into the existing Lambda config before code deployment, ensuring backward compatibility with production variables.

S3 & CloudFront Invalidation: The updated dispatch HTML was deployed to the production S3 bucket at s3://shipcaptaincrew-bucket/ with corresponding CloudFront cache invalidation for /_staging/* during staging validation, then to production paths after confirmation.

Key Decisions & Rationale

Why Environment Variables for Gmail Credentials: Rather than hardcoding credentials or managing a separate secrets manager integration, Gmail service account credentials were stored as Lambda environment variables (encrypted at rest by AWS). This leverages existing infrastructure without adding operational complexity while maintaining the security profile of the deployment.

Why POST for Payment Logging: Following REST conventions, logging a payment is a state change (idempotent within a window), so POST was chosen over PUT. The handler includes timestamp tracking to prevent double-logging within the same minute.

Why Modal UI Pattern: Payment logging is an administrative action that should be explicit and confirmable. The modal pattern (consistent with existing waiver/attendance modals) ensures crew members see what they're confirming before submission.

CloudFront Routing Refinement: The discovery of the waiver endpoint falling through to S3 revealed a gap in the cache behavior hierarchy. Adding explicit /g/* behavior to Lambda origin (not just /api/*) prevents future route registration issues and aligns with the URL structure used by the application.

Testing & Validation

Staging deployment followed these steps:

  • Deploy updated Lambda code to production function (keeping env vars intact)
  • Deploy updated HTML to S3 staging prefix and validate via staging CloudFront URL
  • Test admin login via new /admin/login endpoint
  • Confirm /api/events endpoint responds with patron data including payment fields
  • Verify modal opens, submits, and email notification sends
  • Check Lambda logs for errors during request processing

All smoke tests passed with 200 responses from Lambda routes and logs confirming Gmail message queue submissions.

What's Next

Once crew members have confirmed this is working in their workflow, the following enhancements are candidates for future iterations:

  • Batch payment logging (mark multiple patrons as paid in one action)
  • Payment receipt generation and PDF delivery to patrons
  • Payment history audit trail with crew member attribution
  • Integration with external payment processors (Stripe, PayPal) for automated reconciliation

The current implementation provides the minimal viable feature: crew members can confirm patron payment, patrons receive notification, and payment status persists in DynamoDB for reporting.

```