Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Building HELM: An Interactive Operations Graph for Multi-Channel Revenue & Dispatch Management

Queen of San Diego's business spans multiple revenue channels—Viator, Boatsetter, GetMyBoat, organic web traffic, email campaigns, referral codes—and each path eventually funnels into a complex ops system that manages crew dispatch, client communication, and financial tracking. Understanding this system required a tool that could visualize the entire flow in one interactive interface. That tool is HELM: a self-contained, physics-based operations map deployed to helm.queenofsandiego.com.

The Problem: System Complexity Without Visibility

JADA's business model is inherently non-linear. A visitor might arrive via Google search, Viator listing, email newsletter, or partner referral code. They book through different platforms. Money flows through different payment processors and reconciliation paths. Once booked, the ops team manages crew dispatch via Google Apps Script cloud functions, sends templated emails through SES, tracks expenses in a spreadsheet, and logs health metrics across multiple dashboards.

Without a unified view, it's easy to miss dependencies: Which GAS function fires when a Viator booking arrives? How does crew dispatch relate to the email template system? Where does the money trail actually go? HELM answers these questions by mapping the entire system as an interactive, drill-downable graph.

Architecture: Vis-Network Force-Directed Graph

HELM uses vis-network, a physics-based graph visualization library, to render nodes (systems, platforms, functions, dashboards) and edges (data flows, dependencies, money movement). The graph runs client-side in a single HTML file—no backend needed—making it fast, deployable anywhere, and easy to iterate on.

The core structure:

  • Nodes: Visitor acquisition channels (Organic Search, Email Campaigns, Referral Partners), booking platforms (Viator, Boatsetter, GetMyBoat), payment processors, the core JADA system, ops dashboards, crew dispatch, and finance tracking
  • Edges: Directional flows showing how data and money move between systems
  • Node Categories: Color-coded by function (Acquisition, Platform, Payment, Core System, Ops, Finance, Crew, etc.)
  • Live Health Probes: Node glow colors (green/red/grey) indicate system health or deployment status
  • Detail Panel: Click any node to see associated GAS functions, dashboards, or metadata

File location: /Users/cb/Documents/repos/sites/helm/index.html (1800+ lines of self-contained HTML, CSS, and JavaScript).

Data Ingestion: Extracting System Architecture

Building HELM required comprehensive system archaeology. The development session extracted function signatures from key Google Apps Script files across the JADA ecosystem:

  • gas_bookings: Handles booking intake, platform routing, data normalization
  • gas_crewdispatch: Crew assignment, scheduling, conflict detection
  • gas_emails: Template rendering, SES integration, campaign triggers
  • gas_expenses: Cost tracking, line-item reconciliation, profit calculations
  • gas_health: System monitoring, uptime tracking, alerting
  • gas_stripe / gas_payments: Payment processing, reconciliation

Each GAS file was parsed to extract function definitions, their parameters, and expected data flows. These became edges in HELM's graph. For example:


// Pseudo-code: Function signature extraction
// Input: gas_crewdispatch.gs
// Extract: assignCrew(sailId, crewRoles, availabilityConstraints)
// Output: Edge from "Bookings" → "Crew Dispatch" labeled "assignCrew()"

Infrastructure: S3 + CloudFront + Route53

HELM is deployed as a static site—a single HTML file served via CloudFront with an S3 origin and custom domain via Route53.

S3 Bucket:

  • Bucket name: helm.queenofsandiego.com (exact domain match for CloudFront OAC setup)
  • Region: us-west-2 (consistent with existing JADA infrastructure)
  • Versioning: Enabled (safe rollback if needed)
  • Block Public Access: All enabled (CloudFront OAC handles access)

CloudFront Distribution:

  • Origin: S3 bucket helm.queenofsandiego.com via Origin Access Control (OAC)
  • Default Root Object: index.html
  • Cache Behavior: TTL 3600 seconds (1 hour); shorter TTL for rapid iteration
  • Invalidation: Automated on deploy via CloudFront distribution invalidation API
  • SSL/TLS: ACM certificate for helm.queenofsandiego.com (existing certificate reused from wildcard or subdomain pool)

Route53 ALIAS Record:


Name: helm.queenofsandiego.com
Type: A (IPv4 ALIAS)
Alias Target: CloudFront distribution domain
Evaluate Target Health: false (CloudFront health is implicit)

Deployment workflow: Write/edit /Users/cb/Documents/repos/sites/helm/index.html → Syntax check → Upload to S3 → Invalidate CloudFront distribution → Smoke test via helm.queenofsandiego.com.

Key Design Decisions

1. Single HTML File vs. SPA Framework
HELM is a single self-contained HTML file (~50KB gzipped) rather than a React/Vue SPA. Why? Speed of iteration, zero build step, easy version control diffing, and no dependency management overhead. Vis-network is already bundled via CDN; all business logic is vanilla JavaScript. For a visualization tool used internally by 3-5 people, this is optimal.

2. Force-Directed Physics Layout
Vis-network's physics engine automatically arranges nodes so dependencies cluster together visually. This makes the system architecture immediately intuitive: acquisition channels cluster on the left, core booking logic in the middle, ops/dispatch on the right, finance/reporting at the bottom. No manual layout needed; the graph self-organizes.

3. Live Health Probes
Nodes glow green (healthy), red (down), or grey (not yet probed). Health is determined by periodic CORS-safe HTTP GET requests to status endpoints or CloudFront health checks. This gives ops a real-time heartbeat of the entire system without needing a separate monitoring dashboard.

4. Drill-Down Detail Panel
Clicking any node displays associated metadata: linked GAS functions, related dashboards, file paths, and data ownership. This bridges the gap between high-level system architecture and implementation details. An engineer can understand the flow at 10,000 feet, then dive into specific functions in seconds.

What's Next

Phase 2 will add:

  • Real-time money flow visualization with transaction volumes
  • Crew availability and capacity as dynamic node attributes