Backend-agnostic scheduling adapter hub. Currently bridges Acuity Scheduling via Playwright browser automation, with architecture designed to support additional scheduling backends.

Formerly acuity-middleware. Historical GitHub URLs may redirect, but the canonical repo is Jesssullivan/scheduling-bridge.

An HTTP server wrapping Playwright wizard flows that automate the Acuity booking UI. The bridge uses Effect TS for resource lifecycle management (browser/page acquisition and release).

HTTP Request
  -> server/handler.ts (route matching, auth, JSON serialization)
    -> acuity-service-catalog.ts (static env catalog -> BUSINESS -> scraper fallback)
    -> steps/ (Effect TS programs for each wizard stage)
      -> browser-service.ts (Playwright lifecycle via Effect Layer)
        -> selectors.ts (CSS selector registry with fallback chains)

• server/handler.ts -- Standalone Node.js HTTP server with Bearer token auth
• acuity-service-catalog.ts -- Shared service source order and cache for static config, BUSINESS extraction, and scraper fallback
• browser-service.ts -- Effect TS Layers for a warm shared browser process plus request-scoped page sessions
• acuity-wizard.ts -- Full SchedulingAdapter implementation (local Playwright or remote HTTP proxy)
• remote-adapter.ts -- HTTP client adapter for proxying to a remote middleware instance
• selectors.ts -- Single source of truth for all Acuity DOM selectors
• steps/ -- Individual wizard step programs plus BUSINESS extraction helpers
• acuity-scraper.ts -- Deprecated read fallback for services, dates, and time slots

GET /health is the stable downstream runtime-truth surface.

In addition to basic runtime data, it now publishes:

• release tuple:
  • releaseSha
  • releaseRef
  • releaseVersion
  • releaseBuiltAt
  • nested release.{ sha, ref, version, builtAt, modalEnvironment }
• protocol tuple:
  • protocolVersion
  • nested protocol.version
  • protocol.flowOwner = "scheduling-bridge"
  • protocol.backend = "acuity"
  • protocol.transport = "http-json"
  • protocol.endpoints
  • protocol.capabilities

Downstream apps should use this tuple to assert which bridge release and protocol surface they are talking to during beta validation and rollout claims.

This tuple is the supported runtime truth surface for adopters. Downstream apps should not infer bridge ownership from package metadata, branch names, or Modal dashboard state when /health is available.

The bridge emits NDJSON logs to stdout/stderr for runtime analysis.

• /health remains the authoritative runtime-truth surface for downstream apps
• request handlers emit request-scoped structured events, including requestId
• long-tail slot reads emit slot_read_profile events with phase timings
• SCHEDULING_BRIDGE_PROFILE_SLOT_READS=1 forces profile emission for all slot reads

pnpm install
pnpm dev           # Development with tsx against src/server/handler.ts
# or
pnpm build && pnpm start  # Materialize Bazel-derived dist/ and start it

docker build -t scheduling-bridge .
docker run -p 3001:3001 \
  -e AUTH_TOKEN=your-secret-token \
  -e ACUITY_BASE_URL=https://YourBusiness.as.me \
  -e ACUITY_BYPASS_COUPON=your-coupon-code \
  scheduling-bridge

# Set secrets in Modal dashboard first:
#   AUTH_TOKEN, ACUITY_BASE_URL, ACUITY_BYPASS_COUPON
# The Modal workflow materializes the Bazel-derived pkg/ before deploy.
modal deploy modal-app.py

The supported deployment path for the live Acuity bridge is:

1. merge to main
2. let .github/workflows/deploy-modal.yml deploy modal-app.py
3. inject MIDDLEWARE_RELEASE_SHA, MIDDLEWARE_RELEASE_REF, MIDDLEWARE_RELEASE_VERSION, and MIDDLEWARE_RELEASE_BUILT_AT
4. verify the resulting bridge tuple via GET /health

Operationally, this means:

• Modal deployment is part of release truth, not a side channel
• the live bridge should be identified by the /health release + protocol tuple
• downstream apps should validate the tuple they expect before making rollout claims

nix develop   # Enter dev shell with Node.js + Playwright
pnpm install
pnpm dev

Current release authority:

• canonical repo: Jesssullivan/scheduling-bridge
• npm package: @tummycrypt/scheduling-bridge
• GitHub Packages mirror: @jesssullivan/scheduling-bridge

The current publish + deploy shape is:

1. release metadata declared once
2. Bazel validates/builds the publishable artifact
3. CI dry-runs the extracted Bazel package surface before release
4. GitHub Actions publishes that extracted artifact
5. GitHub Actions deploys the Modal runtime from main
6. downstream apps consume the published package and verify the live runtime tuple via /health

This repo is the sole owner of Acuity automation concerns. App repos and shared packages may consume the bridge and assert its runtime tuple, but they should not duplicate bridge runtime ownership or release truth logic.

Package CI and publish currently use the shared js-bazel-package workflow with runner_mode: shared and publish_mode: same_runner.

The concrete shared-runner labels come from repository Actions variables and must be proven by green workflow runs before they are treated as operational truth. Keep private runner topology and apply details out of this public repo.

pnpm install      # Install dependencies
pnpm dev          # Start dev server with tsx
pnpm typecheck    # Run Bazel typecheck target
pnpm build        # Materialize local pkg/ and dist/ from bazel-bin/pkg
pnpm test         # Run Bazel test target
pnpm docs:generate

MIT