Astound Google Review Tracker - Technical Documentation

Overview

The Astound Google Review Tracker is a Single Page Application (SPA) designed to track, visualize, and benchmark Google Review ratings for Astound Broadband locations across multiple regions. It uses a Serverless Architecture to securely fetch data from the Yext API while serving the frontend as static assets.

System Architecture

Frontend (Client-Side)

• Technology: HTML5, CSS3 (Vanilla), JavaScript (Vanilla).
• Files:
  • index.html: Main dashboard structure, styles, and embedded chart logic.
  • dynamic.js: Handles data fetching, dashboard population, and region management.
  • competitors.js: Stores static competitor benchmark data.
• Libraries:
  • Chart.js: For rendering trend graphs and rankings.
  • jsPDF / html2canvas: For export functionality.

Backend (Serverless)

• Technology: Netlify Functions (Node.js) or Google Cloud Functions (Python).
• Files:
  • serverless-function/netlify/functions/yext-proxy.js: Production proxy for Yext API calls.
  • cloud-function/main.py: Alternative Python-based proxy (Cloud Function).

how it Works (Data Flow)

1. User Access: User visits the deployed URL (frontend).
2. Initialization:
   • index.html loads.
   • Scripts dynamic.js and competitors.js are executed.
   • window.REGIONS is initialized with location metadata (Entity IDs, Addresses).
3. Data Fetching:
   • dynamic.js calls populateDashboard().
   • Iterate through each region and location.
   • Frontend makes an async request to the caching proxy:

     GET /.netlify/functions/yext-proxy?entityId={ID}&maxDate={DATE}
     

4. API Proxy:
   • The Netlify Function (yext-proxy.js) receives the request.
   • It retrieves the YEXT_API_KEY (from Env Vars or fallback).
   • It forwards the request to the official Yext API:

     GET https://api.yextapis.com/v2/accounts/me/reviews
     

5. UI Update:
   • JSON data is returned to the frontend.
   • dynamic.js parses the rating.
   • The dashboard DOM is updated dynamically with the new values and color-coded styles.
6. Competitor Data:
   • competitors.js injects hardcoded benchmark data (Xfinity, Spectrum, etc.) into the grid alongside live Astound data.

Visual Flow Chart

sequenceDiagram
    participant User
    participant Browser (dynamic.js)
    participant Proxy (Netlify Function)
    participant YextAPI
    participant StaticData (competitors.js)

    User->>Browser: Opens Dashboard
    Browser->>StaticData: Load Competitor Data (Hardcoded)
    Browser->>Browser: Render Dashboard Structure
    loop For Each Location & Month
        Browser->>Proxy: Fetch Rating (EntityID, Date)
        Proxy->>YextAPI: Request Review Data (with Secret Key)
        YextAPI-->>Proxy: Return JSON Data
        Proxy-->>Browser: Return JSON Data
        Browser->>Browser: Update Table Cell
    end
    Browser->>User: Display Full Report

Simplified Data Flow

graph TD
    %% Nodes
    Browser[("Browser / Dashboard\n(User Interface)")]
    StaticData[("Static Files\n(Competitors.js & Locations)")]
    Proxy[("Netlify Serverless Function\n(Security Layer)")]
    Yext[("Yext API\n(Live Astound Reviews)")]

    %% Styles
    style Browser fill:#f9f,stroke:#333,stroke-width:2px
    style StaticData fill:#eee,stroke:#333,stroke-width:1px
    style Proxy fill:#bbf,stroke:#333,stroke-width:1px
    style Yext fill:#bfb,stroke:#333,stroke-width:1px

    %% Connections
    Browser -- "1. Loads hardcoded data directly" --> StaticData
    Browser -- "2. Requests review data" --> Proxy
    Proxy -- "3. Authenticates with API Key" --> Yext
    Yext -- "4. Returns live ratings" --> Proxy
    Proxy -- "5. Returns data to dashboard" --> Browser

Data Sources

API Key Management & Configuration Locations

CRITICAL: There are several locations where API keys are defined. For the application to work securely and correctly, you must update these locations or ensure Environment Variables are set.

1. Yext API Key

Used to authenticate with Yext to get review data.

• Production (Netlify Function):

  • File: serverless-function/netlify/functions/yext-proxy.js
  • Line 35: const YEXT_API_KEY = process.env.YEXT_API_KEY || "a4b10...";
  • Action Required: Set YEXT_API_KEY in Netlify Site Settings. Warning: The current code contains a hardcoded fallback key that should be removed for security.

• Alternative (Google Cloud Function):

  • File: cloud-function/main.py
  • Line 34: YEXT_API_KEY = "a4b10..."
  • Action Required: If using this backend, replace the hardcoded string with an environment variable retrieval.

• Frontend (Legacy/Dev):

  • File: dynamic.js
  • Line 4: const YEXT_API_KEY = "YOUR_YEXT_API_KEY_HERE";
  • Note: This variable is defined but seemingly overridden/unused in favor of the proxy URL.

2. Google Maps API Key

Intended for fetching competitor data, but currently unused by the active logic.

• Frontend:
  • File: competitors.js
  • Line 5: const GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY_HERE";
  • Status: Inactive. The code currently uses a hardcoded list of ratings (COMPETITOR_MAPPINGS on line 9).
  • Action Required: If dynamic competitor tracking is desired, competitors.js must be rewritten to actually fetch data using this key.

Updating the App

To Add/Remove Locations:

Edit dynamic.js and modify the REGIONS object.

'Texas': {
    manager: 'Name',
    locations: [
           { address: '...', city: '...', entityId: 'NEW_ID' }
    ]
}

To Update Competitor Data:

Edit competitors.js and manually update the ratings in COMPETITOR_MAPPINGS.

'City-State': {
    verizon: { address: '...', rating: 4.5 }, // Update this value
    // ...
}