Integrations
PPP is a clinical platform stitched together from a small, carefully chosen set of external services. Each integration earns its place — none of them are "nice to have". This section documents what each integration is for, where it's wired in the codebase, how it's configured, and what happens when it fails.
The five integrations
| Integration | Purpose | Status |
|---|---|---|
| Stripe Payments | One-off annual payments for CPD and PPP Full (see pricing) | Live |
| FHIR / SNOMED CT | Read-only SNOMED CT terminology lookups for the surgical logbook (CSIRO Ontoserver) | Live |
| Expo / EAS Push Notifications | Delivery of push notifications to iOS and Android devices via the Expo push service | Live |
| Google Gemini (AI/OCR) | OCR of medical stickers, AI-assisted reflection quality scoring, and PDP generation | Live* |
| GMC Registrant Lookup | UK General Medical Council registration verification and specialist status | Live |
* The OCR path has been migrated to Azure OpenAI in the main platform; the "Gemini" name is retained in environment variables and in the WhatsApp ops bot. See the Gemini page for the full story.
Architectural conventions
Every integration in PPP follows the same four rules. If you are adding a sixth, read the existing pages first and match them.
1. One canonical env var per secret
External credentials live in Azure Key Vault and are plumbed through Doppler (ppp/uat or ppp/prod) into the Azure Container App as environment variables. The Pulumi stack in api/infra-azure/src/index.ts is the source of truth for which env vars get injected into which environment. Secrets are never committed to the repo and never expressed as frontend build-time variables — anything that would leak into the bundle is fetched server-side via a tRPC query (see getStripeConfig as the pattern).
2. Resilience is opt-in, but strongly encouraged
Outbound calls to external services use the shared resilience helpers in api/backend-ppp/src/utils/resilience.ts:
withTimeout(fn, ms, label)— aborts slow calls so they do not pile up tRPC requestswithRetry(fn, { maxRetries, baseDelayMs, shouldRetry })— exponential backoff for transient failuresCircuitBreaker— trips after sustained failures so PPP degrades gracefully instead of cascading
See Stripe, Expo, and Gemini for concrete usage.
3. Contract tests live alongside the integration
Each real integration is backed by either an MSW handler in api/backend-ppp/src/__fixtures__/handlers/ or a live integration test that hits the real endpoint (scoped to UAT only, behind requires-backend markers). Mock responses for unit tests are in api/backend-ppp/src/__fixtures__/responses/. When you change how PPP calls an external service, update both the handler and the fixture so CI stays honest.
4. Frontend never speaks directly to a third party
All third-party HTTP calls originate from the backend, with two deliberate exceptions:
- Stripe Elements — card data must never transit PPP servers for PCI reasons, so the frontend talks to Stripe directly using a short-lived
client_secretcreated by the backend. - Ontoserver — FHIR terminology lookups are read-only, unauthenticated, and run from the browser so search stays snappy with debouncing. See the FHIR page for details.
Every other external service — Expo, Gemini, GMC — is called from the tRPC backend only. Never add a direct frontend call to a secret-bearing API.
Related documentation
- Stripe Payments — one-off PaymentIntents, webhooks, test cards, the full playbook
- Pricing Updates & Stripe Runbook — how to change a plan price end-to-end
- FHIR / SNOMED CT — Ontoserver setup, ValueSet scope, offline mode, version updates
- Expo / EAS Push Notifications — push token lifecycle, circuit breaker, error handling
- Google Gemini (AI/OCR) — medical sticker OCR, the Azure OpenAI migration, WhatsApp ops bot
- GMC Registrant Lookup — UK GMC scraping, consultant/GP classification, rate limiting
api/backend-ppp/src/utils/resilience.ts— shared timeout, retry, and circuit breaker helpersapi/infra-azure/SECRET_LINEAGE.md— canonical table of every secret flowing from Doppler into Azure Key Vault