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.tsand migrations inpackages-shared/ppp/drizzle/— the CD pipeline runsdrizzle-kit migratewith 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
PppDbhelper 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:
| Location | Contents |
|---|---|
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-uatAzure stack +pppUatCloudflare stack - Production —
ppp-uk-prodAzure stack +pppProdCloudflare 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
| Layer | Technology |
|---|---|
| Frontend | React 19, TypeScript 5.8, Vite, MUI v6 |
| State | TanStack Query v4, React Hook Form, Zod |
| API | tRPC v10, SuperJSON, HTTP Batch Link |
| Backend | Node.js 22, Express, tRPC Procedures |
| Auth | Better Auth (database-backed, self-hosted) — email + password, Entra ID and Google SSO |
| Database | PostgreSQL Flexible Server, Drizzle ORM |
| Compute | Azure Container Apps (Consumption tier) |
| CDN / DNS | Cloudflare (DNS, Pages, WAF, security headers) |
| Storage | Azure Blob Storage |
| Secrets | Azure Key Vault + Managed Identity |
| Observability | Azure Log Analytics (container stdout + platform diagnostics) |
| IaC | Pulumi (TypeScript) for both Azure and Cloudflare |
| Build | pnpm workspaces + Turborepo |
| External | Stripe, Azure Communication Services, Azure OpenAI, Expo, FHIR, GMC |
Related Pages
- Azure Infrastructure — concrete Azure resources and their roles
- Multi-Region Design — current state and target UK + AU data sovereignty plan
- Mobile feature spec — mobile app scope and how it fits the backend contract
- Timesheets feature spec — geo-fencing backend and batch processing architecture
- Stripe Payments — payment integration overview
- FHIR / SNOMED CT — medical terminology integration