GRPE

ZAYAZ Global Routing Policy Engine

1. Purpose

The ZAYAZ Global Routing Policy Engine (GRPE) is the authoritative decision engine that determines where a tenant request must be routed at runtime.

GRPE exists to translate:

tenant routing policy,
platform residency policy,
regional health state,
disaster recovery state,
and maintenance overrides

into a deterministic routing decision.

GRPE is a policy engine, not a transport layer.

It does not:

terminate TLS,
resolve DNS,
authenticate users,
or execute ESG business logic.

Instead, it produces a routing decision that is then used by:

Cloudflare Workers,
regional API ingress,
control-plane services,
and internal routers.

2. Design Principles

GRPE MUST follow these principles:

Tenant-centric routing
All routing is based on tenant policy, never on end-user geolocation.
Data residency first
Routing must not violate the tenant’s legal data residency configuration.
Region determinism
A tenant has one active region at any point in time.
Policy over infrastructure
GRPE decides what should happen; infrastructure executes it.
Controlled resilience
Failover behavior is explicit and governed by dr_mode, not by silent heuristics.
Auditability
Every routing decision must be reproducible and explainable.

3. What GRPE Must Decide

GRPE must decide:

whether the tenant remains in primary_region
whether the tenant may use secondary_region
whether dr_region_sr or dr_region_rr may be activated
whether routing must be blocked because no compliant region is available
whether platform maintenance overrides all normal routing
what the effective active_region is
what the final resolved_origin is

GRPE must never decide based on:

request IP geolocation
browser locale
nearest AWS region
CDN edge location

4. Architectural Position

4.1. Control Plane vs Data Plane

Control Plane
Global components that determine routing:
- tenant registry
- auth
- Cloudflare Worker
- GRPE
- residency region policy
- platform routing state
Data Plane
Regional components that execute tenant workloads:
- api.<region>.zayaz.io
- regional storage
- regional compute
- regional queues
- regional KMS and S3

GRPE sits between the two.

4.2. Runtime Flow

5. Authoritative Inputs

GRPE consumes three categories of authoritative inputs.

5.1. Tenant Routing Policy

Tenant-specific, contract-bound input.

Example runtime shape:

example-runtime-shape.tsGitHub ↗
type TenantStatus = "active" | "inactive" | "suspended" | "maintenance";
type OriginTarget = "app_prod" | "app_maintenance" | "sandbox_default";

type Region =
  | "af-south-1"
  | "ap-northeast-1"
  | "ap-northeast-2"
  | "ap-northeast-3"
  | "ap-south-1"
  | "ap-southeast-1"
  | "ap-southeast-2"
  | "eu-central-1"
  | "eu-north-1"
  | "eu-west-1"
  | "eu-west-2"
  | "eu-west-3"
  | "me-central-1"
  | "sa-east-1"
  | "us-east-1"
  | "us-east-2"
  | "us-west-1"
  | "us-west-2";

type ResidencyZone = "af" | "as" | "oc" | "eu" | "me" | "sa" | "na";

interface TenantRoutingPolicy {
  client_id: string;
  legal_country: string;
  primary_region: Region;
  data_residency_zone: ResidencyZone;
  dr_mode: "sr" | "rr";
  dr_activation: "never" | "emergency_only" | "preapproved";
  dr_legal_basis?: string;
  status: TenantStatus;
  origin_target: OriginTarget;
  auth_profile_id: string;
  css_sssr_ref: string;
  logo_sssr_ref: string;
}

Example onboarding-derived payload:

example-onboarding-derived-payload.jsonGitHub ↗
{
  "user_id": "ECO-276-...",
  "legal_country": "DE",
  "primary_region": "eu-north-1",
  "data_residency_zone": "eu",
  "dr_mode": "sr",
  "dr_activation": "emergency_only",
  "dr_legal_basis": "contractual_consent"
}

5.2. Residency Region Policy

The file residency_region_policy.json is the authoritative platform-governed map of:

primary region
zone
secondary region
strict-residency DR region
resilient-residency DR region
whether RR is allowed

This policy is authoritative input to GRPE.

Runtime shape:

rrp-runtime-shape.tsGitHub ↗
/**
 * Supported regions
 */
