This Architecture Design Document describes the technical architecture for the CSR Volunteer Management Platform deployed for John Keells Foundation, part of John Keells Holdings PLC. The platform enables enterprise-wide volunteer management, tracking, ratings, and impact reporting across all JKH business units.

The architecture is a fully managed, containerised deployment on Microsoft Azure with zero self-managed servers. Both the React web application and the n8n automation platform run as Azure Container Apps. All external traffic is routed exclusively through Cloudflare tunnels — no Azure resource has a public-facing origin endpoint. Outbound connectivity to Supabase is locked to a single fixed IP via NAT Gateway.

Figure 1: High-Level Architecture Diagram illustrating the five-layer deployment model — Users, Cloudflare Edge, Azure Container Apps, NAT Gateway, and External Services — for the CSR Volunteer Management Platform hosted on Azure (Southeast Asia / Singapore).

The two tenants serve entirely separate purposes. jkhmgmt.onmicrosoft.com is used solely for Azure subscription hosting — it contains no users and no app registrations. keells.onmicrosoft.com holds all JKH employees and is the tenant where all app registrations are created, including both the n8n automation registration and the Supabase Auth SSO registration. They do not interact.

All subdomains are exclusively under johnkeellsfoundation.com. DNS is managed by Cloudflare. The api subdomain is reserved — no DNS record should be created until required.

All Azure resources follow the pattern: JKH-{ENV}-FND-{TYPE}-{INSTANCE}

Inbound DenyAll is the primary perimeter — both Container Apps have internal-only ingress so no legitimate inbound traffic arrives directly. All external traffic arrives via outbound Cloudflare tunnels.

All credentials are managed through two secure stores. No secret is stored in source code, Docker images, or configuration files committed to GitHub.

This platform involves two distinct Entra ID tenants serving entirely different purposes. They must never be confused:

Both app registrations — the n8n automation registration and the Supabase Auth SSO registration — are created in keells.onmicrosoft.com. The jkhmgmt.onmicrosoft.com tenant is used exclusively for the Azure subscription and contains no users or app registrations.

This is a new, separate app registration required to enable Microsoft Entra ID as the SSO identity provider for volunteer and employee login via Supabase Auth. It is entirely separate from the n8n registration but resides in the same keells.onmicrosoft.com tenant.

This registration must be created in the keells.onmicrosoft.com tenant. JKH employees authenticate with their @keells.com Microsoft accounts, which live in the keells tenant. All app registrations for this platform reside in this tenant.

Feature B.19 specifies that the volunteer's SAP number is automatically populated from the Microsoft identity platform during sign-in. This requires the SAP employee ID to be stored as a custom or extension attribute on the user's Entra ID profile in keells.onmicrosoft.com.

Once confirmed, the Supabase Auth hook reads this attribute at login and populates the SAP Number field on the volunteer profile. It will not overwrite manual entries per B.19 specification.

The following optional claims must be added to the token configuration in the Azure Portal:

In Azure Portal → App Registration → Token configuration → Add optional claim → ID token:

For the groups claim: Token configuration → Add groups claim → Security groups → ID token.

Group IDs are returned as GUIDs in the token. A mapping table in the platform (configured by Central Admin per SC.6) maps these GUIDs to Business Units. JKH IT must provide the Entra ID group GUIDs that correspond to each Business Unit.

The client secret is entered directly into the Supabase Auth provider configuration. It is never stored in code, GitHub, or any config file.

Once the app registration is created, configure in Supabase Dashboard → Authentication → Providers → Azure:

In Entra ID app registration → Authentication → Redirect URIs:

In Supabase Dashboard → Authentication → URL Configuration:

LinkedIn OAuth is provided as a secondary sign-in path for non-Entra ID users (e.g. external partners, contractors, or alumni who do not hold a @keells.com Microsoft account).

RLS must be enabled and verified on all tables in the csr_app schema before go-live. The anon key used by the frontend grants zero access beyond what RLS policies explicitly permit.

The React app uses Supabase Realtime for live in-app notifications (Feature B.15). Each active user maintains a persistent WebSocket connection. At 600 concurrent users this consumes 600 of the available 600 pooled connections — leaving no headroom for REST API calls and direct n8n PostgreSQL connections.

Teams integration is handled entirely through n8n workflows using the Microsoft Graph API:

n8n is not in the CI/CD pipeline — it uses the official n8nio/n8n image updated manually via a pinned version tag.

Cloudflare CDN caches all static assets at the edge. Only HTML requests and API calls reach the origin container.

Estimated effective concurrent connections at origin for 600 concurrent users: 120–180 (20–30% of total).

Minimum 2 replicas eliminates cold-start delay for the first users. Scale-in cooldown is 120s to prevent thrashing during sustained load.

Before go-live, a load test against the staging environment should validate the revised sizing.

Supabase Pro Plan includes automated daily backups with point-in-time recovery (PITR).

The following sequence must be followed exactly. Steps are ordered to satisfy dependencies — each step assumes all prior steps are complete.

The platform is a Progressive Web App (PWA) built on React 19.

Internet Explorer is not supported. Chromium-based browsers are recommended for the best experience.

Microsoft Entra ID and SharePoint are included in existing JKH Microsoft 365 subscriptions. AI translation (Google Translate API) is usage-based and billed separately via Google Cloud. Cost increase versus v2.0 estimate is driven by web app container scaling headroom (max 10 replicas vs 3) required to support up to 1,500 concurrent users.