feat(workshop): add Polymarket analytics track

.github/workflows/workshop.yml

@@ -43,13 +43,25 @@ jobs:
           cache-dependency-path: |
             workshops/build_workshop/app/backend/requirements.txt
             workshops/build_workshop/app/backend/requirements-dev.txt
+            workshops/build_workshop/polymarket/collector/requirements.txt
+            workshops/build_workshop/polymarket/collector/requirements-dev.txt
 
       - name: Run backend tests
         working-directory: workshops/build_workshop/app/backend
         run: |
           python -m pip install -r requirements-dev.txt
           python -m pytest tests/test_chat_guardrails.py tests/test_db_retry.py tests/test_cloud_defaults.py ../loadgen/test_config.py -q
 
+      - name: Run Polymarket collector tests
+        working-directory: workshops/build_workshop/polymarket/collector
+        run: |
+          python -m pip install -r requirements-dev.txt
+          python -m pytest -q
+
+      - name: Run Polymarket ClickHouse integration
+        working-directory: workshops/build_workshop
+        run: ./polymarket/test-clickhouse.sh
+
       - name: Run RTA dashboard tests
         working-directory: workshops/RTA-mini-workshop/dashboard
         run: python -m pytest test_app.py -q
@@ -73,6 +85,8 @@ jobs:
         env:
           NEXT_PUBLIC_BASE_PATH: ""
           NEXT_PUBLIC_SITE_URL: https://workshop.demohouse.cloud
+          NEXT_PUBLIC_WORKSHOP_ENV: dev
+          NEXT_PUBLIC_WORKSHOP_BRANCH: dev-build-workshop-v1
           NEXT_TELEMETRY_DISABLED: "1"
         run: npm run build -- --webpack
 
@@ -102,6 +116,8 @@ jobs:
           cache-dependency-path: |
             workshops/build_workshop/app/backend/requirements.txt
             workshops/build_workshop/app/backend/requirements-dev.txt
+            workshops/build_workshop/polymarket/collector/requirements.txt
+            workshops/build_workshop/polymarket/collector/requirements-dev.txt
 
       - name: Run backend tests on Windows
         working-directory: workshops/build_workshop/app/backend
@@ -110,6 +126,13 @@ jobs:
           python -m pip install -r requirements-dev.txt
           python -m pytest tests/test_chat_guardrails.py tests/test_db_retry.py tests/test_cloud_defaults.py ../loadgen/test_config.py -q
 
+      - name: Run Polymarket collector tests on Windows
+        working-directory: workshops/build_workshop/polymarket/collector
+        shell: pwsh
+        run: |
+          python -m pip install -r requirements-dev.txt
+          python -m pytest -q
+
       - name: Run RTA dashboard tests on Windows
         working-directory: workshops/RTA-mini-workshop/dashboard
         shell: pwsh
@@ -163,10 +186,12 @@ jobs:
             echo "instance_id=${PROD_INSTANCE_ID}" >> "${GITHUB_OUTPUT}"
             echo "image_alias=prod" >> "${GITHUB_OUTPUT}"
             echo "url=https://workshop.demohouse.cloud" >> "${GITHUB_OUTPUT}"
+            echo "workshop_env=prod" >> "${GITHUB_OUTPUT}"
           else
             echo "instance_id=${DEV_INSTANCE_ID}" >> "${GITHUB_OUTPUT}"
             echo "image_alias=dev" >> "${GITHUB_OUTPUT}"
             echo "url=https://dev-workshop.demohouse.cloud" >> "${GITHUB_OUTPUT}"
+            echo "workshop_env=dev" >> "${GITHUB_OUTPUT}"
           fi
           test -n "$(sed -n 's/^instance_id=//p' "${GITHUB_OUTPUT}")"
 
@@ -192,11 +217,15 @@ jobs:
           REPOSITORY: posthouse-demo-workshop
           IMAGE_ALIAS: ${{ steps.target.outputs.image_alias }}
           SITE_URL: ${{ steps.target.outputs.url }}
+          WORKSHOP_ENV: ${{ steps.target.outputs.workshop_env }}
+          WORKSHOP_BRANCH: ${{ github.ref_name }}
         run: |
           docker buildx build \
             --platform linux/arm64 \
             --build-arg NEXT_PUBLIC_BASE_PATH= \
             --build-arg NEXT_PUBLIC_SITE_URL="${SITE_URL}" \
