name: multi-tenant-platform-architecture
description: Cloudflare-first architecture guidance for multi-tenant platforms where tenants own their space. Use when defining domain strategy, tenant isolation, Workers for Platforms routing, custom domains, and plan/limit mapping for untrusted tenant code or UGC.

Multi-Tenant Platform Architecture (Cloudflare-first)

Workflow (order matters)

1. Choose domain strategy
2. Use a dedicated tenant domain (separate from the brand domain) for all subdomains/custom hostnames.
3. Consider PSL for browser cookie isolation; it does not protect reputation. See references/psl.md.

4. Start PSL submission early; review can take weeks.

5. Define isolation model

6. Prefer per-tenant Workers for untrusted code (Workers for Platforms).

7. Avoid shared-tenant branching unless you fully control code and data.

8. Route traffic deterministically

9. Platform Worker owns routing/policy; hostname -> tenant id -> dispatch namespace -> tenant Worker.

10. 404 when no mapping exists; tenants never control routing or see each other.

11. Bind only what is needed

12. Least-privilege bindings per tenant (DB/storage/limited platform API), no shared global state.

13. Treat new bindings as explicit changes; redeploy to grant access.

14. Support custom domains

15. Provide DNS target, verify ownership, store mapping, and route by hostname.
16. Use Cloudflare for SaaS custom hostnames + managed certs. See references/cloudflare-platform.md.

17. Custom domains shift reputation to the tenant and segment users.

18. Surface limits as plans

19. Map CPU/memory/request limits to tiers; expose in API + UI.
20. Do not run long jobs in requests; use queues/workflows.

21. See references/limits-and-quotas.md for current limits.

22. Make the API the product

23. Everything works over HTTP; UI is for ops/incident/billing.
24. Platform logic stays in the routing Worker; tenant Workers serve requests.

25. If it only works in the UI, the platform is leaking.

26. Extend without breaking boundaries

27. Add queues/workflows/containers as optional modes.
28. Keep routing explicit and isolation intact.

Deliverables

• Domain map: brand vs tenant domain, PSL plan, custom domain flow
• Isolation plan: per-tenant Workers + dispatch namespace layout
• Routing plan: hostname lookup, dispatch logic, fallback behavior
• Binding matrix: per-tenant capabilities and data access
• Limits-to-pricing map: CPU/memory/request budgets per tier
• API surface + ops UI scope

References to load

• PSL submission and cookie isolation: references/psl.md
• Cloudflare platform primitives and routing: references/cloudflare-platform.md
• Worker limits and plan mapping: references/limits-and-quotas.md

Pre-commit checklist

• Tenant workloads off the brand domain; PSL decision + timeline set
• Untrusted isolation for tenant code; dispatch routing authoritative and tenant-blind
• Custom domain onboarding defined; limits tied to billing; API parity with UI