Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Building HELM: An Interactive Operations Topology Map for Multi-Platform Booking Systems

Over the course of a focused development session, we designed and deployed HELM—a self-contained, browser-based interactive operations graph for Queen of San Diego. HELM visualizes the entire booking funnel from traffic source through crew dispatch, money flow across booking platforms, and real-time system health. This article walks through the architecture, infrastructure decisions, and technical patterns that make HELM a production-ready operational dashboard.

What Was Built

HELM is a single-file HTML application deployed to helm.queenofsandiego.com that renders a force-directed physics graph using the vis-network library. The application:

  • Displays 40+ nodes representing booking platforms, marketing channels, GAS backends, ops dashboards, and crew management systems
  • Shows edges (connections) between source channels → website → booking platforms → ops systems → crew dispatch
  • Includes a drill-down detail panel that lists all GAS function signatures for any selected node
  • Implements live health diagnostics with node glow status (green = healthy, red = unhealthy)
  • Provides a system health bar at the top showing aggregate operational status
  • Uses dark navy/gold styling for visual polish

Technical Architecture

Data Structure and Node Taxonomy

The application uses a NODE_DATA constant that categorizes all system components:

// Categories represented in HELM:
// - traffic_source: email campaigns, organic search, referral partners
// - booking_platform: Viator, Boatsetter, GetMyBoat, and greyed-out planned platforms
// - website: main landing/booking flow
// - backend_service: Google Apps Script endpoints (crew dispatch, expense tracking, etc.)
// - ops_dashboard: operational tools for managing sails, crew, finances
// - crew_system: crew dispatch, crew contact management

Each node includes metadata: category, health probe endpoint, GAS function signature list, and description. Edges define parent→child relationships representing data flow and dependency chains.

Health Diagnostics System

HELM polls health endpoints asynchronously. For nodes backed by GAS or cloud infrastructure, it evaluates node.glow color (0-2 scale) based on recent probe results:

// Pseudo-implementation of health check polling:
// - Each node has optional healthProbeUrl
// - Polling interval: 30 seconds
// - Failed probe → node.color.highlight = red
// - Healthy probe → node.color.highlight = green
// - System health bar aggregates: (healthy_count / total_count) * 100

Drill-Down Detail Panel

When a user clicks a node, a right-side panel appears listing all GAS function signatures for that system. This required extracting function definitions from multiple GAS files—for example, from gas_crewdispatch.gs, gas_expense_tracker.gs, and others. The signatures are embedded directly in the NODE_DATA constant, making HELM entirely self-contained with no external API calls required for function discovery.

Infrastructure and Deployment

S3 and CloudFront Setup

HELM was deployed to a new S3 bucket: helm.queenofsandiego.com. The deployment process:

  1. Created S3 bucket with no public ACL; access restricted via CloudFront Origin Access Control (OAC)
  2. Uploaded index.html to S3 root with Content-Type: text/html
  3. Created CloudFront distribution with OAC policy linking to the S3 bucket
  4. Set S3 bucket policy to allow only CloudFront OAC principal to read objects
  5. Created Route53 ALIAS record pointing helm.queenofsandiego.com to the CloudFront distribution domain

The OAC pattern (rather than legacy Origin Access Identity) ensures that the S3 bucket is never directly accessible over HTTP—all traffic flows through CloudFront, enabling cache invalidation, DDoS protection, and geo-distribution.

Cache Invalidation Strategy

After each deployment iteration, the CloudFront distribution cache was invalidated using the wildcard pattern /* to ensure browsers fetch the latest index.html. This is especially important during development when node definitions, GAS function signatures, or health probe logic changes frequently.

Key Implementation Decisions

Why Self-Contained HTML + Embedded Data

Rather than building a multi-file React/Vue application with separate API backends, HELM was written as a single index.html file with embedded <style> and <script> blocks. This decision was made to:

  • Minimize dependencies: Only vis-network library loaded from CDN; all other logic is vanilla JavaScript
  • Simplify deployment: One file to upload to S3; no build step required
  • Improve resilience: Even if external CDNs are slow, the page renders immediately with cached vis-network
  • Enable offline operation: Engineers can download and run locally if needed

Why Force-Directed Physics Graph

The vis-network library provides automatic node layout using force-directed simulation (Barnesut algorithm). This was chosen over manual static coordinates because:

  • New nodes and edges can be added without manual layout adjustment
  • Relationships become visually apparent through proximity and clustering
  • Engineers unfamiliar with the system can explore and discover dependencies organically

Embedded GAS Function Signatures

Rather than querying Google Apps Script or a separate API for function definitions, all GAS function signatures were extracted ahead of time and embedded in NODE_DATA. This was decided because:

  • Function signatures rarely change; updates are infrequent
  • Embedding reduces load-time latency (no external HTTP round-trip)
  • The detail panel is purely informational; it doesn't need real-time data

Development Process and Debugging

The development session involved iterative refinement across several areas:

  • Syntax validation: Ran JavaScript parser checks before each S3 upload to catch errors before CloudFront distribution
  • Network verification: Extracted function signatures from 10+ GAS files across the JADA ecosystem and cross-referenced against NODE_DATA to ensure all backend services were represented
  • Health probe integration: Reviewed existing health endpoints used by the progress dashboard and integrated similar patterns into HELM
  • CSS refinement: Iterated on dark navy/gold color scheme and panel styling to ensure professional appearance suitable for sharing with engineers at top firms

What's Next

HELM is now live at helm.queenofsandiego.com and provides a working foundation for operational visibility. Future enhancements may include:

  • Real-time revenue tracking overlay showing money flow from booking platforms through settlement
  • Historical timeline view showing which booking sources drove revenue on specific dates
  • Drill-down into individual crew dispatch