+            --build-arg NEXT_PUBLIC_WORKSHOP_ENV="${WORKSHOP_ENV}" \
+            --build-arg NEXT_PUBLIC_WORKSHOP_BRANCH="${WORKSHOP_BRANCH}" \
             --tag "${REGISTRY}/${REPOSITORY}:${GITHUB_SHA}" \
             --tag "${REGISTRY}/${REPOSITORY}:${IMAGE_ALIAS}" \
             --push \
@@ -272,6 +301,7 @@ jobs:
       - name: Verify public routes
         env:
           SITE_URL: ${{ steps.target.outputs.url }}
+          WORKSHOP_ENV: ${{ steps.target.outputs.workshop_env }}
         run: |
           set -euo pipefail
 
@@ -306,10 +336,21 @@ jobs:
             return 1
           }
 
-          for path in / /build-workshop /rta-mini/index.html /docs/learner/00-setup /docs/learner/07-break-and-fix /docs/learner/08-chat-langfuse; do
+          routes=(/ /build-workshop /rta-mini/index.html /docs/ai-sre /docs/polymarket /docs/polymarket/learner/00-setup /docs/polymarket/instructor /docs/learner/00-setup /docs/learner/07-break-and-fix /docs/learner/08-chat-langfuse)
+          if [[ "${WORKSHOP_ENV}" == "dev" ]]; then
+            routes+=(/docs/polymarket/rehearsal)
+          fi
+          for path in "${routes[@]}"; do
             probe_route "${path}"
           done
 
+          if [[ "${WORKSHOP_ENV}" == "prod" ]]; then
+            rehearsal_status=$(curl --show-error --silent \
+              --output /dev/null --write-out '%{http_code}' \
+              "${SITE_URL}/docs/polymarket/rehearsal")
+            test "${rehearsal_status}" = "404"
+          fi
+
       - name: Deployment summary
         env:
           SITE_URL: ${{ steps.target.outputs.url }}

README.md

@@ -8,6 +8,7 @@ Collection of ClickHouse demo projects showcasing various features and patterns.
 | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | [Incremental Materialized Views](./incremental_materialized_views/) | Progressive tutorial from basic MVs to full Medallion Architecture                     |
 | [Telco Marketing Analytics](./agent_stack_builds/telco_marketing/)  | AI-powered telco analytics stack with LibreChat, ClickHouse MCP, LiteLLM, and Langfuse |
+| [ClickHouse Cloud Workshops](./workshops/build_workshop/)           | AI SRE and Polymarket real-time analytics tracks built on ClickHouse Cloud             |
 
 ## Getting Started
 

workshops/build_workshop/README.md

@@ -1,18 +1,23 @@
-# ClickHouse BUILD Workshop ("Build AI with AI")
+# ClickHouse Cloud use-case workshops
 
