The Trinity Beast — Website Analytics Guide

1. Overview

The Website Analytics system provides lightweight, privacy-first analytics for the CPMP website. It tracks page views and user interaction events without cookies, fingerprinting, or collecting any personally identifiable information (PII). All data stays in Aurora PostgreSQL within the project's AWS account — no third-party services involved.

What It Tracks

• Page views — path, title, referrer, screen dimensions, anonymous visitor/session IDs, country (from CloudFront header)
• Interaction events — video plays, map pin clicks, document library clicks, CTA button clicks, general link clicks
• Aggregated reporting — top pages, daily trends, referrer sources, event breakdowns, map pin click heatmaps, document popularity

Key Principles

• Privacy-first: No cookies, no PII, no fingerprinting, no third-party services. GDPR/CCPA compliant without consent banners.
• Lightweight: Single 2KB JS snippet, fire-and-forget beacon requests. Zero impact on page load performance.
• Self-hosted: All data stored in Aurora PostgreSQL within the AWS account. No data leaves the infrastructure.
• Server-validated: Event types are whitelisted server-side. All input fields are truncated to prevent abuse.

System Components

2. Architecture

The analytics system follows a simple ingest-store-query pattern. The client-side beacon fires page views and events to two public endpoints on the LPO server. The server validates, truncates, and inserts directly into Aurora PostgreSQL. The admin endpoint runs aggregation queries on demand — no pre-computed materialized views, no caching layer, no background jobs.

Why No Cache Layer?

Analytics queries hit Aurora directly rather than ElastiCache. The data volume is low (website traffic, not API usage logs), the queries are simple aggregations with time-range filters, and the indexes are purpose-built. Adding a cache layer would add complexity without meaningful performance gain at current scale.

Data Flow

