Azure Infrastructure
PPP runs on a narrow set of Azure resources, all provisioned via Pulumi (TypeScript) from api/infra-azure/. Two stacks are deployed today — both in UK South:
| Stack | Pulumi stack name | Environment |
|---|---|---|
| UAT | ppp-uk-uat | uat |
| Production | ppp-uk-prod | prod |
A third Pulumi project (api/infra-azure-shared/) provisions resources shared across both environments as the ppp-uk-shared stack. For the higher-level picture see System Overview; for the regional roadmap see Multi-Region Design.
Public URLs
| Service | UAT |
|---|---|
| Marketing site | https://uat.professionalperformanceportfolio.com |
| PPP web app | https://ppp-uat.professionalperformanceportfolio.com |
| tRPC API | https://api-uat.professionalperformanceportfolio.com |
| Health probe | https://api-uat.professionalperformanceportfolio.com/healthz |
| Better Auth routes | https://api-uat.professionalperformanceportfolio.com/api/auth |
Production uses the non-uat equivalents on the same apex domain.
Resource Topology
Resource Responsibilities
Compute — Azure Container Apps
- Container App (Consumption tier) runs the PPP tRPC backend as a Docker image. Scale-to-zero when idle, scale-out under load.
- Container Apps Environment hosts the app and forwards stdout/stderr and platform diagnostics to Log Analytics — without this, crash-loop revisions are invisible.
- Azure Container Registry (Basic SKU) stores the backend image. No admin credentials — the Container App's user-assigned Managed Identity pulls images via the
AcrPullRBAC role, and the CD pipeline Service Principal pushes viaAcrPush.
The container image is built from api/backend-ppp/Dockerfile.container on a node:22-slim base. CD tags images as <env>-<git-sha> and Pulumi passes the full ACR reference into the Container App template.
Database — PostgreSQL Flexible Server
- Standard_B1ms Burstable (1 vCore, 2 GiB RAM, 32 GiB storage) in UK South.
- AES-256 encryption at rest (default) and TLS-in-transit enforced (
sslmode=require). - Firewall rule opens "Allow Azure Services" so Consumption Container Apps — which have no static egress IP — can connect.
- Drizzle ORM migrations run pre-rollout in the CD pipeline. Every DDL migration ships with a sibling
.validate.sqlthat re-asserts the change against the live DB; a silent no-op fails the deploy before the new revision takes traffic.
Storage — Azure Blob Storage
- Storage Account is
Standard_LRS(Locally Redundant Storage),StorageV2kind, Hot access tier, TLS 1.2 minimum, public blob access disabled. - Two containers:
uploads(user files — sticker images, operative lists, timesheet PDFs) andcache(large tRPC payload caching for slow queries). - Blob Service CORS is configured so the SPA can
PUTdirectly via SAS URLs from the PPP web app origin only. - The backend's
AzureBlobProvidermints short-lived SAS tokens on demand — the storage account key is fetched from Key Vault once at startup.
Legacy AWS S3 (embrace-core-v3-assets) is still referenced for historical file URLs during the tail of the storage migration; all new uploads land in Blob Storage.
Caching — Azure Cache for Redis
- UAT:
Basic C0— no replication, single node. - Production:
Standard C1— primary + replica for failover. - TLS only (
rediss://on port 6380), non-SSL port disabled. - The backend uses Redis for two purposes via
PppCache:- Graceful-degradation cache — every cache call site treats a Redis miss/failure as a cache miss and falls through to Postgres, so a Redis outage slows but never breaks the app.
- Shared rate-limit store —
checkRateLimitAsyncinsrc/utils/rate-limiter.tsusesINCR+EXPIREso global caps (e.g. the 3-regenerates-per-24h cap on timesheet approval links) are enforced across all container replicas. When Redis is unavailable the limiter falls back to the in-processMap(fail-open, adequate for single-replica). (#5833)
Secrets — Azure Key Vault
- Standard SKU, RBAC-authorised (no legacy access policies), 7-day soft delete.
- Secrets include database credentials, Stripe API keys, Azure OpenAI keys, Better Auth signing secret, ACS connection string, Redis connection string, storage account key, and per-feature HMAC signing secrets.
- The Container App pulls secrets at template-render time — Pulumi reads them from Doppler (the single master secret store) and passes them into Key Vault so there's an audit trail and an operational rotation path.
- The
Key Vault Secrets Userrole is granted to both the Container App's Managed Identity (runtime) and the CD pipeline Service Principal (rotation + feature-flag wiring).
Identity — User-assigned Managed Identity
- One identity per environment.
- Roles:
AcrPullon the container registry,Key Vault Secrets Useron the vault. - The Container App runs under this identity, so nothing in the container image or environment variables holds long-lived Azure credentials.
Authentication — Better Auth (self-hosted)
PPP uses Better Auth, a database-backed self-hosted auth library, rather than a managed identity provider. It runs inside the Container App under /api/auth and persists sessions and accounts in the same PostgreSQL database as the application. Email + password is the primary sign-in method, and Entra ID (Microsoft) and Google SSO are wired in as additional social providers.
Microsoft (Entra ID) is provisioned via Pulumi as an Azure AD application registration in the same stack — the app's client ID and a rotating client secret flow straight into Key Vault and then into the Container App. Google credentials come from Doppler because they're created in the Google Cloud console.
AWS Cognito is still present in the dev environment for historical reasons, but UAT and Prod do not use it.
Transactional Email — Azure Communication Services
- Communication Service + Email Service + verified sender Domain (DNS-verified via TXT + DKIM CNAMEs managed in the Cloudflare stack).
- The ACS connection string is provisioned as a Pulumi output and stored in Key Vault for rotation.
- Diagnostic settings stream
EmailSendMail,EmailStatusUpdate, andEmailUserEngagementoperational logs into Log Analytics — this is what makes silent Hotmail/Outlook junk drops visible in Kusto.
ACS replaces SendGrid for all transactional email (password resets, CPD approvals, 360 review invitations, timesheet batches).
AI / OCR — Azure OpenAI
- Cognitive Services account (
S0SKU) with agpt-4o-minideployment on theGlobalStandardSKU. - Replaces Google Gemini for OCR of surgical stickers and operative lists. Structured outputs (
zodResponseFormat) mean the parser is type-safe end-to-end.
Observability — Log Analytics
- Log Analytics Workspace (
PerGB2018, 30-day retention) captures:- Container stdout/stderr and Container Apps system events via the environment's log forwarding agent.
- ACS email delivery diagnostics via a
DiagnosticSetting.
- Queryable via Kusto from the Azure Portal or the Monitor API.
- There is no separate Application Insights resource today. The combination of Log Analytics + Container Apps platform diagnostics + health probes is the full observability surface.
Feature Flags — Azure App Configuration
- Provisioned by the shared Pulumi stack (
ppp-uk-shared). - The marketing site's
/feature-flagsCloudflare Pages function reads the read-only connection string to serve flags to unauthenticated visitors (e.g.ppp-login-enabled). - Stack references pass the read-only connection string from the shared stack into Key Vault in each per-environment stack.
Cloudflare Edge
The Cloudflare side is provisioned by api/infra-cloudflare/ as two stacks — pppUat and pppProd. It is responsible for:
- DNS zone and every record under
professionalperformanceportfolio.com - Pages projects for the marketing site and the PPP web app
- Custom domain bindings linking Pages projects to subdomains
- Security Headers Ruleset — HSTS,
X-Content-Type-Options,X-Frame-Options,Referrer-Policy,Permissions-Policy, and a strictContent-Security-Policyinjected on every proxied response - Bot management and Browser Integrity Check on the zone
- WAF rules (managed and custom) for login abuse
wwwapex redirect via a List + Ruleset- Dev tunnel (Cloudflare Zero Trust Tunnel) for the shared development environment
SSL mode is Flexible between Cloudflare and the Azure Container App origin: TLS is terminated at Cloudflare, and traffic to the Container App ingress flows over HTTP on the internal *.azurecontainerapps.io hostname. This is because the Azure-managed ingress cert only covers *.azurecontainerapps.io, not the custom api-<env> subdomain.
Pulumi Project Layout
| Project | Location | Stacks |
|---|---|---|
| Shared Azure resources | api/infra-azure-shared/ | ppp-uk-shared |
| Per-environment Azure stacks | api/infra-azure/ | ppp-uk-uat, ppp-uk-prod |
| Cloudflare stacks | api/infra-cloudflare/ | pppUat, pppProd |
Pulumi state is stored in an Azure Blob backend (azblob://pulumi-state). Stack references pass the shared App Configuration connection string from the shared stack into each per-environment stack, and the Container App FQDN from each Azure stack into the matching Cloudflare stack so the api-<env> CNAME can be created idempotently.
Health Probes
The Container App exposes liveness and readiness probes on GET /healthz:
- Liveness — initial delay 30s, period 30s
- Readiness — initial delay 15s, period 10s
Scaling is set to 0–2 replicas on UAT (scale-to-zero is deliberate for cost). Cold start is ~10–30 s; the Cloudflare edge absorbs this for idle traffic.
Related Pages
- System Overview — end-to-end data flow
- Multi-Region Design — current state and target UK + AU design
- Timesheets feature spec — backend that uses the geo-fencing and batch email signing described here
- Mobile feature spec — mobile client that shares this tRPC contract
- Stripe Payments — payment integration overview