Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Building HELM: A Real-Time Interactive Operations Graph for SailJADA

Over the past development session, we built and deployed HELM — an interactive, drill-down operations visualization for SailJADA's entire business flow. This single-page application maps customer acquisition channels, revenue streams, booking pipelines, and crew dispatch operations into a force-directed graph with live health diagnostics. Here's how we engineered it.

What Was Built

HELM is a self-contained HTML file deployed to helm.queenofsandiego.com that visualizes SailJADA's complete operational topology:

  • Top of funnel: Email campaigns, organic web search, referral partner codes, and external booking platforms (Viator, Boatsetter, GetMyBoat)
  • Customer journey: Leads through each sales dashboard, conversion tracking, and booking completion
  • Revenue tracking: Commission flows from each platform, with greyed-out nodes for known-but-not-yet-live integrations
  • Operational execution: Crew dispatch, email sequences, call logs, and per-sail management workflows
  • Live health monitoring: Real-time status indicators on each node showing green/red health based on scheduled Google Apps Script probes

The visualization uses a physics-based force-directed layout (via vis-network) to keep related systems clustered while allowing interactive panning, zooming, and node drilling. A right-side detail panel shows function signatures and system metadata when nodes are clicked.

Technical Architecture

Visualization Engine

We chose vis-network (CDN-hosted from unpkg.com) for several reasons:

  • Physics simulation naturally clusters related systems without manual layout
  • Handles 30–50 node graphs with smooth interaction on modern browsers
  • Built-in zoom/pan prevents the "lost in space" feeling of large diagrams
  • Supports real-time node property updates (colors, glows, labels) without redraw latency

Alternative considered: D3.js. Rejected because HELM needed to be entirely self-contained in a single HTML file (no build step, no separate CSS/JS files) and D3's learning curve would have added unnecessary complexity for this use case.

Health Monitoring

Each major system node (email service, crew dispatch system, booking dashboards, etc.) has an associated Google Apps Script function that runs on a schedule. HELM queries a central GAS endpoint that aggregates health status from:

  • gas_email — checks SES queue and bounce logs
  • gas_crewdispatch — verifies the crew dispatch sheet is responsive and recent
  • gas_booking — checks if the booking dashboard's underlying data sources are fresh
  • gas_expense_tracker — validates expense reconciliation latency

Results are polled every 30 seconds. If a probe fails or returns stale data, its node glows red; healthy systems glow green. A system-wide health bar at the top shows aggregate health percentage.

File Structure and Deployment

Source

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

Single self-contained file (~50KB gzipped), containing:

  • Inline HTML structure with a canvas for vis-network and a detail sidebar
  • Embedded CSS (dark navy #0a1930, accent gold #d4af37, minimalist design)
  • Embedded JavaScript with node/edge definitions, physics config, health polling logic, and click handlers
  • Password gate (SHA-256 hashed) to prevent accidental exposure to non-technical stakeholders

Infrastructure: S3 + CloudFront + Route53

S3 Bucket Creation:

aws s3api create-bucket \
  --bucket helm.queenofsandiego.com \
  --region us-east-1

Bucket is private; public access is solely through CloudFront.

CloudFront Distribution:

Created Origin Access Control (OAC) to allow CloudFront to read from S3 without public bucket policy exposure. The distribution:

  • Points to helm.queenofsandiego.com.s3.us-east-1.amazonaws.com as origin
  • Default root object: index.html
  • Compression: enabled (gzip for HTML, CSS, JS)
  • TTL: 60 seconds (short, to pick up health updates rapidly)
  • SSL: ACM certificate for *.queenofsandiego.com (wildcard, reused from existing infrastructure)

Route53 ALIAS Record:

helm.queenofsandiego.com ALIAS → d<cloudfront-dist-id>.cloudfront.net

Standard pattern for CloudFront alias records; no additional CNAME needed.

Deployment Workflow

Each change cycle:

  1. Edit /Users/cb/Documents/repos/sites/helm/index.html locally
  2. Run syntax check (Node.js runtime eval with mock browser APIs)
  3. Upload to S3: aws s3 cp helm/index.html s3://helm.queenofsandiego.com/index.html --content-type text/html
  4. Invalidate CloudFront: aws cloudfront create-invalidation --distribution-id <dist-id> --paths "/*"
  5. Poll distribution until deployed (~2–3 minutes typically)
  6. Smoke test via CloudFront domain, then verify ALIAS record

Key Design Decisions

Single-File Architecture

We rejected a multi-file approach (separate CSS, JS, build step) because:

  • HELM is a diagnostic/ops tool, not a customer-facing product — fast iteration > perfect modularity
  • Single file = no cache busting complexity, no asset coordination issues
  • Can be version-controlled and deployed as a single atomic unit
  • Easier to audit security (all code in one place, simpler S3/CloudFront policy)

Force-Directed Physics Over Manual Layout

We chose vis-network's Barneshutt physics engine because manual node positioning would require:

  • Redesign every time the system topology changes (frequent at SailJADA)
  • Subjective decisions about spacing (who gets top-left vs. bottom-right?)
  • More code to maintain

Physics layout is self-documenting: nodes naturally cluster by connectivity, revealing system architecture organically.

Password Gate (SHA-256)

HELM contains business-sensitive data (revenue platform names, internal email addresses, crew dispatch systems). A simple SHA-256 check in the browser prevents casual discovery while acknowledging that determined actors can inspect the code. This