Oslr · Operational docs

Oslr documentation

Everything you need to deploy, configure, and keep Oslr running. Oslr is a mobile-first app that helps doctors and medical students organise clinical bedside teaching on hospital wards — one React codebase shipped to web and to native iOS/Android.

Branch model, in one line

All development lands via pull requests into dev; main is production and only moves when you merge dev → main. Full detail in Deployment → Branching & release workflow.

How it ships

Three pipelines, all triggered by pushing to GitHub. There are no manual release steps in the normal path.

Two environments

The backend runs as two separate Supabase projects, chosen by branch. The frontend picks its project from build-time VITE_SUPABASE_* variables.

Also in the repo

Architecture, conventions, and the data model live in CLAUDE.MD; the project overview is in the README. Point-in-time product notes (the July 2026 usability audit, action plan, and wave 1–2 fixes) and debugging reproduction scripts stay as markdown under docs/ — see the docs index.

01 · Operations

Deployment guide

How Oslr ships to web, mobile, and backend. For a command cheat-sheet see Quick reference; for first-time environment setup see Production setup.

Branching & release workflow

All development happens through pull requests into dev. Nothing is committed directly to main. dev is the integration branch that everyone builds on; main is production and is only updated by opening a release PR from dev → main.

So a release looks like: push to dev → the app is built and submitted to TestFlight for review while you keep iterating on Preview web (dev DB). When the change is signed off, open a dev → main PR; merging it deploys production web + prod backend and releases the already-reviewed app version to the stores in the same step.

Overview

Three pipelines, all triggered by pushing to GitHub. There are no manual release steps in the normal path.

