pcobooster.com

Planning Center tools for worship teams.

Overview

This app helps teams schedule people into open positions for specific plans by combining:

• service type and plan selection
• needed team positions grouped by team
• people matching for the selected team/position
• availability and recent scheduling history context
• one-click scheduling into Planning Center

The public marketing site lives at /, with the origin story at /about. The authenticated product starts at /services.

This is a Bun/Turborepo monorepo. The product UI lives in apps/web, the API Worker (an Alchemy Effect-native Cloudflare Worker serving the product API with Effect HttpApi on an Effect HTTP router) lives in apps/server, server implementation lives in packages/api, browser-safe API contracts live in packages/contracts, the product API client lives in packages/client, Planning Center models and calendar rules live in packages/planning-center-models, and the static marketing site lives in apps/marketing. See marketing development and deployment.

For parallel remote development, see Codex cloud development.

Setup

This repo uses Bun for dependency management and scripts. Use bun.lock as the only lockfile; do not use npm or commit package-lock.json.

Use Node.js 24 (see .node-version) and Bun 1.4.2 (pinned in package.json; CI reads it from there).

1. Install dependencies

bun install --frozen-lockfile

2. Configure local secrets

Development credentials live in Infisical pcobooster-dev, which Alchemy reads for stage local. With the agent-dev machine identity's INFISICAL_CLIENT_ID and INFISICAL_CLIENT_SECRET set, run bun run setup:infisical once to store it in your default Alchemy profile. Never put a secret value in command arguments, chat, issues, or committed files.

bun run dev signs you in as the owner of the Planning Center sandbox PAT from the Keychain sandbox scope (bun run secrets:set sandbox PLANNING_CENTER_PAT); dev:church uses the Agape PAT from Infisical, read-only. dev:auth uses real OAuth and dev:present enables presentation mode. The servers bind to 127.0.0.1; deployed Workers ignore the development bypass. Each stage gets separate D1 data.

Scripts that run outside Alchemy use bun run secrets:dev <command>. Operator-only tools keep Keychain scopes (bun run secrets:run apple -- <command>). Deployed app secrets live in Cloudflare Secrets Store; GitHub environment secrets supply deployment credentials. See configuration, migration, and deployment.

3. Start the app

bun run dev

Alchemy applies migrations to persistent local D1 and starts the API and product; marketing runs beside them. The command prints the product URL. You are signed in with the personal access token; there is no sign-in page.

The main checkout uses ports 3000 (API), 3001 (product), and 3002 (marketing). Each linked git worktree gets its own block of ports, derived from its path (4000 to 4993), so several worktrees can run bun run dev at once. Set DEV_PORT_BASE=<port> to choose the block yourself; the stack uses that port and the next two. Every checkout keeps its own local D1 database under .alchemy/.

All running checkouts share one personal access token, so they share Planning Center's limit of 100 requests per 20 seconds per user. Each API Worker paces only its own requests, so two busy checkouts can see 429s that one would not.

Test Planning Center sign-in

bun run dev:auth

This runs real Planning Center OAuth instead of the token, always on the main ports: Planning Center redirects only to the registered http://127.0.0.1:3001/api/auth/callback/planning-center, so one checkout at a time can test sign-in. Production uses https://pcobooster.com/api/auth/callback/planning-center; preview callbacks use the production OAuth broker.

Schema migrations are generated by Drizzle.Schema on bun run dev (or explicitly with bun run db:generate); commit them. Alchemy applies them during local startup and deployments. No remote database credentials are needed to run tests.

Present locally

bun run dev:present

This enables PRESENTATION_MODE=1 for the local dev servers. It is ignored when NODE_ENV=production . The app shows a "Presentation mode" badge. Your signed-in account and organization stay visible. Planning Center people get consistent fictional names, fictional initials, and no photos across candidates, filled positions, search, and People pages. Blockout reasons/descriptions and selected-plan decline notes are masked on the server. Aliases come from about 9,500 name combinations, so two people rarely share one.

Search matches the fictional names. Its first request loads the People directory; subsequent requests reuse the account-scoped directory cache for five minutes. Browser people caches and React Query caches are isolated from normal mode. PRESENTATION_SEED optionally changes the aliases and browser cache namespace.

Stop the server, run bun run dev, and reload open tabs to return to normal mode. Do not store PRESENTATION_MODE in Keychain if you want the command to control it. The flag is ignored in production . It does not change authentication or grant API access.

