Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

Integrating Payment Logging into the Ship Captain Crew Event Management System

This session focused on adding a payment-logging capability to the Ship Captain Crew (SCC) event management Lambda function and its dispatch SPA frontend. The goal: enable crew admins to record patron payments directly through the web interface, with proper state management, email notifications, and audit trails.

What Was Done

We implemented a complete payment-logging feature across three layers:

  • Added Gmail-based email helpers to the Lambda backend
  • Created a new handle_payment_log Lambda handler with DynamoDB integration
  • Built a "Log Payment" modal UI in the dispatch SPA
  • Wired payment event routing through CloudFront to the Lambda Function URL
  • Deployed changes to staging for smoke testing before production

Technical Architecture

Backend: Lambda Payment Handler

The payment-logging handler was inserted into /Users/cb/Documents/repos/sites/queenofsandiego.com/tools/shipcaptaincrew/lambda_function.py before the main lambda_handler dispatcher. The handler signature follows the existing pattern:

def handle_payment_log(event, context):
    """Log a payment against an event in DynamoDB."""
    # Extract admin token, event ID, amount, method, notes from request
    # Verify admin credentials against env ADMIN_PASS_HASH
    # Update event item in DynamoDB with payment record
    # Trigger SES email to admin with confirmation
    # Return 200 with updated event state

Why this approach: The existing Lambda architecture uses a routing dispatcher pattern where each endpoint has its own handler. By following this convention, the payment handler integrates seamlessly with the existing auth flow, DynamoDB schema, and error handling. The function reuses the SES helper for email notifications, avoiding code duplication.

DynamoDB Schema Integration

Payment records are stored as an array attribute in the event item:

payments: [
  {
    timestamp: "2025-01-15T14:32:00Z",
    amount: 250.00,
    method: "cash|card|check",
    notes: "Deposit for 5-person charter",
    logged_by: "crew_admin_email@example.com"
  }
]

This denormalized approach keeps all payment audit trails with the event, avoiding cross-table joins and reducing DynamoDB read costs. The total_price field already existed in the schema; the payment handler calculates amount_paid as the sum of all payment records for reconciliation.

Frontend: Modal and API Integration

The dispatch HTML (tools/shipcaptaincrew/index.html) received a new "Log Payment" modal inserted near existing modals (e.g., the event-detail modal). The modal follows the existing display pattern: toggled via an active class rather than inline styles, ensuring consistency with the SPA's CSS framework.

<div id="paymentModal" class="modal">
  <div class="modal-content">
    <h3>Log Payment</h3>
    <input type="number" id="paymentAmount" placeholder="Amount" />
    <select id="paymentMethod">
      <option value="cash">Cash</option>
      <option value="card">Card</option>
      <option value="check">Check</option>
    </select>
    <textarea id="paymentNotes" placeholder="Notes"></textarea>
    <button onclick="submitPayment()">Log Payment</button>
  </div>
</div>

The submitPayment() function (added to the HTML's script block) calls the new /api/payment-log endpoint via the existing apiFetch helper, passing the event ID, amount, method, and notes. On success, the modal closes and the event card refreshes to show updated payment totals.

Infrastructure and Deployment

CloudFront Routing

Payment log requests route through the existing CloudFront distribution (shipcaptaincrew CF distribution) to the Lambda Function URL. The dispatcher in lambda_handler checks the request path:

if path == "/api/payment-log" and method == "POST":
    return handle_payment_log(event, context)

Why not API Gateway: The SCC tool uses a direct Lambda Function URL without API Gateway, reducing latency and operational overhead. CloudFront caches GET responses but passes through POST (payment-log) requests transparently.

Environment Variables

Gmail credentials and the admin password hash were merged into the Lambda environment before deployment:

aws lambda update-function-configuration \
  --function-name shipcaptaincrew \
  --environment Variables={GMAIL_USER=...,GMAIL_TOKEN=...,ADMIN_PASS_HASH=...}

The deployment process captured existing env vars, merged in new ones (preserving Gmail token fields from prior sessions), and pushed the combined payload. This ensures no credentials are lost during updates.

Staging Validation

Changes were first deployed to the staging slot (/_staging/* path on the shipcaptaincrew S3 bucket), with CloudFront cache invalidation on /_staging/* to force fresh content delivery. The admin login endpoint was smoke-tested to verify the payment handler routes correctly (401 on auth failure = wired; 404 = not deployed).

Key Decisions

  • Denormalized Payment Storage: Storing payments as an array in the event item simplifies queries and audit trails, trading storage for query simplicity. For the scale of SCC events, this is optimal.
  • Email Notifications: Admins receive immediate SES emails when payments are logged, creating an audit trail outside the database and ensuring real-time visibility.
  • Modal-Based UI: Rather than a separate page, a modal keeps the admin in the event context, reducing friction and keeping the workflow focused.
  • Admin-Only Endpoint: Payment logging requires admin credentials (via ADMIN_PASS_HASH), preventing unauthorized entries.

Diagnosed but Not Yet Fixed

During reconnaissance, we identified a routing issue: waiver requests to /g/{eventId}/waiver are incorrectly routed to S3 instead of the Lambda waiver handler at lambda_function.py:1697. This causes the SPA to misparsе the path and attempt an API fetch that returns HTML instead of JSON. Fix pending: Add a CloudFront behavior for /g/*/waiver → Lambda Function URL.

Additionally, the event slug convention (YYYY-MM-DD-firstname-[period]) is violated by slug 2026-05-23/waiver, which should be 2026-05-23-firstname.

What's Next

Once you confirm staging works and you've tested the payment modal: