Skip to content

System Overview ​

PPP is a multi-instance pnpm monorepo built around a React SPA, a tRPC backend on Azure Container Apps, and a PostgreSQL Flexible Server. Cloudflare fronts everything — DNS, CDN, WAF, and static hosting for the SPA — while every compute and data resource lives in Azure UK South.

This page is the bird's-eye view. For per-environment resource detail see Azure Infrastructure; for the regional strategy see Multi-Region Design.

High-Level Architecture ​

Data Flow: Browser to Database ​

The happy path for a typical authenticated query:

Key points:

  • Cloudflare terminates TLS in front of both the SPA (Pages) and the API (api-<env> CNAME → Container App ingress). Security headers are injected by a Cloudflare Ruleset on every proxied response.
  • Better Auth (database-backed, self-hosted inside the Container App) is the primary authentication system. It replaces AWS Cognito — Cognito is still available for the dev environment during the tail of the migration, but UAT and Prod run Better Auth end-to-end. Email + password is the primary sign-in method, with Entra ID (Microsoft) and Google SSO wired in as additional providers where the client credentials are configured.
  • tRPC v10 gives the frontend end-to-end type safety. The React client uses @trpc/react-query + TanStack Query v4; the backend uses the Express adapter on Node.js 22.
  • Drizzle ORM owns schema and queries. The schema lives in packages-shared/ppp/src/schema.ts and migrations in packages-shared/ppp/drizzle/ — the CD pipeline runs drizzle-kit migrate with a sibling validator for every DDL change before a new container revision takes traffic.

Backend Layering ​

The tRPC backend is split into three layers so that business logic is testable without a router or HTTP layer:

  • Routers are thin: input validation (Zod), auth guards, and a single service call.
  • Services contain business logic and are the primary unit of test — see Backend Testing.
  • Data access is funnelled through a single PppDb helper so that every query runs with the same connection pool, logger, and instance context.

Monorepo Layout ​

Code is organised as a pnpm workspace monorepo with Turborepo for task orchestration:

LocationContents
instances/ppp/PPP React SPA (Vite, MUI v6, React Hook Form + Zod, tRPC client)
api/backend-ppp/PPP tRPC backend (Express, Drizzle, service layer)
api/backend-core/Shared backend utilities (storage abstraction, entrypoints, context)
api/infra-azure/Pulumi (TypeScript) — Azure UAT and Prod resource stacks
api/infra-cloudflare/Pulumi (TypeScript) — DNS, Pages projects, security headers, WAF
packages/Shared core packages (core-ui, core-constants, utils-api, config-mui, config-tsconfig)
packages-shared/ppp/PPP-specific shared code — Drizzle schema, Zod schemas, migrations, constants

See the repository README.md for the full directory layout and CLAUDE.md at the repo root for development conventions.

Deployment Flow ​

The CD workflow (.github/workflows/cd.yml) fires on push to uat and main, uses path filters to decide what to rebuild, then runs Pulumi for infrastructure changes, Drizzle for database migrations, and wrangler for Cloudflare Pages.

Environments:

  • UAT — ppp-uk-uat Azure stack + pppUat Cloudflare stack
  • Production — ppp-uk-prod Azure stack + pppProd Cloudflare stack

Mobile App ​

The mobile client is an Expo/React Native app that shares the same tRPC contract as the web app. Native-only features (shake-to-report, geo-fenced timesheet check-in, push notifications via Expo) live behind the same service layer as the web flows — the backend has one source of truth per feature. See the Mobile feature spec for the current scope.

Key Technology Stack ​

LayerTechnology
FrontendReact 19, TypeScript 5.8, Vite, MUI v6
StateTanStack Query v4, React Hook Form, Zod
APItRPC v10, SuperJSON, HTTP Batch Link
BackendNode.js 22, Express, tRPC Procedures
AuthBetter Auth (database-backed, self-hosted) — email + password, Entra ID and Google SSO
DatabasePostgreSQL Flexible Server, Drizzle ORM
ComputeAzure Container Apps (Consumption tier)
CDN / DNSCloudflare (DNS, Pages, WAF, security headers)
StorageAzure Blob Storage
SecretsAzure Key Vault + Managed Identity
ObservabilityAzure Log Analytics (container stdout + platform diagnostics)
IaCPulumi (TypeScript) for both Azure and Cloudflare
Buildpnpm workspaces + Turborepo
ExternalStripe, Azure Communication Services, Azure OpenAI, Expo, FHIR, GMC

Internal documentation — org members only