type Region =
  | "eu-north-1"
  | "eu-central-1"
  | "us-east-1";

/**
 * Residency zones
 */
type ResidencyZone =
  | "EU"
  | "US"
  | "GLOBAL";

/**
 * Encryption policy
 */
type EncryptionPolicy = "sse_kms_required";

/**
 * Residency Region Policy Entry
 */
export interface ResidencyRegionPolicyEntry {
  zone: ResidencyZone;
  primary_region: Region;
  secondary_region: Region;
  dr_region_sr: Region;
  dr_region_rr: Region | null;
  rr_allowed: boolean;
  dr_encryption: EncryptionPolicy;
  notes?: string;
}

/**
 * Example usage
 */
const examplePolicy: ResidencyRegionPolicyEntry = {
  zone: "EU",
  primary_region: "eu-north-1",
  secondary_region: "eu-central-1",
  dr_region_sr: "eu-central-1",
  dr_region_rr: null,
  rr_allowed: false,
  dr_encryption: "sse_kms_required",
  notes: "EU data must remain within EU regions"
};

console.log(examplePolicy);

This policy is immutable at runtime and only changes through controlled release/versioning.

5.3. Platform Routing State

Operational runtime state used by GRPE.

operational-runtime-state.tsGitHub ↗
/**
 * Supported regions
 */
type Region =
  | "eu-north-1"
  | "eu-central-1"
  | "us-east-1";

/**
 * Region health states
 */
type RegionHealth = "healthy" | "degraded" | "down";

/**
 * Platform Routing State
 */
export interface PlatformRoutingState {
  force_maintenance: boolean;

  /**
   * Health status per region (optional per region)
   */
  region_health: Partial<Record<Region, RegionHealth>>;

  /**
   * Regions currently declared under disaster recovery
   */
  dr_declared_regions: Region[];

  /**
   * Regions blocked due to compliance / outage / policy
   */
  blocked_regions?: Region[];

  /**
   * Version identifier for policy tracking / audit
   */
  policy_version?: string;
}

/**
 * Example usage
 */
const exampleState: PlatformRoutingState = {
  force_maintenance: false,
  region_health: {
    "eu-north-1": "healthy",
    "eu-central-1": "degraded",
    "us-east-1": "down"
  },
  dr_declared_regions: ["eu-central-1"],
  blocked_regions: ["us-east-1"],
  policy_version: "v2026.03.21"
};

console.log(exampleState);

This state is not contractual. It is operational and may change during incidents.

6. Derived Routing Concepts

GRPE computes or consumes the following concepts.

6.1. secondary_region

Derived from residency_region_policy[primary_region].secondary_region.

6.2. dr_effective_region

Derived as:

if tenant.dr_mode == "sr":
    dr_effective_region = dr_region_sr
else if tenant.dr_mode == "rr":
    dr_effective_region = dr_region_rr

6.3. active_region

The region that will actually serve the request now.

Usually:

active_region = primary_region

But may become:

secondary_region
dr_region_sr
dr_region_rr

depending on policy and state.

7. Outputs

GRPE must return a deterministic decision object.

output.tsGitHub ↗
/**
 * Supported regions
 */
type Region =
  | "eu-north-1"
  | "eu-central-1"
  | "us-east-1";

/**
 * Routing mode
 */
type RoutingMode =
  | "primary"
  | "secondary"
  | "dr"
  | "maintenance"
  | "blocked";

/**
 * Compliance decision
 */
type ComplianceDecision = "allowed" | "denied";

/**
 * Routing decision
 */
export interface RoutingDecision {
  client_id: string;
  routing_mode: RoutingMode;
  active_region?: Region;
  resolved_origin: string;
  compliance_decision: ComplianceDecision;
  failover_reason?: string;
  policy_version?: string;
}

/**
 * Example usage
 */
const exampleDecision: RoutingDecision = {
  client_id: "client-eco-001",
  routing_mode: "primary",
  active_region: "eu-north-1",
  resolved_origin: "https://eu-north-1.app.zayaz.io",
  compliance_decision: "allowed",
  policy_version: "v2026.03.21"
};

console.log(exampleDecision);