This masks person fields for app presentations, not the underlying dataset: IDs, schedules, team/position names, plan titles, and free-form plan-item text remain real. Review those custom labels before a public recording. Actions still write to the real Planning Center account; server logs and external Planning Center pages are outside the masking scope.

Share a read-only demo

https://pcobooster.com/demo/<key> opens the app for someone without a Planning Center login. It reads your Planning Center organization with people's personal details spoofed, and cannot write. See the demo link guide for setup and revocation.

API Routes

Product operations are Effect HttpApi endpoints under /api/v1 (one method and path per procedure, packages/contracts/src/http), called by tag through makeProductClient (packages/client). Better Auth keeps its protocol-owned GET/POST /api/auth/* handler. /health is the service liveness endpoint.

Project Structure

apps/
  web/                       # TanStack Start product UI
  server/                    # API Worker (Alchemy Effect-native) serving Effect HttpApi
  marketing/                 # Prerendered TanStack Start marketing site
packages/
  api/                       # Server-side application, auth, DB, adapters, API server
  contracts/                 # Browser-safe API contracts and fault classes
  client/                    # Product API client, request scheduler, query helpers
  planning-center-models/    # Shared Planning Center shapes and calendar rules
  presentation-mode/         # Shared server-side presentation configuration
  config/                    # Shared TypeScript configuration

Development Commands

• bun run dev
• bun run build
• bun run check: strict Ultracite lint and formatting checks
• bun run fix: auto-fix and format
• bun run ci: the local CI gate (check, typecheck, and tests)
• bun run ci:affected --base origin/main: lint, then check changed packages and dependents plus repository guards; use --dry-run to inspect the selection. For an upper stack layer, pass its preceding branch as the base.
• bun run typecheck
• bun run test
• bun run test:watch
• bun run proof -- doctor: audit revision-bound PR proof prerequisites

Testing

bun run ci
bun run build

Tests are colocated under packages/*/src and apps/*/src. Feature modules accept narrow typed dependencies so tests can exercise behavior without replacing modules. Everything is validated with Effect Schema: the server decodes inputs, the client decodes answers, and Planning Center responses, KV entries, and persisted browser caches (written and read through each endpoint's own schema) are decoded the same way.

Pull requests must pass the GitHub ci and cloudflare-build checks. See CI/CD for the merge gates, deployment flow, dependency update policy, and rollback procedure.

For visible or high-risk changes, follow Proofed delivery. The repo-local skills under .agents/skills/ cover setup, app-specific browser verification, verification-skill generation, and independent PR proof.

Code Quality

Ultracite uses Oxlint and Oxfmt with the strict core, React, TanStack, Vitest, shadcn, anti-slop, and React Doctor presets. oxlint.config.ts and oxfmt.config.ts are the configuration sources. GitHub CI rejects warnings as well as errors, then runs TypeScript and tests; cloudflare-build separately builds the Workers without credentials. Tests use explicit dummy credentials from vitest.config.ts; neither gate receives production secrets. Generated route trees, database migrations, and scraped API documentation are excluded from formatting.

The OXC VS Code extension is recommended in .vscode/extensions.json; workspace settings enable formatting and explicit fixes on save. bun install installs the Lefthook hooks: pre-commit fixes and re-stages supported staged files, and pre-push runs bun run check and bun run typecheck. Run bun run ci before submitting changes and bun x ultracite doctor when diagnosing the toolchain.

Shared UI primitives expose appearance through variants, with semantic theme tokens for scheduling states. Call sites own layout.

Better Auth is pinned to 1.7.5; keep the registered callback URLs above aligned with the service origin.

Stacked Pull Requests

Use GitHub's native stacks for changes with dependent review layers. Keep each layer focused and independently passing bun run ci and bun run build.

gh extension install github/gh-stack
gh stack init --base main codex/my-change-foundation
# Commit the foundation, then start its dependent layer.
gh stack add codex/my-change-interface
# Commit and validate the interface, then publish draft PRs.
gh stack submit --auto --remote origin
gh stack view --json

Each PR targets the preceding branch; the bottom PR targets main. After editing a lower layer, run gh stack rebase --upstack --remote origin and resubmit. Update the generated PR titles and descriptions with the behavior changes and validation results.

When every layer is ready and GitHub checks pass, use gh stack merge <stack-number> --yes --squash to land the stack together. GitHub enforces the repository's merge requirements for the entire operation. Use gh stack sync --remote origin afterward to reconcile local state.

Planning Center API Docs

Local scraped API docs are in docs/planning-center-api/. See docs/planning-center-api/README.md for export details.