Skip to content

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 ​

IntegrationPurposeStatus
Stripe PaymentsOne-off annual payments for CPD and PPP Full (see pricing)Live
FHIR / SNOMED CTRead-only SNOMED CT terminology lookups for the surgical logbook (CSIRO Ontoserver)Live
Expo / EAS Push NotificationsDelivery of push notifications to iOS and Android devices via the Expo push serviceLive
Google Gemini (AI/OCR)OCR of medical stickers, AI-assisted reflection quality scoring, and PDP generationLive*
GMC Registrant LookupUK General Medical Council registration verification and specialist statusLive

* 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 requests
  • withRetry(fn, { maxRetries, baseDelayMs, shouldRetry }) — exponential backoff for transient failures
  • CircuitBreaker — 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_secret created 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.

Internal documentation — org members only