7.1. Output semantics

routing_mode Explains what class of routing was selected.
active_region The effective region chosen for the request, if applicable.
resolved_origin The final host/URL the request should be routed to.
compliance_decision Whether the selected outcome is compliant with tenant residency/DR policy.
failover_reason Human-readable explanation when not on primary.

8. Region Policy Source

The following policy map is authoritative for primary, secondary, SR DR, and RR DR behavior.

8.1. Policy Notes

The policy includes, per primary region:

zone
primary_region
secondary_region
dr_region_sr
dr_region_rr
rr_allowed
encryption rule
explanatory notes

Examples from the policy:

eu-north-1 → secondary eu-west-1, SR DR eu-west-3, RR not allowed
af-south-1 → same-region SR only, RR DR eu-west-1
sa-east-1 → same-region SR only, RR DR us-east-1

8.2. Full JSON Source

GRPE uses the authoritative residency_region_policy.json defined in the AWS Usage & Tenant Routing Architecture specification.

9. Decision Rules

GRPE must apply rules in a fixed order.

9.1. Rule Order

Global maintenance override
Tenant status validation
Origin target short-circuiting
Primary region evaluation
Secondary region evaluation
DR evaluation
Compliance validation
Final origin resolution
Block if no compliant target exists

9.2. Maintenance Override

If platform maintenance is forced:

all tenant requests route to maintenance origin
unless explicitly exempted by future policy extensions

Example outcome:

example-outcome.jsonGitHub ↗
{
  "client_id": "eco-173-123-456-789",
  "routing_mode": "maintenance",
  "resolved_origin": "https://maintenance.zayaz.io",
  "compliance_decision": "allowed"
}

9.3. Tenant Status Rules

If tenant is:

inactive
suspended

GRPE must not route to regional application origin.

If tenant is:

maintenance

GRPE routes to maintenance origin.

9.4. Origin Target Rules

If origin_target is:

sandbox_default → route to sandbox origin
app_maintenance → route to maintenance origin
app_prod → continue normal regional routing

9.5. Primary Region Rule

If primary_region is healthy and not blocked:

active_region = primary_region
routing_mode = primary

9.6. Secondary Region Rule

If primary_region is not healthy enough for routing, GRPE may evaluate secondary_region.

This is a platform resilience optimization layer, not a legal DR event.

Use of secondary_region is allowed only if:

it is defined in policy
it is in the same permitted zone/policy envelope
the platform state allows non-DR failover
future policy settings do not disable it

If not used, GRPE proceeds to DR evaluation.

9.7. Strict Residency DR Rule (dr_mode = "sr")

If tenant is in SR mode:

GRPE may only activate dr_region_sr
dr_region_rr must never be used
no cross-zone DR is allowed

9.8. Resilient Residency DR Rule (dr_mode = "rr")

If tenant is in RR mode:

rr_allowed must be true in policy
GRPE may activate dr_region_rr
activation must respect dr_activation
dr_legal_basis must exist when required

9.9. DR Activation Rules

If dr_activation = "never":

no DR routing allowed

If dr_activation = "emergency_only":

DR routing only if platform state indicates declared disaster conditions

If dr_activation = "preapproved":

DR routing may proceed under pre-approved platform failover conditions

9.10. Compliance Validation

GRPE must validate that the resulting region is lawful for the tenant.

Validation includes:

residency zone compatibility
DR mode compatibility
RR allow-list compatibility
legal basis where required

If validation fails:

compliance_decision = denied
routing must be blocked or diverted to maintenance

10. Origin Resolution

GRPE chooses region and mode. A separate origin resolver translates the result to a concrete host.

10.1. Regional API Host Convention

regional-api-host-convention.tsGitHub ↗
/**
 * Supported regions
 */
type Region =
  | "eu-north-1"
  | "eu-central-1"
  | "us-east-1";

/**
 * Resolve regional API host
 */
export function regionalApiHost(region: Region): string {
  return `https://api.${region}.zayaz.io`;
}

/**
 * Example usage
 */
const apiUrl = regionalApiHost("eu-north-1");
console.log(apiUrl);

Examples:

eu-north-1 → https://api.eu-north-1.zayaz.io
us-east-1 → https://api.us-east-1.zayaz.io