Pull requests touching oslr-web/** also run a quality gate (.github/workflows/web-quality-gate.yml): npm ci, npm run build, npm run lint. This is what protects dev — a red gate blocks the merge.

Two environments

The backend runs as two separate Supabase projects, chosen by branch. This split governs the web app and backend deploys; the native app is always built against prod (see the note above).

1 · Web (Vercel)

Two separate Vercel projects are built from this repo: the app (oslr-web/) and the marketing site (oslr-landing/). Each has its own vercel.json and its own Root Directory setting.

The app — oslr-web/

• Config: vercel.json — SPA rewrites so client-side routes resolve.
• Trigger: every push. main → Production, other branches → Preview URLs.
• Build: Vercel runs npm ci + npm run build in oslr-web/, serves dist/.

The marketing site — oslr-landing/

• Config: oslr-landing/vercel.json — rewrites to index.html for the client-side routes (/about, /help, /privacy, /terms), plus cache headers on /assets/*.
• Project settings: Root Directory oslr-landing, framework Vite, build npm run build, output dist.
• Environment variables:
  • VITE_GA_MEASUREMENT_ID — the GA4 Measurement ID (e.g. G-XXXXXXXXXX). Set it in the Production scope only, so preview deploys never report into the analytics property. With it unset, the analytics code is stripped from the build entirely.
  • VITE_VIDEO_BASE_URL — the S3 base the /help page loads walkthrough videos from (defaults to the bucket convention in config.ts if unset).
  Vite bakes both in at build time, so redeploy after changing either.
• Analytics: GA4, loaded directly — there is no consent banner, and advertising signals are explicitly denied. Event schema, the one-time GA4 custom-dimension setup, and the two conversion funnels are documented in oslr-landing/README.md.
• Help videos: the /help page is built from oslr-landing/src/lib/helpWorkflows.ts and embeds the demo videos from S3 (published by demo-videos/publish.sh) — see the Demo videos page.
• Outbound links (app URL, store listings, contact addresses) all live in oslr-landing/src/lib/config.ts.

Environment variables (Vercel → Settings → Environment Variables — set each twice, once per scope):

Vite bakes these in at build time — redeploy after changing them.

Manual deploy (rarely needed):

cd oslr-web
npm run build
vercel --prod

2 · Mobile (Codemagic)

• Config: codemagic.yaml — two workflows, android_internal and ios_testflight.
• Trigger: push to dev (both workflows) → iOS to TestFlight (submitted for App Review) and Android to the Play internal track.
• Backend: the app is built against the prod Supabase project — codemagic.yaml supplies the prod VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY (mxthnwdweubpkjostkbd; the anon value is the project's publishable key) for both mobile workflows, so the review build hits prod.
• Signing & secrets: managed in Codemagic (variable groups code-signing, ios-signing; Android keystore mercury_keystore; App Store Connect integration CodemagicOslr). No signing files are stored in the repo.
• Release: the TestFlight/internal build is the release candidate. It goes public when you merge dev → main and release that version in App Store Connect / Play Console — the app store release and the production web/backend deploy happen together.

Both workflows run npm ci → npm run build → npx cap sync before building the native app.

Versioning is a single UTC timestamp, unified across platforms so a version is self-documenting (a user on 2026.0725.1430 was built 25 Jul 14:30 UTC):

• Version name (iOS marketing + Android versionName, identical): YYYY.MMDD.HHMM.
• iOS build (CFBundleVersion): YYYYMMDDHHMMSS.
• Android versionCode (internal only): Google Play's latest build number + 1. Play's existing versionCode is already inflated near its ~2.1B cap — higher than the current Unix time — so a timestamp can't reliably beat it; we query the latest and increment. The user-visible versionName is still the unified timestamp above.

Android — android_internal

• Package: com.mercury.mercuryapp (env ANDROID_PACKAGE_NAME).
• Builds a signed AAB (./gradlew bundleRelease) with the timestamp versionCode/versionName, publishes to the internal track.
• Needs Play Developer API access for GOOGLE_PLAY_SERVICE_ACCOUNT.

iOS — ios_testflight

• Bundle ID: com.mercury.mercuryapp; distribution type app_store.
• Automatic signing via the App Store Connect integration (app-store-connect fetch-signing-files), CocoaPods install, build-ipa.
• Sets ITSAppUsesNonExemptEncryption = false (no export-compliance prompt).
• Release (two steps): after the IPA is built, Upload IPA to TestFlight uploads it with app-store-connect publish (codemagic-cli-tools, waiting for Apple to finish processing), then App Store version + metadata runs the Fastlane release lane to create the App Store version = this build's timestamp, attach the build, and push metadata from fastlane/metadata/** — leaving the version "ready to submit" (submit_for_review: false, so the final Submit stays a manual click; flip that flag to go fully hands-off). This is why the App Store version, not just the TestFlight build, now advances on every dev push.
• Why the split: the binary upload uses the CLI (native ASC-key handling) rather than fastlane's upload_to_testflight, because Apple's altool rejects the SEC1-converted key that spaceship/deliver requires ("invalid AuthKey −39"). So the CLI does the upload and Fastlane (needs ruby: 3.3.6) does only the version + metadata via spaceship — no altool.

iOS code signing — what to do (step by step)

Signing here is automatic: Codemagic uses the App Store Connect API key (integration CodemagicOslr) to fetch/create the certificate and provisioning profile at build time — nothing is stored in the repo. The mental model that makes this painless:

• A distribution certificate is account-wide — one certificate signs all your apps. It is not per-app.
• A provisioning profile is per-bundle-ID, but the build auto-creates it (app-store-connect fetch-signing-files … --create).
• The App ID com.mercury.mercuryapp already exists in the Apple account (from the original app), so a profile can be made for it.

Step 1 — Confirm the API key can manage signing. App Store Connect → Users and Access → Integrations → Keys → the key behind CodemagicOslr. Its role must be App Manager or Admin (a "Developer" key can't create certificates/profiles). Bump it if needed.

Step 2 — Generate a signing private key (one command on your Mac; copies itself to the clipboard):

ssh-keygen -t rsa -b 2048 -m PEM -f ~/oslr_signing_key -q -N "" && cat ~/oslr_signing_key | pbcopy

Step 3 — Add it to Codemagic. Codemagic → oslr3 → Environment variables → add:

• Name: CERTIFICATE_PRIVATE_KEY
• Value: paste from the clipboard (the whole -----BEGIN…END----- block)
• Group: ios-signing · tick Secure

That's it. The next build's Fetch signing files step creates (or reuses) the distribution certificate from that key and auto-creates the com.mercury.mercuryapp profile.

Push notifications

iOS push (FCM) needs the Firebase config to match the bundle ID. oslr-web/ios/App/GoogleService-Info.plist is the com.mercury.mercuryapp iOS app registered in the same Firebase project (oslr3-12501). If you ever change the bundle ID again, re-register that app in Firebase console → Project settings → your iOS apps and drop in the new GoogleService-Info.plist, or push will silently fail. Android is unaffected (already com.mercury.mercuryapp).

App Store listing as code

The App Store listing text is version-controlled in fastlane/metadata/en-US/ — name, subtitle, description, keywords, promotional_text, release_notes, privacy_url, and the support/marketing URLs. It is pushed with Fastlane deliver in two places, both with submit_for_review: false (they populate the listing but never submit):

• Automatically on every dev push, by the release lane in ios_testflight (see above) — this keeps the prepared App Store version's text in sync with the repo as part of the normal build.
• Manually, via the ios_appstore_metadata workflow (Codemagic UI → Start build → ios_appstore_metadata) — the metadata lane, for tweaking copy on the current editable version between builds without a rebuild.

• Both lanes share one helper that handles Codemagic's @file: key reference and converts Apple's PKCS#8 .p8 to SEC1 (an OpenSSL 3 quirk); both need ruby: 3.3.6.
• Because we ship as com.mercury.mercuryapp (the established app), deliver just updates the existing listing — the "Oslr" app-name clash and the brand-new-app "No data" first-version error that would hit a fresh app record both go away, so name/subtitle are now managed here.
• Primary locale: metadata lives under en-US/ — it must match the app's primary locale in App Store Connect (English (U.S.), the locale the 3.0.0 version was created under). privacy_url points at https://www.oslr.co.uk/privacy; keep that page live or a submit will bounce.

3 · Backend (GitHub Actions → Supabase)

• Config: .github/workflows/deploy-supabase.yml.
• Trigger: push to main or dev that changes supabase/** (also manual via workflow_dispatch).
• Environment: main → Production, otherwise → Preview. Environment secrets resolve the target project automatically, and protection rules (e.g. required reviewers on Production) gate the run.

What it does, against the selected project:

1. Installs the Supabase CLI and links the project.
2. supabase db push — applies migrations in supabase/migrations/.
3. Deploys every Edge Function with supabase functions deploy <name> --no-verify-jwt --use-api.
4. Sets the FCM_SERVICE_ACCOUNT_JSON function secret.
5. PATCHes the branded auth email templates (supabase/templates/*.html) via the Management API — only the mailer_* fields, leaving site_url/SMTP untouched.

Required secrets. Repository-level (shared by both environments):

Per environment (Preview and Production, different values):

Manual deploy:

supabase login
supabase link --project-ref <project-ref>
supabase db push
supabase functions deploy <name> --use-api

Everyday workflow

1. Branch off dev, develop locally (npm run dev).
2. Open a PR into dev → the web quality gate runs; Vercel posts a Preview URL.
3. Merge to dev → deploys Preview web (dev DB) + the dev Supabase project, and Codemagic builds the release-candidate app and uploads it to TestFlight for App Review.
4. Release: once the app is reviewed and the change is signed off, open a PR dev → main. Merging deploys prod Supabase + Production web, and you release the reviewed app version in App Store Connect / Play Console at the same time.

Verifying a deploy

Web

curl -I https://oslr3.vercel.app        # expect 200

Check the deployment and logs in the Vercel dashboard.

Mobile

• iOS: App Store Connect → TestFlight → check the new build processed.
• Android: Play Console → Testing → Internal testing → check the versionCode.

Backend

• GitHub → Actions → the "Deploy Supabase Changes" run is green.
• Supabase dashboard → confirm the migration and function versions.

Rollback

Web — Vercel dashboard → Deployments → pick the last good one → Promote to Production (or vercel rollback).

Mobile — you can't truly roll back a shipped build; release a new build based on the previous good commit. On Android you can also halt/replace the internal-track rollout in the Play Console.

Backend — write a new "down" migration that reverses the change and supabase db push; never edit the original migration. For a function, git checkout <good-commit> -- supabase/functions/<name> and redeploy.

Troubleshooting

Reference

• vercel.json — web SPA routing
• codemagic.yaml — mobile build & release
• .github/workflows/deploy-supabase.yml — backend deploy
• .github/workflows/web-quality-gate.yml — PR build/lint gate
• .github/workflows/publish-demo-videos.yml — sync demo videos to S3 on push to main
• oslr-web/capacitor.config.ts — native app config
• Production setup — one-time dev/prod setup
• Runbook — secrets, rotation, incidents

Platform status: Vercel · Codemagic · Supabase · GitHub.

02 · Operations

Quick reference

Commands and URLs at a glance. Full detail in the Deployment guide.

Branch → environment

Everything deploys on push, and all work lands via PRs into dev. A push to dev builds the app (prod-backed) to TestFlight for review; merging dev → main deploys production web + backend and releases the reviewed app. Web follows the branch (dev DB on Preview, prod DB on Production); the native app is prod-backed on every track (codemagic.yaml bakes in the prod project — see Deployment § Mobile).

Dashboards

Production web: oslr3.vercel.app

The marketing site (oslr-landing/) is a second Vercel project in the same dashboard — see Deployment § 1 for its settings.

Deploy commands

Deploys are automatic on push. Manual fallbacks:

# Web
cd oslr-web && npm run build && vercel --prod

# Supabase (link the right project first)
supabase link --project-ref <project-ref>
supabase db push                              # migrations
supabase functions deploy <name> --use-api    # a function

Every function is deployed with --no-verify-jwt; functions that need an authenticated caller verify the JWT in code.

Mobile (local, for debugging)

cd oslr-web
npm run build
npx cap sync ios     && npx cap open ios       # or android

Store builds/uploads run in Codemagic on push to dev, not locally.

Required env / secrets

• Vercel (per scope): VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY
• GitHub — repo secrets: SUPABASE_ACCESS_TOKEN, FCM_SERVICE_ACCOUNT_JSON
• GitHub — per environment (Preview / Production): SUPABASE_PROJECT_ID, SUPABASE_DB_PASSWORD

Setup details in Production setup; secret ownership & rotation in the Runbook.

Logs & status

curl -I https://oslr3.vercel.app                       # web up?
vercel logs                                            # web logs
supabase functions logs <name> --project-ref <ref>     # function logs
gh run list --workflow=deploy-supabase.yml             # backend deploys

Rollback

# Web: promote a previous deployment in the Vercel dashboard, or
vercel rollback

# Supabase: reverse with a NEW migration (never edit an old one)
supabase migration new revert_<name>
supabase db push

Common issues

03 · Operations

Production / dev environment split

One-time setup of the two backend environments. For how deploys work day to day see Deployment; for a cheat-sheet see Quick reference.

Two Supabase projects, selected by git branch:

Migrations/functions deploy via .github/workflows/deploy-supabase.yml. Frontend env vars live in Vercel. There is no hardcoded Supabase fallback in the app (oslr-web/src/lib/supabase.ts) — a missing var fails loudly.

1 · GitHub — secrets & Environments

Repository → Settings → Secrets and variables → Actions, and Repository → Settings → Environments.

1a. Repository-level secrets (shared by both environments)

1b. Environment Preview secrets (→ dev project)

1c. Environment Production secrets (→ prod project)

Then on the Production environment:

• Deployment branches and tags → Selected → add main. This restricts the Production environment (and its secrets) to the main branch.
• Required reviewers → yourself. A push to main that touches supabase/** then pauses for your approval before it writes to the live DB.

GitHub CLI equivalent

# Repo-level (shared)
gh secret set SUPABASE_ACCESS_TOKEN
gh secret set FCM_SERVICE_ACCOUNT_JSON < fcm-service-account.json

# Per environment
gh secret set SUPABASE_PROJECT_ID  --env Preview     --body "jeibuakusgpcyybfnmos"
gh secret set SUPABASE_DB_PASSWORD --env Preview
gh secret set SUPABASE_PROJECT_ID  --env Production   --body "<PROD_REF>"
gh secret set SUPABASE_DB_PASSWORD --env Production

Environments must exist before --env works; create them once in the UI (Settings → Environments → New environment) or they'll 404.

2 · Vercel — frontend env vars

Project → Settings → Environment Variables. Add each variable twice — once scoped to Production (prod values), once scoped to Preview + Development (dev values). Same name, different value per scope.

• Anon key: Project Settings → API → Project API keys → anon public.
• Result: main deploys (Production) hit prod; dev and any feature branch (Preview) hit dev. vite dev locally uses .env.local (unchanged).
• After changing Vercel env vars, redeploy — they're baked in at build time.

Mobile (Codemagic) env vars

Unlike Vercel, the mobile build is prod-backed: codemagic.yaml vars: set VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY to the prod project (mxthnwdweubpkjostkbd) for both workflows, so the TestFlight/internal build that goes for App Review talks to prod. The anon value is the project's publishable key (sb_publishable_…).

3 · Prod project — one-time setup (not covered by migrations)

Run Phase 0 first (verify migrations rebuild the schema from scratch) before any of this.

# Link to the NEW prod project and push schema
supabase link --project-ref <PROD_REF>
supabase db push                 # applies all migrations to empty prod DB

# Prod seed = reference data (job titles, specialties, locations) + two App
# Review logins (a teacher + a student, on example.com, no org membership).
# Locations are HOSPITALS (Broomfield only for launch). Do NOT use seed.sql or
# seed_demo.sql (they insert demo sessions/orgs). Idempotent — safe to re-run.
# NOTE: the main->Production deploy now applies this automatically (needs the
# SUPABASE_DB_URL Production secret); this manual run is just for first setup.
psql "<PROD_DB_CONNECTION_STRING>" -f supabase/seed_prod.sql

# Edge functions + their secrets (functions don't carry secrets across projects)
supabase functions deploy --project-ref <PROD_REF>
supabase secrets set FCM_SERVICE_ACCOUNT_JSON="$(cat fcm-service-account.json)" --project-ref <PROD_REF>

Dashboard settings to replicate on prod (config.toml only covers local)

• Auth → URL Configuration: Site URL = real prod URL; add prod redirect allow-list; set Apple sign-in redirect.
• Auth → SMTP: configure custom SMTP + email templates (don't ship real users on Supabase's default rate-limited mailer).
• Storage: recreate any buckets + policies the app expects.
• Database → Backups: enable PITR / daily backups (Pro plan).

4 · Go-live checklist

• Phase 0: supabase db diff --linked against dev is clean (no drift)
• GitHub repo secrets set (access token, FCM)
• GitHub Preview + Production environments created with their secrets
• Production environment restricted to main + required-reviewer protection
• Vercel vars set for both scopes, prod redeployed
• dev branch created and pushed; verify it deploys to dev project
• Prod schema pushed; seed_prod.sql applied (reference data + two App Review logins), functions + secrets deployed
• seed_prod.sql auto-applies on every prod deploy using the existing SUPABASE_PROJECT_ID + SUPABASE_DB_PASSWORD secrets (via the session pooler); the optional SUPABASE_DB_URL secret only overrides a non-standard pooler host
• Prod auth/SMTP/storage/backups configured
• Mobile: Codemagic env vars set to prod Supabase; a dev build submitted to TestFlight for App Review, released to the stores when merged to main
• End-to-end smoke test on prod (signup, RLS, push, account deletion)

5 · Hosting this documentation (docs.oslr.co.uk)

The doc site is served by its own Vercel project, separate from the app — so it has its own domain and deployments and never touches the app's. Set it up once:

1. Vercel → Add New → Project → import oslr/oslr3 again; name it e.g. oslr-docs.
2. Root Directory → docs/site. Framework Preset Other, no build command (it's static HTML).
3. Settings → Environments → set the Production environment's branch to dev (this is where the docs live). Note: the production-branch control moved to the Environments page — it is no longer under Settings → Git.
4. Settings → Domains → add docs.oslr.co.uk. At the oslr.co.uk DNS host add a CNAME: docs → cname.vercel-dns.com. Vercel issues the TLS cert automatically.
5. (Optional) Settings → Git → Ignored Build Step: git diff --quiet HEAD^ HEAD -- docs/site — rebuilds only when the docs changed.

04 · Operations

Release credentials & incident response

Who owns what, how often secrets rotate, and how to respond when a release breaks.

Ownership matrix

Credential storage policy

• Store production credentials in the team's password manager and platform secret stores only.
• Never commit credential files or plaintext secrets to git.
• Keep local credential artifacts in the git-ignored credentials/ directory when needed for manual setup.

Rotation cadence

• Rotate mobile signing/API credentials every 90 days or immediately after team membership changes.
• Rotate deployment tokens/secrets every 90 days.
• Rotate immediately after any suspected leak, CI log exposure, or compromised workstation.

Pre-release checks

• Confirm npm ci, npm run build, and npm run lint are green on the release commit.
• Confirm Codemagic ios_testflight and android_internal workflows are green for the same commit.
• Confirm the iOS bundle ID is com.mercury.mercuryapp and the Android package ID is com.mercury.mercuryapp.
• Confirm Google Play upload track is internal and TestFlight upload completed.

Incident severity & response

SEV-1 — Production outage or broken mobile release pipeline

• Trigger: release artifact cannot be produced or published for iOS/Android, or a production deploy failure blocks users.
• SLA: acknowledge within 15 minutes.
• Owner: Platform DevOps Lead.
• Escalate to CEO immediately and request Security QA Lead for validation.

SEV-2 — Degraded CI signal or non-blocking release issue

• Trigger: flaky checks, warning-level quality regressions, delayed release execution.
• SLA: acknowledge within 60 minutes.
• Owner: Platform DevOps Lead.
• Escalate to Security QA Lead if risk reaches release cutoff.

Incident procedure

1. Stabilize — freeze new release attempts; capture failing run links, logs, and the exact commit SHA.
2. Triage — identify whether the failure is credentials, configuration, or a source change; validate signing assets and secret availability in Codemagic/GitHub.
3. Mitigate — roll forward with a targeted fix when possible; if blocked, roll back to the last known good release commit and republish.
4. Communicate — post status updates every 30 minutes until resolved; include impact, current mitigation, and next checkpoint.
5. Recover & prevent — document root cause and preventive action; rotate any credentials involved; open follow-up tasks for hardening and test-coverage gaps.

Escalation contacts

• Platform DevOps Lead — primary on-call for release engineering.
• Security QA Lead — release gate and validation support.
• CEO — final escalation for staffing, external communication, and approval.

05 · The app

Demo videos

Narrated walkthroughs of every key workflow. Each one drives a real browser through a real user story with a voiceover and captions — the fastest way to see how a part of the app actually works. Because every step asserts its way through the flow, a demo that renders is also a passing acceptance test of that story.

📱 = phone view (default) · 🖥 = desktop (admin flows).

Getting started — any user

Doctor / teacher

Student

Admin — institution

Account & settings — any user

The full catalogue — including which script covers each story and suggested groupings for longer films — is in WORKFLOWS.md. (There's also a 00-smoke clip that just exercises the render harness itself.)

Render them yourself

From demo-videos/, against a local dev server seeded with seed_demo.sql:

cd demo-videos
npm install && npx playwright install chromium

npm run list                                 # list the demos
node render.mjs --check                       # headless, assert-only — fast acceptance test
npm run demo                                  # re-seed + fixtures + render all
node render.mjs 01-create-teaching-session    # render one → out/01-create-teaching-session.mp4

Prerequisites (dev server on :5173, demo accounts from seed_demo.sql, ffmpeg, optional OpenAI TTS) and how to add a new demo are in demo-videos/README.md. Keep each demo's selectors aligned with the matching cypress/e2e/*.cy.ts spec so the demo and the test stay in step.