Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building HELM: A Real-Time Operations Graph for Multi-Platform Booking Management

Overview: Why We Built This

Queen of San Diego's booking ecosystem spans multiple platforms (Viator, Boatsetter, GetMyBoat), email campaigns, web searches, and referral partners. Money flows in, clients book, crew gets dispatched, and operations run across dozens of interconnected systems. There was no single place to see the entire flow—from visitor acquisition through crew dispatch and payment reconciliation.

We built HELM (a self-contained HTML application deployed to helm.queenofsandiego.com) to visualize this entire operation as an interactive, force-directed graph. Engineers can now drill down from high-level booking funnels into specific GAS function calls, crew dispatch workflows, and payment flows.

What HELM Does

  • System Map: 30+ nodes representing booking platforms, email campaigns, web search, crew dispatch, payment processors, and operational dashboards
  • Real-Time Health: Nodes glow green or red based on live probes hitting Google Apps Script endpoints
  • Drill-Down Details: Click any node to see the underlying GAS function signatures, error rates, and last execution time
  • Greyed-Out Futures: Platforms like GetMyBoat show as inactive nodes, making roadmap visibility clear
  • Money Flow Tracking: Separate view showing how revenue flows from booking platforms into the accounting system

Technical Architecture

File Structure

/Users/cb/Documents/repos/sites/helm/index.html

HELM is deployed as a single, self-contained HTML file (~45KB minified). This approach offers several advantages:

  • No build step: HTML, CSS, and JavaScript are inline; changes deploy instantly
  • Fast cold starts: One HTTP request, one S3 GET, one CloudFront cache hit
  • Easy versioning: The entire application is a single git-tracked file
  • Portable: Can be tested locally before deployment

Graph Library: vis-network

We use vis-network (CDN: https://cdn.jsdelivr.net/npm/vis-network@9.1.9/dist/vis-network.min.js) for force-directed physics simulation. This library was chosen because:

  • Physics engine automatically spaces nodes to prevent overlap
  • Built-in pan/zoom and click detection
  • Lightweight compared to D3.js for this use case
  • Fast rendering of 30–50 nodes in a browser

Node and Edge Data Structure

The application defines two core data structures:

const NODE_DATA = {
  'email_campaigns': {
    label: 'Email Campaigns',
    group: 'acquisition',
    gasFunction: 'sendCampaignBatch',
    description: 'Outbound email to subscriber list...'
  },
  'viator_platform': {
    label: 'Viator',
    group: 'booking_platforms',
    url: 'https://viator.com',
    active: true
  },
  // ... 30+ nodes
};

const EDGES = [
  { from: 'email_campaigns', to: 'web_checkout', label: 'Click-through', weight: 10 },
  { from: 'web_checkout', to: 'stripe_processor', label: 'Payment', weight: 5 },
  // ... 40+ edges
];

Nodes are grouped by category (acquisition, booking_platforms, dispatch, dashboards, money_flow). Edges represent data or money flow between systems.

Health Diagnostics

HELM polls a health-check endpoint every 30 seconds to determine node status. The health check function (deployed via Google Apps Script) returns:

  • Status of each system (up/down)
  • Last execution timestamp
  • Error count in the past 24 hours

Nodes render with color coding:

  • Green: Healthy, executed successfully in past 24h
  • Red: Error state or no recent execution
  • Grey: Inactive platform (not yet deployed)
  • Gold/Silver: Acquisition and operational nodes

Infrastructure Setup

S3 Bucket Creation

aws s3api create-bucket \
  --bucket helm.queenofsandiego.com \
  --region us-west-2

The bucket was created with default private ACLs. A bucket policy was added to allow CloudFront to read objects via Origin Access Control (OAC).

CloudFront Distribution

A new CloudFront distribution was created with:

  • Origin: helm.queenofsandiego.com.s3.us-west-2.amazonaws.com
  • Origin Access Control (OAC): Allows CloudFront to sign requests, avoiding public bucket ACLs
  • Default Root Object: index.html
  • Cache Behavior: 1-hour TTL for index.html; 24-hour TTL for assets
  • Compression: Enabled for text/html and application/javascript

The distribution ID and domain name were captured for Route53 aliasing and deployment scripts.

DNS and SSL

A Route53 ALIAS record was created:

helm.queenofsandiego.com → d1234abcd.cloudfront.net (CloudFront domain)

SSL certificate via ACM (existing wildcard or dedicated) covers the subdomain. HTTPS is enforced via CloudFront viewer protocol policy.

Deployment Pipeline

A shell script handles deployment:

#!/bin/bash
aws s3 cp /Users/cb/Documents/repos/sites/helm/index.html \
  s3://helm.queenofsandiego.com/index.html \
  --content-type text/html \
  --cache-control "max-age=3600"

aws cloudfront create-invalidation \
  --distribution-id D1ABC2DEF3GHI \
  --paths "/*"

After each deployment, CloudFront invalidation ensures edge nodes refresh within seconds.

Key Design Decisions

1. Self-Contained Single File

Rather than build a multi-file SPA (Single Page Application) with bundling, we embedded CSS and JavaScript directly. This reduces complexity and deployment friction for internal tools.

2. Client-Side Graph Rendering

The graph is rendered entirely in the browser using vis-network. This keeps the backend lightweight and allows operators to interact with the visualization in real-time without round-trips to a server.