10.2. Static Origins

static-origins.tsGitHub ↗
const STATIC_ORIGINS = {
  app_maintenance: "https://maintenance.zayaz.io",
  sandbox_default: "https://sandbox.zayaz.dev"
} as const;

11. Reference Implementation (TypeScript)

reference-implementation.tsGitHub ↗
type TenantStatus = "active" | "inactive" | "suspended" | "maintenance";
type OriginTarget = "app_prod" | "app_maintenance" | "sandbox_default";
type RegionHealth = "healthy" | "degraded" | "down";

type Region =
  | "af-south-1"
  | "ap-northeast-1"
  | "ap-northeast-2"
  | "ap-northeast-3"
  | "ap-south-1"
  | "ap-southeast-1"
  | "ap-southeast-2"
  | "eu-central-1"
  | "eu-north-1"
  | "eu-west-1"
  | "eu-west-2"
  | "eu-west-3"
  | "me-central-1"
  | "sa-east-1"
  | "us-east-1"
  | "us-east-2"
  | "us-west-1"
  | "us-west-2";

type ResidencyZone = "af" | "as" | "oc" | "eu" | "me" | "sa" | "na";

interface TenantRoutingPolicy {
  client_id: string;
  legal_country: string;
  primary_region: Region;
  data_residency_zone: ResidencyZone;
  dr_mode: "sr" | "rr";
  dr_activation: "never" | "emergency_only" | "preapproved";
  dr_legal_basis?: string;
  status: TenantStatus;
  origin_target: OriginTarget;
  auth_profile_id: string;
  css_sssr_ref: string;
  logo_sssr_ref: string;
}

interface ResidencyRegionPolicyEntry {
  zone: ResidencyZone;
  primary_region: Region;
  secondary_region: Region;
  dr_region_sr: Region;
  dr_region_rr: Region | null;
  rr_allowed: boolean;
  dr_encryption: "sse_kms_required";
  notes?: string;
}

interface PlatformRoutingState {
  force_maintenance: boolean;
  region_health: Partial<Record<Region, RegionHealth>>;
  dr_declared_regions: Region[];
  blocked_regions?: Region[];
  policy_version?: string;
  allow_secondary_failover?: boolean;
}

interface RoutingDecision {
  client_id: string;
  routing_mode: "primary" | "secondary" | "dr" | "maintenance" | "blocked";
  active_region?: Region;
  resolved_origin: string;
  compliance_decision: "allowed" | "denied";
  failover_reason?: string;
  policy_version?: string;
}

function regionalApiHost(region: Region): string {
  return `https://api.${region}.zayaz.io`;
}

const STATIC_ORIGINS = {
  app_maintenance: "https://maintenance.zayaz.io",
  sandbox_default: "https://sandbox.zayaz.dev"
} as const;

function isRegionBlocked(region: Region, state: PlatformRoutingState): boolean {
  return (state.blocked_regions ?? []).includes(region);
}

function isRegionUsable(region: Region, state: PlatformRoutingState): boolean {
  const health = state.region_health[region] ?? "healthy";
  return health === "healthy" || health === "degraded";
}

function isDeclaredDrRegion(region: Region, state: PlatformRoutingState): boolean {
  return state.dr_declared_regions.includes(region);
}

