Catalyst

Slack emoji reaction leaderboard.

Built as a Bun workspaces monorepo:

Package	Description	Deployed to
packages/worker	Hono API + Slack event handler (CF Worker)	catalyst.scstem.tech/api/*
packages/web	React frontend (CF Pages)	catalyst.scstem.tech

Stack: Cloudflare Workers + D1, Hono, slack-cloudflare-workers, React 19, TanStack Router + Query, TailwindCSS v4

Prerequisites

• Bun (v1.3+)
• mise — task runner and env loader
• A Cloudflare account
• A Slack workspace you can create apps in

Quick start (local dev)

# 1. Install dependencies
bun install

# 2. Create your local secrets file
cp mise.local.toml.example mise.local.toml

# 3. Create + migrate the local D1 database
mise run db:migrate

# 4. Run the worker + web dev servers
mise run dev

# 5. Open the site. The AccessGate takes password **`000000`** by default.

The UI will look empty until you've imported some Slack data — see Backfill historical data below.

Environment variables

Variable	Why	Default
SITE_PASSWORD	AccessGate password prompt	000000 (in mise.toml)
TURNSTILE_SECRET_KEY	Validates captcha token server-side	CF test secret (in mise.toml)
VITE_TURNSTILE_SITE_KEY	Frontend captcha widget	Frontend falls back to CF test site key
SLACK_BOT_TOKEN	Backfill script, /api/slack/events, /backfill workflow	—
SLACK_SIGNING_SECRET	/api/slack/events signature verification	—
CLOUDFLARE_API_TOKEN	mise run deploy:* and remote db:migrate/backfill	—

Set up a Slack app

Skip this section if you're only doing frontend or read-API work — the AccessGate, charts, and rankings all work without Slack once you've got data in D1.

1. Go to api.slack.com/apps → Create New App → From scratch
2. Name it whatever you want and pick your workspace

Bot token scopes

Under OAuth & Permissions, add these Bot Token Scopes:

Scope	Used for
reactions:read	Receiving reaction events
chat:write	Bot messages (backfill status, slash command responses)
commands	Slash commands (/catalyst, /backfill)
channels:history	Backfill: reading message history
groups:history	Backfill: private channel history
channels:read	Backfill: listing channels
groups:read	Backfill: listing private channels
users:read	Fetching user profiles (display names + avatars)
emoji:read	Fetching custom emoji images

Event subscriptions

Under Event Subscriptions:

1. Toggle Enable Events on
2. Set the Request URL to your deployed worker (e.g. https://catalyst.scstem.tech/api/slack/events)
3. Subscribe to bot events: reaction_added, reaction_removed

Slash commands

Create two commands, both pointing at /api/slack/events:

Command	Description
/catalyst	Ping the Catalyst bot
/backfill	Backfill emoji reactions for this channel

The shared endpoint is fine — the slack-cloudflare-workers SDK dispatches by payload type.

Install + grab credentials

• OAuth & Permissions → Install to Workspace → copy the Bot User OAuth Token (xoxb-…)
• Basic Information → App Credentials → copy the Signing Secret

Put both in mise.local.toml as SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET.

Backfill historical data

The backfill task pulls all existing reactions from Slack into D1 and rebuilds the aggregate tables.

mise run backfill              # local D1 (default)
mise run backfill staging      # remote: staging D1
mise run backfill prod         # remote: production D1

Requires SLACK_BOT_TOKEN in mise.local.toml. Remote targets also need CLOUDFLARE_API_TOKEN and a clean git working directory.

Optional cutoff: BACKFILL_SINCE=2025-01-01 mise run backfill (ISO date).

The bot must be invited to any channels you want to backfill (/invite @YourBotName).

For on-demand single-channel backfills, use the /backfill slash command inside Slack — it triggers a Cloudflare Workflow that pages through the channel's history with automatic retries.

Pull remote data into local D1

To work against real data locally, pull a snapshot of a remote D1 into your local one:

mise run db:pull               # from staging (default)
mise run db:pull prod          # from production (requires confirmation)

This wipes the local D1 state, imports the remote dump (schema + data), then re-applies migrations so any unreleased schema changes are reapplied on top. Requires CLOUDFLARE_API_TOKEN.

Deploying

See DEPLOY.md for:

• First-time Cloudflare setup (D1 databases, Pages project, production secrets, environment variables)
• Day-to-day deploy commands and safety guardrails
• Infrastructure overview

Production secrets are managed via wrangler secret put — separately from your local mise.local.toml.

Architecture

┌──────────────────┐     POST /api/slack/events  ┌─────────────────────┐
│   Slack Events   │ ──────────────────────────► │  slack-cloudflare-  │
│   API            │                             │  workers SDK        │
└──────────────────┘                             │  (sig verification, │
                                                 │   challenge, parse) │
                                                 └────────┬────────────┘
                                                          │
                                                          ▼
                                                 ┌─────────────────────┐
                                                 │  addReaction() /    │
                                                 │  removeReaction()   │
                                                 │  → D1 batch write   │
                                                 └─────────────────────┘

┌──────────────────┐     GET /api/*              ┌─────────────────────┐
│   React frontend │ ──────────────────────────► │  Hono app           │
│   (hono/client)  │ ◄────────────────────────── │  → Drizzle → D1     │
└──────────────────┘     JSON (type-safe RPC)    └─────────────────────┘