Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Implementing Deep-Link Navigation and Orchestrator Reporting for Multi-Platform Analytics Audit

Over the past development session, we implemented a comprehensive Google Analytics audit pipeline with orchestrator-driven reporting and dashboard deep-linking capabilities. This post covers the technical architecture, infrastructure decisions, and integration patterns that enable real-time operational visibility across multiple platforms.

What Was Done

  • Established hash-based deep-link routing on the progress dashboard at progress.queenofsandiego.com
  • Built an automated GA code audit across all site HTML files to identify tracking gaps
  • Created an orchestrator-driven pipeline that pulls 30-day GA traffic data and generates actionable reports
  • Implemented card-based dashboard output for urgent operational items (Mother's Day blast approval, Paul Simon proof deadline, GA API access)
  • Integrated Constant Contact campaign audit with email operational excellence recommendations

Technical Details: Dashboard Deep-Link Architecture

The progress dashboard implements hash-based navigation rather than query parameters, enabling direct deep links to specific kanban cards without server-side routing complexity. The URL format follows this pattern:

https://progress.queenofsandiego.com/#card-{cardId}

Card IDs are generated with a timestamp prefix (e.g., t-31aa2593). The JavaScript event listener in the dashboard monitors the hashchange event and renders the appropriate card view. This pattern was chosen because:

  • Client-side routing — avoids unnecessary server requests and reduces latency for card navigation
  • Bookmarkable state — users can share deep links directly in Slack or email without losing context
  • No backend routing required — the dashboard is a single-page application (SPA) served as static assets from CloudFront
  • Compatible with existing deployment — no changes needed to Route53 or API Gateway rules

The implementation checks the hash on page load and on every hashchange event, extracting the card ID and fetching metadata from the card storage service. This enables real-time linking to live audit results without manual URL construction.

GA Code Audit Pipeline Architecture

The audit system operates in two phases:

Phase 1: Static Code Scan

We built a file traversal script that recursively searches all HTML templates and static pages across these primary paths:

  • /Users/cb/Documents/repos/web/templates/ — main website HTML templates
  • /Users/cb/Documents/repos/email/templates/ — email campaign templates (Constant Contact exports)
  • /Users/cb/Documents/repos/dashboard/ — progress dashboard static assets

For each file, the audit checks for the presence of Google Analytics tracking code patterns:

gtag('config', 'GA_MEASUREMENT_ID')
analytics.page()
_gaq.push(['_trackPageview'])

Files without tracking code are flagged as gaps and included in the final report. This approach catches missing instrumentation before code reaches production.

Phase 2: Orchestrator-Driven Data Pull and Reporting

The orchestrator service consumes the audit results and triggers a multi-step workflow:

  • Google Analytics Data API call — fetches last 30 days of pageviews, sessions, and users dimensions grouped by pagePath and source/medium
  • Constant Contact API integration — lists all scheduled campaigns and their send status (approved, scheduled, paused)
  • Report synthesis — cross-references GA gaps with traffic data to prioritize which pages need tracking most urgently
  • Dashboard card generation — outputs findings as structured kanban cards on the progress board

Card t-31aa2593 went live at https://progress.queenofsandiego.com/#card-t-31aa2593 with five sections covering code gaps, traffic patterns, campaign status, and operational recommendations.

Infrastructure and Service Account Configuration

A critical finding emerged during the audit: no Google Analytics Data API access existed for the service account. This was a zero-credential-refresh scenario.

The fix involved two steps:

  1. Grant service account to GA Admin — In Google Analytics Admin console, add the service account email to the appropriate property's user list with "Editor" role. This must be the service account email from the Google Cloud project JSON key file (format: *@*.iam.gserviceaccount.com), not a user email.
  2. Verify API is enabled — Confirm Google Analytics Data API v1 is enabled on the Google Cloud project. This can be verified via gcloud services list --enabled or the Cloud Console.

The reauth pattern used for this is stored in /Users/cb/Documents/repos/tools/reauth_ga.py, which handles OAuth token refresh for CLI-based GA queries. The script uses the existing OAuth flow and caches tokens in the Claude project memory directory to avoid repeated user prompts.

Key Decisions and Why

Orchestrator-First Reporting

Rather than building a custom reporting UI, we delegated report generation to the existing orchestrator service. Why: The orchestrator already has integrations with GA API, Constant Contact API, and the dashboard card service. Adding a new reporting feature would require duplicating this integration logic. Delegating to orchestrator follows the single-responsibility principle and keeps the codebase DRY.

Hash-Based Deep Links Over Query Parameters

We chose hash-based routing (#card-id) instead of query parameters (?card=id). Why: Query parameters require server-side logic to resolve and can be lost if the page reloads at the wrong moment in an SPA. Hash navigation is handled entirely on the client, survives page reloads, and is the standard SPA pattern. It also matches the existing dashboard navigation scheme.

Card-Based Output for Operational Items

Urgent findings (Mother's Day blast unapproved, Paul Simon proof deadline, GA API access) were surfaced as kanban cards rather than console logs or email alerts. Why: The team uses the progress dashboard as the single source of truth for operational status. Cards are visible at a glance, can be assigned, and include deep links for context. This prevents important items from getting buried in chat or email threads.

Urgent Operational Items Identified

The audit surfaced three needs-you items that require immediate attention:

  1. Mother's Day Emergency Blast — Scheduled for April 29 (4 days out). Campaign is prepared but unapproved in Constant Contact. Requires stakeholder sign-off on email subject and recipient list before send date.
  2. Paul Simon Blast Proof — Proof needed by May 12 (6 days out). Template is ready; proof send must be prepared and delivered to CB for review before campaign goes to production list.
  3. GA API Access Gap — Service account needs Editor role on GA property. This is a 3-minute fix in GA Admin console but blocks all programmatic traffic reporting.

What's Next