mirror of https://github.com/harvard-edge/cs249r_book.git synced 2026-05-08 02:28:25 -05:00

Files

Vijay Janapa Reddi 098f872821 feat(staffml): 8,891 Qs + backward design + math verification + A100 fix

Corpus: 8,891 published (87.8% validated). Backward design methodology.
A100 constants fixed (FP16: 156→312 TFLOPS). Math verification done.
New figures: backward design chain, applicability matrix. Bibliography
updated (Wiggins, Messick). Verification script added.

2026-04-01 23:53:38 -04:00

2.3 KiB

Raw Permalink Blame History

StaffML Analytics Worker

Lightweight Cloudflare Worker for collecting anonymous usage analytics from StaffML.

What It Collects

Anonymous events with no PII, no cookies, no persistent user IDs:

Question scores (topic, zone, level, track, score 0-3)
Gauntlet starts/completions
Issue reports and improvement suggestions
Daily challenge completions

Session IDs are ephemeral UUIDs that reset when the browser tab closes.

Setup

1. Install Wrangler

npm install -g wrangler
wrangler login

2. Create KV Namespace

cd interviews/staffml/analytics-worker
wrangler kv:namespace create STAFFML_ANALYTICS

Copy the returned namespace ID and update wrangler.toml:

[[kv_namespaces]]
binding = "STAFFML_ANALYTICS"
id = "<YOUR_KV_NAMESPACE_ID>"

3. Deploy

wrangler deploy

Note the URL (e.g., https://staffml-analytics.<your-subdomain>.workers.dev).

4. Configure StaffML

Set the analytics endpoint in your build environment:

# In the GitHub Actions workflow or .env.local:
NEXT_PUBLIC_ANALYTICS_URL=https://staffml-analytics.<your-subdomain>.workers.dev

Without this variable, analytics works in local-only mode (dashboard shows local data).

Endpoints

POST /

Accepts a batch of events:

{
  "events": [
    { "type": "question_scored", "topic": "roofline-analysis", "zone": "recall", "level": "L3", "track": "cloud", "score": 2, "_ts": 1712000000000, "_sid": "abc-123" }
  ]
}

Response: { "accepted": 1 }

GET /

Returns aggregate summary:

{
  "totalEvents": 1234,
  "last7Days": {
    "uniqueSessions": 42,
    "questionsScored": 380,
    "gauntletsCompleted": 15,
    "eventsByDay": { "2026-04-01": 50, ... },
    "scoresByLevel": { "L3": { "total": 120, "count": 50, "avg": "2.40" } }
  }
}

Security

CORS restricted to mlsysbook.ai, harvard-edge.github.io, and localhost
Max 100 events per request
Max 1KB per event
Email-pattern detection (rejects events containing PII)
Field allowlist (strips unknown fields)
90-day TTL on stored data
No authentication required (anonymous by design)

Data Retention

Events are stored with a 90-day TTL in Cloudflare KV. After 90 days, they are automatically deleted. The running event counter (meta:total_events) persists indefinitely.

2.3 KiB Raw Permalink Blame History