flowchart LR
    A["🌐 Browser
analytics.js"] -->|"sendBeacon / fetch
POST JSON"| B["⚡ LPO Server
analytics.go"]
    B -->|"INSERT"| C["🗄️ Aurora PostgreSQL
page_views + page_events"]
    C -->|"SELECT aggregations"| D["🔒 Admin Endpoint
GET /admin/page-analytics"]
    D -->|"JSON response"| E["📊 TBCC Dashboard
+ KCC CLI"]

    style A fill:#1e3a5f,stroke:#60a5fa,color:#e2e8f0
    style B fill:#064e3b,stroke:#10b981,color:#e2e8f0
    style C fill:#334155,stroke:#FF9900,color:#e2e8f0
    style D fill:#4c1d95,stroke:#a855f7,color:#e2e8f0
    style E fill:#78350f,stroke:#f59e0b,color:#e2e8f0
      

Request Path Detail

3. Client-Side Beacon (analytics.js)

The tracking snippet is a self-contained IIFE with zero dependencies. It lives at cpmp-redesign/js/analytics.js and is included on every page via a <script> tag before the closing </body>.

Visitor & Session Identity

Transport

• Primary: navigator.sendBeacon(url, blob) — survives page unload, non-blocking, fire-and-forget
• Fallback: fetch(url, { method: 'POST', keepalive: true }) — for browsers without sendBeacon support
• Failure handling: Silent. If the request fails, it's dropped. No retries, no queuing, no error callbacks.

Auto Page View

On every page load, analytics.js automatically sends a page view with:

Public API: tbTrack()

For interaction events, pages call the global tbTrack function:

// Signature
window.tbTrack(eventType, target, data)

// eventType — one of: video_click, map_pin_click, doc_click, cta_click, link_click
// target   — what was clicked (string)
// data     — optional object with additional context

Usage Examples

// Map pin click (from map.html)
tbTrack('map_pin_click', 'Lahore Medical Camp', {
  impact_type: 'medical-camps',
  media_type: 'video'
});

// Video play (from index.html)
tbTrack('video_click', 'hero-video', { duration: '2:30' });

// Document library click
tbTrack('doc_click', 'Trinity-Beast-API-Reference');

// CTA button click
tbTrack('cta_click', 'join-us-hero');

Including on a Page

<!-- Place before closing </body> tag, after i18n.js -->
<script src="js/i18n.js"></script>
<script src="js/analytics.js"></script>

Beacon Lifecycle

sequenceDiagram
    participant B as Browser
    participant JS as analytics.js
    participant LS as localStorage
    participant SS as sessionStorage
    participant API as LPO Server
    participant DB as Aurora PostgreSQL

    B->>JS: Page loads, IIFE executes
    JS->>LS: getItem('tb_vid')
    alt Visitor ID exists
        LS-->>JS: Return existing ID
    else First visit
        JS->>LS: setItem('tb_vid', 'v_...')
    end
    JS->>SS: getItem('tb_sid')
    alt Session ID exists
        SS-->>JS: Return existing ID
    else New tab
        JS->>SS: setItem('tb_sid', 's_...')
    end
    JS->>API: sendBeacon POST /analytics/pageview
    API->>DB: INSERT INTO page_views
    Note over B,JS: Later — user clicks map pin
    B->>JS: tbTrack('map_pin_click', ...)
    JS->>API: sendBeacon POST /analytics/event
    API->>DB: INSERT INTO page_events
      

4. Database Schema

Both tables are auto-created at server startup via MigrateAnalyticsTables() in analytics.go. The migration is idempotent — safe to run on every deploy. All CREATE TABLE and CREATE INDEX statements use IF NOT EXISTS.

page_views

page_events

Indexes (6 total)

5. Event Types & Validation

The server validates incoming events against a whitelist of known types. Any event_type not in this list is rejected with 400 Bad Request. To add a new event type, update the validTypes map in analytics.go and redeploy.

6. API Endpoints

Three endpoints power the analytics system. Two are public (no auth, fire-and-forget) and one is admin-protected.

POST /analytics/pageview

Auth: None — public, fire-and-forget

Records a single page view. Called automatically by analytics.js on every page load.

Request Body

Server-added fields (not in request body):

• user_agent — extracted from the HTTP User-Agent request header (truncated to 1000 chars)
• country — extracted from CloudFront-Viewer-Country header, with X-Country as fallback

Response: 200 OK

{"recorded": "ok"}

POST /analytics/event

Auth: None — public, fire-and-forget

Records a user interaction event. Called via tbTrack() in client code.

Request Body

Response: 200 OK

{"recorded": "ok"}

Error responses:

• 400 — Missing page_path or event_type, or unknown event_type
• 500 — Database insert failure

GET /admin/page-analytics

Auth: X-Admin-Key header required

Returns aggregated analytics data for the specified time period. Runs 8 SQL queries against Aurora and returns a single JSON response.

Query Parameters

Example Request

curl -s -H "X-Admin-Key: <admin-key>" \
  "https://api.cpmp-site.org/admin/page-analytics?days=30"

7. Admin Response Reference

The GET /admin/page-analytics endpoint returns a JSON object with 10 top-level fields. Each field is the result of a separate SQL aggregation query.

Response Structure

{
  "status": "✅ [LPO] [us-east-2] [BeastMirror] [/admin/page-analytics] [200]",
  "status_code": 200,
  "endpoint": "/admin/page-analytics",
  "cluster_node": "BeastMirror",
  "region": "us-east-2",
  "timestamp": "2026-04-29T13:20:52Z",
  "data": {
    "period_days": 7,
    "total_views": 1234,
    "unique_visitors": 456,
    "total_events": 89,
    "top_pages": [ ... ],
    "daily_trend": [ ... ],
    "top_referrers": [ ... ],
    "events_by_type": [ ... ],
    "top_event_targets": [ ... ],
    "map_pin_clicks": [ ... ],
    "doc_clicks": [ ... ]
  }
}

Field Reference

SQL Queries Behind Each Field

8. Security & Abuse Prevention

The analytics endpoints are public (no auth) by design — the beacon must fire without API keys. Several server-side protections prevent abuse.

Input Truncation

Every string field is truncated to its maximum column length before insertion. This prevents oversized payloads from consuming storage or causing insert failures.

Event Type Whitelist

The /analytics/event endpoint validates event_type against a hardcoded map of allowed values. Unknown types return 400 Bad Request. This prevents arbitrary event injection.

Event Data Size Cap

The event_data JSONB field is validated in two ways:

• JSON validity: The raw bytes are unmarshaled to verify it's valid JSON. Invalid JSON is silently replaced with {}.
• Size cap: If the JSON exceeds 2000 bytes, it's replaced with {}. This prevents large payloads from inflating the JSONB column.

Required Field Validation

• /analytics/pageview — requires page_path (non-empty)
• /analytics/event — requires both page_path and event_type (non-empty)

Rate Limiting

9. Page Coverage

The analytics.js script is included on all public-facing pages. It is placed before the closing </body> tag, after i18n.js.

Pages with analytics.js

10. KCC & TBCC Integration

Website analytics data is accessible through two operational interfaces: the Kiro Command Center (KCC) CLI and the Trinity Beast Command Center (TBCC) web dashboard.

KCC — Command Line

The KCC verify script includes the page-analytics endpoint in its health check sweep:

# Full endpoint verification (includes page-analytics)
bash scripts/kcc.sh verify

# Direct curl for analytics data
curl -s -H "X-Admin-Key: <admin-key>" \
  "https://api.cpmp-site.org/admin/page-analytics?days=7" | python3 -m json.tool

# 30-day lookback
curl -s -H "X-Admin-Key: <admin-key>" \
  "https://api.cpmp-site.org/admin/page-analytics?days=30" | python3 -m json.tool

TBCC — Web Dashboard

The Page Analytics widget in the TBCC dashboard provides a visual interface for reviewing analytics data.

Period Selector

Four time periods available:

Dashboard Components

Public Analytics Dashboard

A standalone, no-auth analytics dashboard is available at cpmp-site.org/docs/analytics-dashboard.html. It provides:

• Summary view — traffic trend chart, interaction breakdown, traffic sources
• Pages & Reading view — top pages with dwell-time indicators (read vs scanned vs bounced), scroll depth funnel
• Interactions view — full detail table of every event type and target
• Patterns view — hourly activity heatmap (EST), visitor countries
• Global Reach view — Leaflet world map with country markers, reach statistics

The dashboard calls GET /analytics/summary?days=7 (public, no auth) and renders all data client-side. Period selector supports 24h, 7d, 14d, 30d, and 90d windows.

Public Endpoint

GET /analytics/summary?days=7

# Returns: total_views, unique_visitors, total_sessions, avg_dwell_seconds,
# daily_trend, top_pages (with avg dwell), events_by_type, top_targets,
# scroll_depth, top_referrers, countries, hourly_heatmap, dwell_by_page

Event Types Tracked

11. Privacy

The analytics system is designed with privacy as a core principle. It collects the minimum data needed for useful analytics without compromising visitor privacy.

What We Do NOT Do

• No cookies: Zero cookies are set. No cookie banners needed.
• No PII: No names, emails, IP addresses, or identifiable information is stored.
• No fingerprinting: No canvas fingerprinting, font enumeration, or device fingerprinting.
• No third-party services: No Google Analytics, no external tracking pixels, no CDN-hosted scripts.
• No cross-site tracking: Visitor IDs are scoped to the single domain only.
• No IP logging: IP addresses are never stored in the analytics tables.

What We Do

Data Residency

• All analytics data stays in Aurora PostgreSQL within the project's AWS account (us-east-2)
• No data is sent to external services or third parties
• No data sharing, selling, or exporting
• Data is retained indefinitely (no automatic purge — can be added if needed)