function resolveRoutingDecision(
  tenant: TenantRoutingPolicy,
  regionPolicy: ResidencyRegionPolicyEntry,
  state: PlatformRoutingState
): RoutingDecision {
  if (state.force_maintenance || tenant.status === "maintenance") {
    return {
      client_id: tenant.client_id,
      routing_mode: "maintenance",
      resolved_origin: STATIC_ORIGINS.app_maintenance,
      compliance_decision: "allowed",
      policy_version: state.policy_version
    };
  }

  if (tenant.status === "inactive" || tenant.status === "suspended") {
    return {
      client_id: tenant.client_id,
      routing_mode: "blocked",
      resolved_origin: STATIC_ORIGINS.app_maintenance,
      compliance_decision: "denied",
      failover_reason: `tenant_status_${tenant.status}`,
      policy_version: state.policy_version
    };
  }

  if (tenant.origin_target === "sandbox_default") {
    return {
      client_id: tenant.client_id,
      routing_mode: "primary",
      resolved_origin: STATIC_ORIGINS.sandbox_default,
      compliance_decision: "allowed",
      policy_version: state.policy_version
    };
  }

  if (tenant.origin_target === "app_maintenance") {
    return {
      client_id: tenant.client_id,
      routing_mode: "maintenance",
      resolved_origin: STATIC_ORIGINS.app_maintenance,
      compliance_decision: "allowed",
      policy_version: state.policy_version
    };
  }

  if (
    !isRegionBlocked(tenant.primary_region, state) &&
    isRegionUsable(tenant.primary_region, state)
  ) {
    return {
      client_id: tenant.client_id,
      routing_mode: "primary",
      active_region: tenant.primary_region,
      resolved_origin: regionalApiHost(tenant.primary_region),
      compliance_decision: "allowed",
      policy_version: state.policy_version
    };
  }

  if (
    state.allow_secondary_failover &&
    regionPolicy.secondary_region &&
    !isRegionBlocked(regionPolicy.secondary_region, state) &&
    isRegionUsable(regionPolicy.secondary_region, state) &&
    regionPolicy.zone === tenant.data_residency_zone
  ) {
    return {
      client_id: tenant.client_id,
      routing_mode: "secondary",
      active_region: regionPolicy.secondary_region,
      resolved_origin: regionalApiHost(regionPolicy.secondary_region),
      compliance_decision: "allowed",
      failover_reason: "primary_region_unavailable_secondary_used",
      policy_version: state.policy_version
    };
  }

  if (tenant.dr_mode === "sr") {
    const dr = regionPolicy.dr_region_sr;
    if (
      dr &&
      !isRegionBlocked(dr, state) &&
      isRegionUsable(dr, state) &&
      regionPolicy.zone === tenant.data_residency_zone &&
      (tenant.dr_activation === "preapproved" ||
        (tenant.dr_activation === "emergency_only" && isDeclaredDrRegion(dr, state)))
    ) {
      return {
        client_id: tenant.client_id,
        routing_mode: "dr",
        active_region: dr,
        resolved_origin: regionalApiHost(dr),
        compliance_decision: "allowed",
        failover_reason: "strict_residency_dr",
        policy_version: state.policy_version
      };
    }
  }

  if (tenant.dr_mode === "rr" && regionPolicy.rr_allowed && regionPolicy.dr_region_rr) {
    const dr = regionPolicy.dr_region_rr;
    if (
      !isRegionBlocked(dr, state) &&
      isRegionUsable(dr, state) &&
      tenant.dr_legal_basis &&
      (tenant.dr_activation === "preapproved" ||
        (tenant.dr_activation === "emergency_only" && isDeclaredDrRegion(dr, state)))
    ) {
      return {
        client_id: tenant.client_id,
        routing_mode: "dr",
        active_region: dr,
        resolved_origin: regionalApiHost(dr),
        compliance_decision: "allowed",
        failover_reason: "resilient_residency_dr",
        policy_version: state.policy_version
      };
    }
  }

  return {
    client_id: tenant.client_id,
    routing_mode: "blocked",
    resolved_origin: STATIC_ORIGINS.app_maintenance,
    compliance_decision: "denied",
    failover_reason: "no_compliant_region_available",
    policy_version: state.policy_version
  };
}

12. Decision Table (Simplified)

Tenant state	Primary healthy	Secondary allowed	DR allowed	Outcome
active	yes	n/a	n/a	primary
active	no	yes	n/a	secondary
active + SR	no	no	yes	dr_region_sr
active + RR	no	no	yes	dr_region_rr
inactive	n/a	n/a	n/a	blocked
suspended	n/a	n/a	n/a	blocked
maintenance	n/a	n/a	n/a	maintenance

13. Cloudflare Worker Integration

GRPE should not be embedded as ad hoc logic inside worker.ts.

Preferred module split:

tenant-policy.ts
residency-policy.ts
platform-routing-state.ts
grpe.ts
origin-resolver.ts
worker.ts

13.1. Worker Flow

14. KV Snapshot Requirements

