Add interactive "How Snowplow works" walkthrough

[Greg Thomson (gthomson31)]

Summary

Adds a new docs page at /docs/how-it-works/ with an embedded interactive demo that walks a single event through the full Snowplow pipeline. Aimed at both technical evaluators and less-technical buyers — it tells the value story visually instead of asking them to read the architecture page cold.

Highlights:

• Animated event traverses Track → Collect → Validate → Enrich → Load → Model
• Live JSON payload grows on the left, pipeline log streams on the right
• "Send an invalid event" demonstrates the schema-violation path into the RT Bad Stream with a structured failure reason
• Pipeline diagram visually reinforces the "in your cloud account" boundary plus named RT Good / RT Bad streams and the Iglu Schema Registry — matching the framing used in docs/fundamentals/
• Each stage card and the track itself are clickable scrubbers after a run — click any step to revisit its JSON + log state
• Light theme, flat outlined SVG icons (no emojis, no external icon CDN), inherits the docs theme
• Page lives in the docs sidebar (sidebar_position: 1.5) so the rest of the docs nav is always one click away
• Homepage gains a CTA card linking to the walkthrough

Files

• static/demo/how-it-works.html — the demo asset (single file, no dependencies, also embeds an auto-resize postMessage so the iframe fits its content)
• src/components/ResizingIframe.tsx — Docusaurus-friendly height-fitting iframe wrapper that listens for those resize messages
• docs/how-it-works/index.md — short MDX wrapper with title, lede, and the embedded demo
• docs/introduction.md — adds a CTA card on the docs homepage

Test plan

• yarn start — page loads at http://localhost:3000/docs/how-it-works/
• Docs sidebar visible; How Snowplow works highlighted between Get started and Fundamentals
• Click Send a valid event — token traverses Track → Model, JSON grows with each stage, log streams 12 entries, final latency shown
• Click Send an invalid event — token stops at Validate with bad styling, log shows schema-violation messages, JSON shows a structured failure record
• After a run, click any stage card or any position on the track — token jumps to that step and JSON + log replay the state at that point
• Stage hover/active styling renders correctly
• Page resizes responsively (≤1000 px collapses the cloud-stages grid; ≤560 px stacks them)
• CTA card on /docs/ links here
• Standalone demo accessible at /demo/how-it-works.html (works without docs chrome — useful for embeds elsewhere)

Notes / follow-ups

• Demo is intentionally a standalone HTML file so it can also be hosted externally or embedded in Console without dragging Docusaurus along.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
❌ Deployment failed View logs	documentation	a1d869e	May 18 2026, 08:43 AM

[Greg Thomson (gthomson31)]

Claude (@claude)

[claude]

Style review

Most of this PR is the standalone HTML demo, but the user-facing copy still needs to follow the style guide. Suggestions, grouped by file:

docs/how-it-works/index.md

• Marketing tone in the lede. CLAUDE.md says "Never use marketing language. Use professional, technical tone." Snowplow Customer Data Infrastructure captures every customer interaction… and Watch a single event travel from a tracker call to a warehouse row below… read as marketing copy. Suggest something like:

  Snowplow CDI validates and enriches every event you track, then delivers it to your warehouse, lake, or stream in real time. The walkthrough below sends a single event through each stage of the pipeline, with the JSON payload and pipeline log updating at every step.

  Also note introduction.md uses Snowplow CDI in its description; using the same short form here keeps the homepage and the linked page consistent.

• Link out to fundamentals. The lede only links to events. The demo also explains entities, schemas, and failed events — all concepts that live in /docs/fundamentals/. Per the style guide ("Link to concepts in /docs/fundamentals/. Never re-explain them inline."), add inline links to:

  • entities
  • schemas
  • failed events

• Mention both buttons. The paragraph only references Send a valid event. Since the demo also surfaces Send an invalid event, mention it too — it's how readers discover the failed-events path.

docs/introduction.md

• CTA description — Watch a single event travel from tracker to warehouse, with live JSON, validation, and enrichment at each step. Same marketing-tone issue as above. A more technical phrasing, e.g. Send a single event through every pipeline stage and inspect the JSON payload, validation result, and enrichments at each step.

static/demo/how-it-works.html

• `entity` vs `context`. CLAUDE.md: "Use 'entity', never 'context'."

  • …self-describing event data and entity contexts. → …self-describing event data and entities.
  • The contexts array carries entities… — since contexts here is the literal JSON field name, wrap it in code formatting (<code>contexts</code>) and rephrase, e.g. `The <code>contexts</code> array carries entities…` — so the term-of-art entity does the conceptual work and contexts is clearly a field name.

• Emojis. CLAUDE.md: "Only use emojis if the user explicitly requests it." Several appear in user-facing copy:

  • Button labels: ▶ Send a valid event, ✗ Send an invalid event — drop the glyphs, the buttons are visually distinct already.
  • Pipeline log: ❌ schema validation FAILED and ✓ schema validated… — replace with plain words (FAIL / OK) or rely on the existing bad/good tag colors.

• Inconsistent stream naming. The page uses RT Good stream, RT Bad stream, failed events stream, and Failed events stream interchangeably. Pick one form and use it everywhere. The rest of the docs (e.g. docs/fundamentals/index.md) say Real-Time Good Stream / Real-Time Bad Stream and failed events — matching that is the safest call. The RT abbreviation isn't used elsewhere in the docs.

• Heading voice. Style guide prefers imperative voice for headings. A few section headings read as labels rather than actions:

  • Anatomy of a Snowplow event — fine as a noun phrase here.
  • Where events come from / Where data lands — could become See where events come from / See where data lands, though these are acceptable as informational.
  • Signals — real-time attributes — consider Serve real-time attributes with Signals (also moves the product name out of an em-dash chip).

• Stage <h3>s — 1. Track, 2. Collect, …: visual numbering is fine for the demo, but if you want them to read as sentence-case docs headings, drop the leading digits and rely on the ordered layout for sequence.

• Minor copy nits:

  • Twenty-plus tracker SDKs exist, all wire-compatible. — most numerals elsewhere in the docs use digits; 20+ tracker SDKs… is more consistent with surrounding tech-doc style.
  • Pipeline in your cloud account · AWS · GCP · Azure — middle-dot list inside a single label is unusual for these docs. Consider Pipeline runs in your cloud (AWS, GCP, or Azure).
  • Schema Registry (Iglu) in the schema chip is inverted from how the rest of the docs refer to it. Use Iglu Schema Registry to match.
  • agentic applications in the Signals bullets reads marketing-y; the surrounding bullets are factual, so something like AI agents and assistants keeps the register consistent.

Nothing here is a blocker — the page is a strong concept and the structure follows the style guide well. The changes above are mostly about leaning further into the docs' technical voice and tightening the few places the demo drifts into marketing tone.

[Nick (stanch)]

How was this produced, and how will we maintain it?