Platform Operations Guide

This guide is for teams maintaining app-link infrastructure, adapter registries, and production deployments.

Associated domains and app links

Route Bible serves both platform verification endpoints:

• /.well-known/apple-app-site-association
• /.well-known/assetlinks.json

Required values:

• Apple: APPLE_APP_ID in TEAMID.bundle.id format
• Android: ANDROID_PACKAGE_NAME, ANDROID_SHA256_FINGERPRINT

Verification checklist:

1. Deploy static site.
2. Confirm each endpoint returns 200 with valid JSON.
3. Validate domain association with platform tools.

Adapter registry source of truth

Primary adapter config:

• apps/route-bible/packages/adapters/config/adapters.links.json

Adapter config is strict-validated at startup/tests; invalid entries fail fast.

Required adapter fields:

• id
• name
• status (active, degraded, disabled)
• confidence (official, community, experimental)
• lastVerifiedAt (ISO timestamp)
• links[] with kind (deep or web) and template

Deployment model

• Frontend is static and deployed from Vercel artifacts.
• Runtime settings are generated into runtime-config.js from ROUTE_BIBLE_* environment variables.
• Backend capabilities are Supabase (Auth, Postgres, edge functions).

Production-critical checks:

• /builder renders and generates QR assets.
• /:passage resolves and launches correctly.
• /verse-pack auth + checkout + ZIP flow works.
• .well-known endpoints resolve publicly.

Operational risks to watch

• Auth email throttling if using default Supabase SMTP.
• Stale or invalid adapter templates.
• Polar webhook drift between sandbox and production settings.
• Incorrect app-link fingerprints after mobile signing changes.

Rollout recommendation for large Bible sites

1. Start by emitting canonical Route Bible links beside existing links.
2. Add an opt-in "Open in app" or Route Bible badge module.
3. Track clickthrough and fallback outcomes.
4. Promote Route Bible as primary once error rates are stable.