The Worker-side KV snapshot should include enough policy to avoid a live control-plane lookup on every request.

Recommended payload:

kv-snapshot.jsonGitHub ↗
{
  "client_id": "eco-173-123-456-789",
  "tenant_slug": "acme",
  "hostname": "acme.zayaz.cloud",
  "status": "active",
  "origin_target": "app_prod",
  "primary_region": "eu-north-1",
  "data_residency_zone": "eu",
  "dr_mode": "sr",
  "dr_activation": "emergency_only",
  "dr_legal_basis": "contractual_consent",
  "css_sssr_ref": "sssr:asset.client-profiles.css.css @ eco-173-123-456-789",
  "logo_sssr_ref": "sssr:asset.client-profiles.main-logo.gif @ eco-173-123-456-789",
  "auth_profile_id": "auth_acme_v1"
}

15. Observability & Audit

Every GRPE decision must be loggable.

Minimum audit payload:

minimum-audit-payload.jsonGitHub ↗
{
  "client_id": "eco-173-123-456-789",
  "primary_region": "eu-north-1",
  "routing_mode": "primary",
  "active_region": "eu-north-1",
  "resolved_origin": "https://api.eu-north-1.zayaz.io",
  "compliance_decision": "allowed",
  "failover_reason": null,
  "policy_version": "2026-03-21",
  "timestamp": "2026-03-21T12:00:00Z"
}

Events should be emitted for:

primary routing success
secondary routing success
DR activation
compliance denial
blocked routing
maintenance override

These events should feed:

ALTD
telemetry/ops dashboards
post-incident analysis
compliance review

16. Non-Negotiable Invariants

Routing is policy-driven, never geolocation-driven
Tenant policy is authoritative
primary_region is sticky until migration
GRPE never chooses an unlawful region
dr_region_rr must never be used unless RR is both allowed and legally activated
Maintenance override must remain explicit
Every decision must be reproducible from inputs

17. Future Extensions

GRPE may later support:

compliance profiles
sovereign cloud rules
tenant tier-based routing classes
maintenance exemptions
latency-aware ranking within legally allowed candidates
formal decision traces / signed routing attestations

Any extension must preserve:

determinism
auditability
policy-first routing

18. Summary

ZAYAZ GRPE is the formal runtime decision engine for tenant routing.

It converts:

tenant policy,
residency region policy,
and platform routing state

into:

compliant region selection,
deterministic origin resolution,
and auditable runtime behavior.

It is the layer that ensures ZAYAZ can always answer:

Where is tenant X being routed right now?
Why was that region selected?
Was the choice policy-compliant?
Under what DR or maintenance state did that happen?

That makes GRPE a core infrastructure and compliance component of the ZAYAZ platform.

GitHub Repo Request for Change (RFC)

1. Purpose​

2. Design Principles​

3. What GRPE Must Decide​

4. Architectural Position​

4.1. Control Plane vs Data Plane​

4.2. Runtime Flow​

5. Authoritative Inputs​

5.1. Tenant Routing Policy​

5.2. Residency Region Policy​

5.3. Platform Routing State​

6. Derived Routing Concepts​

6.1. secondary_region​

6.2. dr_effective_region​

6.3. active_region​

7. Outputs​

7.1. Output semantics​

8. Region Policy Source​

8.1. Policy Notes​

8.2. Full JSON Source​

9. Decision Rules​

9.1. Rule Order​

9.2. Maintenance Override​

9.3. Tenant Status Rules​

9.4. Origin Target Rules​

9.5. Primary Region Rule​

9.6. Secondary Region Rule​

9.7. Strict Residency DR Rule (dr_mode = "sr")​

9.8. Resilient Residency DR Rule (dr_mode = "rr")​

9.9. DR Activation Rules​

9.10. Compliance Validation​

10. Origin Resolution​

10.1. Regional API Host Convention​

10.2. Static Origins​

11. Reference Implementation (TypeScript)​

12. Decision Table (Simplified)​

13. Cloudflare Worker Integration​

13.1. Worker Flow​

14. KV Snapshot Requirements​

15. Observability & Audit​

16. Non-Negotiable Invariants​

17. Future Extensions​

18. Summary​