Hierarchical Tenancy & Cloudflare Integration

Hierarchical Tenancy & Cloudflare Integration

The z0 architecture is designed to scale from a single company to a massive multi-tenant platform.

1. Tenancy Levels

z0 supports a three-tier hierarchy for isolation and config inheritance:

Level	Identifier	Description
Platform	z0_TENANT_ID	The root owner (defined in wrangler.toml).
Tenant	tenant_id	Your customer (passed via LedgerClient or headers).
Sub-tenant	subtenant_id	Units within a customer (e.g., dept_marketing).

Scoping Strategy

We recommend using Segmented IDs for hierarchical tenancy: platform_id : tenant_id : subtenant_id

Example: acme-platform:nike:retail-us

2. Cloudflare Integration

Workers for Platforms

z0 is the perfect companion for Workers for Platforms.

• The Hub: Your “Dispatch Worker” handles routing and authentication.
• The Spokes: Each user-deployed script can define its own z0 ledgers.
• Isolation: Since each tenant_id gets its own Durable Object instance, you get physical database isolation for every customer on your platform.

Cloudflare for SaaS

Integrate z0 with Cloudflare for SaaS to provide custom domains for your tenants:

1. Map customer.com to your Worker via Custom Hostnames.
2. In your Worker, extract the hostname to determine the tenant_id.
3. z0 automatically routes all traffic for that hostname to the correct “mini-server” DO instance.

3. Configuration Inheritance

Invariants and configs flow down the hierarchy:

• Platform-level Invariants: Applied to everybody on the platform (e.g., “All payments >= 0”).
• Tenant-level Invariants: Specific to one customer (e.g., “Max discount 20%”).
• Entity-level Invariants: Only for one specific object.

Higher-level invariants/configs are immutable for lower levels, ensuring platform safety while allowing tenant flexibility.