-A three-hour, hands-on workshop: participants use their own agentic coding tool to take
-an NYC-taxi ride-hailing analytics app end to end on ClickHouse Cloud — CDC ingestion
-with ClickPipes, conversational BI with ClickHouse Agents, observability with ClickStack
-(including an AI-built SRE dashboard), a break-and-fix incident lab diagnosed by an AI
-SRE, and an in-app AI chat traced to Langfuse Cloud.
+This site now carries two dedicated use cases:
+
+- **AI SRE with NYC taxi data:** the existing three-hour application, managed Postgres
+  CDC, Agents, ClickStack, incident diagnosis, and Langfuse journey under `app/`.
+- **Polymarket real-time analytics:** a two-hour public market-data stream, typed
+  ClickHouse model, one-minute aggregate, investigation, and Cloud dashboard under
+  `polymarket/`.
+
+Both tracks support macOS and Windows through Ubuntu on WSL 2. ClickHouse Cloud is the
+only ClickHouse server; no local database substitute is part of either track.
 
 Learners clone the repository, then switch to `build-workshop-v1`. Maintainers create a
 feature branch, open a PR to protected `dev-build-workshop-v1`, verify
 [dev-workshop.demohouse.cloud](https://dev-workshop.demohouse.cloud), then promote
 `dev-build-workshop-v1` to protected `build-workshop-v1` for
 [workshop.demohouse.cloud](https://workshop.demohouse.cloud).
 
-## Architecture
+## AI SRE architecture
 
 The app edge runs on the participant's laptop. ClickHouse, Postgres, ClickPipes, and
 ClickStack/HyperDX live in ClickHouse Cloud; OpenAI and Langfuse are separate hosted
@@ -121,7 +126,8 @@ flowchart LR
 | Path | What |
 |---|---|
 | `app/` | The local application edge: React frontend, FastAPI backend, managed-Postgres data generator, and stateless ClickStack OTel forwarder. All databases and product UIs are cloud-hosted. Workshop entrypoint: `preflight.sh` + `docker-compose.workshop.yml` + `.env.workshop.example`. |
-| `playbook/` | The published follow-along playbook (Next.js + Fumadocs; dual learner/instructor tracks plus self-paced and troubleshooting pages; deploys to workshop.demohouse.cloud). Requires Node >= 22.12 to build. |
+| `polymarket/` | Public Polymarket collector, ClickHouse schema/reference queries, fixture mode, Docker Compose entrypoint, and tests. The only Compose service is the stateless collector. |
+| `playbook/` | The published workshop catalog and dedicated AI SRE / Polymarket learner and instructor tracks. Requires Node >= 22.12 to build. |
 | `docs/` | `diagrams/` — the platform, architecture, data-flow, and module-flow SVGs, generated by `gen_diagrams.py`. |
 | `infra/` | Instructor tooling via clickhousectl: the demo stack end-to-end run and a cloud-hosted managed-Postgres fallback pool for participants whose orgs cannot create one. |
 
@@ -138,7 +144,7 @@ The learner playbook lists the branch names and the observable symptom of each f
 diagnosis paths and fixes live in the playbook's instructor track (module 07) and are
 deliberately not documented in this directory.
 
-## Quick start (participant)
+## AI SRE quick start
 
 ```bash
 git clone <this-repo>
@@ -152,3 +158,18 @@ docker compose --env-file .env.workshop -f docker-compose.workshop.yml up -d
 
 Then follow the playbook from module 00 (or the self-paced page if no instructor is
 around).
+
+## Polymarket quick start
+
+```bash
+git clone <this-repo>
+cd ClickHouse_Demos
+git switch build-workshop-v1
+cd workshops/build_workshop/polymarket
+cp .env.polymarket.example .env.polymarket
+set -a; source ./.env.polymarket; set +a
+./preflight.sh
+```
+
+Then start at `/docs/polymarket/learner/00-setup`. Learners create the schema from
+copyable SQL on the site before starting the collector.

workshops/build_workshop/playbook/Dockerfile

@@ -25,8 +25,12 @@ FROM node:22-slim AS builder
 WORKDIR /app
 ARG NEXT_PUBLIC_BASE_PATH=
 ARG NEXT_PUBLIC_SITE_URL=https://dev-workshop.demohouse.cloud
+ARG NEXT_PUBLIC_WORKSHOP_ENV=prod
+ARG NEXT_PUBLIC_WORKSHOP_BRANCH=build-workshop-v1
 ENV NEXT_PUBLIC_BASE_PATH=$NEXT_PUBLIC_BASE_PATH
 ENV NEXT_PUBLIC_SITE_URL=$NEXT_PUBLIC_SITE_URL
+ENV NEXT_PUBLIC_WORKSHOP_ENV=$NEXT_PUBLIC_WORKSHOP_ENV
+ENV NEXT_PUBLIC_WORKSHOP_BRANCH=$NEXT_PUBLIC_WORKSHOP_BRANCH
 ENV NEXT_TELEMETRY_DISABLED=1
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .

workshops/build_workshop/playbook/README.md

@@ -1,13 +1,15 @@
-# ClickHouse BUILD Workshop playbook
+# ClickHouse Cloud workshop playbook
 
-The published playbook for the ClickHouse BUILD Workshop ("Build AI with AI"): a
-three-hour, hands-on session where participants use their own agentic coding tool to take
-an NYC-taxi ride-hailing analytics app end to end on ClickHouse Cloud.
+The published playbook offers two dedicated ClickHouse Cloud use cases:
 
-This directory is the documentation site only. The workshop app that participants clone
-and build on lives alongside it at `workshops/build_workshop/app` in this repository, on
-the `build-workshop-v1` branch. The site is built with [Next.js](https://nextjs.org)
-and [Fumadocs](https://fumadocs.dev). Production is
+- **AI SRE:** a three-hour NYC-taxi application, observability, incident, and traced-chat track.
+- **Polymarket:** a two-hour public market-data stream, real-time aggregate, investigation, and Cloud dashboard track.
+
+This directory is the documentation site only. The AI SRE application lives at
+`workshops/build_workshop/app`; the Polymarket collector and SQL assets live at
+`workshops/build_workshop/polymarket`. Learner materials use the `build-workshop-v1`
+branch. The site is built with [Next.js](https://nextjs.org) and
+[Fumadocs](https://fumadocs.dev). Production is
 [workshop.demohouse.cloud](https://workshop.demohouse.cloud); dev is
 [dev-workshop.demohouse.cloud](https://dev-workshop.demohouse.cloud).
 
@@ -62,21 +64,27 @@ the recommended Node deployment redirects those paths to their new module number
 
 ## Content authoring
 
-All content is MDX under `content/docs/`. The site is dual-track: every module has a
-Learner page and an Instructor page.
+All content is MDX under `content/docs/`. Each use case has learner and instructor
+tracks with a shared module sequence.
 
 ```
 content/docs/
-  index.mdx                # the overview (hero, tracks, scope, modules table, ...)
-  meta.json                # top-level ordering: index, learner, instructor
+  index.mdx                # use-case selector and shared platform contract
+  ai-sre.mdx               # AI SRE landing page; legacy module URLs stay valid
+  meta.json                # top-level ordering and navigation groups
   learner/
-    meta.json              # root:true -> Learner track tab; orders the modules
-    index.mdx              # track landing
+    meta.json              # AI SRE learner track; orders the modules
+    index.mdx              # AI SRE learner landing
     00-setup.mdx ... 09-wrap-up.mdx
   instructor/
-    meta.json              # root:true -> Instructor track tab; orders the modules
-    index.mdx              # run of show + shared-resource checklist
+    meta.json              # AI SRE instructor track; orders the modules
+    index.mdx              # AI SRE run of show + shared-resource checklist
     00-setup.mdx ... 09-wrap-up.mdx
+  polymarket/
+    index.mdx              # Polymarket use-case landing
+    rehearsal.mdx          # dev-only maintainer rehearsal
+    learner/               # 00-setup ... 07-wrap-up + troubleshooting
+    instructor/            # matching 00-setup ... 07-wrap-up run of show
 ```
 
 - Ordering is controlled by the `pages` array in each `meta.json` (file basenames,
@@ -104,7 +112,7 @@ Desktop WSL integration; it does not mean translating shared Bash blocks into Po
 - Keep shell scripts LF-only. The Windows CI job enforces the platform contract and builds
   the complete playbook on a Windows runner.
 
-### The per-module learner contract
+### The AI SRE per-module learner contract
 
 Every learner module page follows this skeleton, in order:
 

workshops/build_workshop/playbook/content/docs/ai-sre.mdx

@@ -0,0 +1,29 @@
+---
+title: AI SRE track
+description: The existing three-hour NYC taxi application, observability, incident, and AI workflow.
+---
+
+Build a real-time NYC taxi application on ClickHouse Cloud, stream changes from managed
+Postgres with ClickPipes, observe the app with ClickStack, diagnose a fault with an AI
+SRE workflow, and trace the application chat with Langfuse.
+
+## Choose your role
+
+<Cards>
+  <Card title="AI SRE learner" href="/docs/learner" description="Follow the hands-on modules from setup through wrap-up." />
+  <Card title="AI SRE instructor" href="/docs/instructor" description="Use the run of show, failure recovery, and facilitator notes." />
+</Cards>
+
+## Outcome
+
+In about three hours you build and verify:
+
+- a ClickHouse Cloud analytics service with millions of taxi rows;
+- managed Postgres CDC through ClickPipes;
+- ClickHouse Agents over the operational data;
+- application traces and logs in Managed ClickStack;
+- an AI-assisted SRE dashboard, alert, and incident diagnosis; and
+- an in-app AI chat traced in Langfuse Cloud.
+
+The existing learner and instructor URLs remain unchanged so saved links continue to
+work.