Multi Tenant Architecture

Multi-Tenant Platform Architecture (Cloudflare or Vercel)

• IS: domain strategy, tenant identification and isolation, subdomain routing, custom domains, white-label setup, and plan/limit mapping on Cloudflare or Vercel.
• IS NOT: general app folder structure or module boundaries (use define-architecture), or scaffolding a new repo (use scaffold-nextjs).

Contents

• Platform dispatch (decide first)
• Workflow (order matters)
• Gotchas
• Deliverables
• Pre-commit checklist
• Related skills

Platform dispatch (decide first)

• Pick one platform and commit; do not mix hosting. Hybrid setups create routing complexity that compounds.
• Load only the chosen platform's references unless explicitly comparing the two.
• Always load psl.md when deciding domain strategy (step 1).
• Load limits-and-quotas.md before mapping limits to pricing (step 8).

Workflow (order matters)

1. Choose domain strategy

• Use a dedicated tenant domain (separate from the brand domain) for all subdomains and custom hostnames. Reputation does not isolate; a phishing site on random.acme.com damages the whole domain.
• Register a separate TLD for tenant workloads (e.g. acme.app for tenants, acme.com for brand).
• Consider PSL for browser cookie isolation; it does not protect reputation. See psl.md.
• Start PSL submission early; review can take weeks.

2. Choose tenant identification strategy

• Subdomain-based: tenant.yourdomain.com. Requires wildcard DNS. Simplest for many tenants.
• Custom domain: tenant brings their own domain and CNAMEs to your platform. Best for serious or paying tenants.
• Path-based: yourdomain.com/tenant-slug. No per-tenant DNS/SSL, but limits branding and complicates cookie isolation.
• Pick one primary strategy; offer custom domain as an upgrade path.

3. Define isolation model

• Cloudflare: per-tenant Workers via dispatch namespaces for untrusted code. Avoid shared-tenant branching unless you fully control code and data.
• Vercel: single shared Next.js app with tenant_id scoping. Middleware resolves tenant from hostname; every data query includes tenant context. Use Postgres RLS for defence-in-depth.

4. Route traffic deterministically

• Cloudflare: the platform Worker owns routing; hostname -> tenant id -> dispatch namespace -> tenant Worker. 404 when no mapping exists.
• Vercel: Middleware extracts the hostname and rewrites to a /domains/[domain] dynamic segment. Edge Config for sub-millisecond tenant lookups. 404 when no mapping exists.
• Tenants never control routing or see each other on either platform.

5. Pass tenant context through the stack

• Cloudflare: the platform Worker resolves the tenant and injects headers or bindings before dispatching to the tenant Worker.
• Vercel: Middleware sets x-tenant-id, x-tenant-slug, x-tenant-plan on the forwarded request headers (not the response). Server Components read via headers(); API routes read from request headers:

  // middleware.ts
  import { NextRequest, NextResponse } from "next/server";
  export function middleware(request: NextRequest) {
    const hostname = request.headers.get("host") ?? "";
    const tenant = hostname.split(".")[0]; // resolve from Edge Config/DB in production
    const requestHeaders = new Headers(request.headers);
    requestHeaders.set("x-tenant-id", tenant);
    return NextResponse.next({ request: { headers: requestHeaders } });
  }

• The Middleware or platform Worker is the single authority; never trust client-supplied tenant identity.

6. Bind only what is needed

• Cloudflare: least-privilege bindings per tenant (DB/storage/limited platform API), no shared global state. Treat new bindings as explicit changes; redeploy to grant access.
• Vercel: Edge Config for tenant config (domain mappings, feature flags, plan info). @vercel/sdk for domain management. Database connections scoped by tenant_id, or database-per-tenant (Neon).

7. Support custom domains and per-tenant static files

• Provide a DNS target, verify ownership, store the mapping, route by hostname.
• Cloudflare: Cloudflare for SaaS custom hostnames with managed certs. See cloudflare-platform.md.
• Vercel: @vercel/sdk for programmatic domain CRUD plus automatic Let's Encrypt SSL; wildcard subdomains require Vercel nameservers. See vercel-domains.md.
• Custom domains shift reputation to the tenant and create natural user segments (casual on platform domain, serious on their own domain).
• robots.txt, sitemap.xml, llms.txt must vary by tenant; never serve them from /public. Cloudflare: generate in the tenant Worker. Vercel: route handlers under the domain segment (see vercel-platform.md).

8. Surface limits as plans

• Map platform limits to pricing tiers; expose them in the API and UI.
• Do not run long jobs in requests; use queues or workflows.
• See limits-and-quotas.md for limits snapshots and source links; re-check official docs before final architecture or pricing decisions.

9. Make the API the product

• Everything works over HTTP; the UI is for ops, incidents, and billing.
• Platform logic stays in the routing layer (dispatch Worker or Middleware); tenant content serves requests.
• If it only works in the UI, the platform is leaking.

10. Extend without breaking boundaries

• Add queues, workflows, or containers as optional modes.
• Keep routing explicit and isolation intact.

Gotchas

• Don't use the brand domain for tenant subdomains: a phishing site on random.acme.com damages the entire acme.com reputation. Register a separate TLD for tenant workloads.
• Don't skip PSL submission when subdomains host untrusted content: review takes weeks, not days, and the cookie-isolation timeline slips with it.
• Don't trust client-supplied tenant identity, even behind auth. The Middleware or platform Worker is the single authority for tenant resolution.
• Don't set tenant headers on the Middleware response object: headers() in Server Components reads forwarded request headers, so use NextResponse.next({ request: { headers } }) or the tenant id never arrives.
• Don't mix hosting platforms: pick Cloudflare or Vercel and commit. Hybrid setups create routing complexity that compounds.
• Don't start with path-based tenancy if custom domains are on the roadmap: migrating later requires URL rewrites, cookie changes, and DNS migration.
• Don't share database connections across tenants without RLS or tenant_id scoping: one missing WHERE clause leaks another tenant's data.
• Don't block /.well-known/acme-challenge/* with Middleware or redirects: Let's Encrypt HTTP-01 validation fails and custom-domain SSL never issues.
• Don't treat Edge Config writes as instant: propagation takes up to 10 seconds, so a "domain connected" UI that reads Edge Config immediately shows stale state.

Deliverables

• Platform choice rationale: Cloudflare vs Vercel with justification
• Tenant identification strategy: subdomain, custom domain, or path-based
• Domain map: brand vs tenant domain, PSL plan, custom domain flow
• Isolation plan: per-tenant Workers or shared-app with tenant scoping
• Routing plan: hostname lookup, dispatch/rewrite logic, fallback behavior
• Tenant context flow: how tenant identity propagates through Middleware/headers/DB
• Binding/config matrix: per-tenant capabilities and data access
• Limits-to-pricing map: CPU/memory/request/domain budgets per tier
• API surface plus ops UI scope

Pre-commit checklist

• [ ] Platform chosen with clear rationale documented
• [ ] Tenant workloads off the brand domain; PSL decision and timeline set
• [ ] Tenant identification strategy chosen; custom domain upgrade path defined
• [ ] Isolation model defined: per-tenant Workers (Cloudflare) or shared-app plus RLS (Vercel)
• [ ] Routing authoritative and tenant-blind; dispatch or Middleware handles all traffic
• [ ] Tenant context flows through Middleware/platform Worker only; no client-supplied identity trusted
• [ ] Custom domain onboarding defined with DNS target, verification, and cert provisioning
• [ ] Per-tenant static files (robots.txt, sitemap.xml, llms.txt) served dynamically
• [ ] Limits tied to billing; API parity with UI
• [ ] Limits snapshot refreshed from official docs and dated in planning notes

Related skills

• define-architecture: folder structure, module contracts, and middleware pipelines for the application itself.
• scaffold-nextjs: bootstrap the Next.js turborepo before applying these tenancy patterns.
• optimise-seo: per-tenant sitemaps, canonical URLs, and structured data once routing works.

Cloudflare platform primitives (Workers for Platforms)

Use this reference for Cloudflare-specific routing, isolation, and custom domain mechanics.

Routing pattern (hostname -> tenant -> dispatch)

• Hostname routing with a wildcard route (*/*) sends all SaaS-domain traffic to a dispatch Worker.
• Supports platform subdomains and customer vanity domains; avoid per-domain routes.
• Resolve hostname -> tenant id -> dispatch namespace -> tenant Worker; 404 if no mapping.
• Use a dedicated SaaS domain and set custom hostnames + fallback origin; point DNS (CNAME/proxied apex).

Custom domains (Cloudflare for SaaS)

• Supports subdomains on your zone and customer vanity domains.
• Validation required before cert issuance (http/txt/email via API).
• Standard mode routes custom hostnames to the SaaS fallback origin.

Isolation modes (dispatch namespaces)

• Untrusted mode (default) for customer code: no request.cf, no caches.default (isolated cache).
• Trusted mode enables request.cf and shared cache; use only when you control code or enforce isolation.

Sources

• https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/get-started/hostname-routing/
• https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/
• https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/
• https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/platform/worker-isolation/
• https://developers.cloudflare.com/api/operations/custom-hostnames-for-a-zone-create-custom-hostname
• https://x.com/burcs/status/2011542877420294233 (Brandon from Cloudflare, multi-tenant platform development walkthrough)

Platform limits and plan mapping

Use this reference to map platform limits directly to pricing tiers.

Freshness policy

• Treat values below as a snapshot as of 2026-02-05.
• Re-check each cited source before finalizing pricing, architecture, or launch decisions.
• If a source conflicts with this file, treat the source documentation as canonical and update this file.

Cloudflare Workers limits (per request/isolate)

• CPU time: 10 ms (Free), 30 s default / 5 min max (Paid).
• Memory: 128 MB per isolate.
• HTTP: no hard wall-clock limit; runtime ends on client disconnect; waitUntil() can extend briefly.
• D1: 10 GB per database; millions of databases per account; ~1,000 QPS per database.
• KV: eventually consistent (~60 s propagation); optimised for high-read/low-write.
• R2: 10 GB free storage; zero egress fees.
• Custom hostnames (Cloudflare for SaaS): 5,000 (Free/Pro/Business), unlimited (Enterprise).

Vercel limits

• Domains per project: 50 (Hobby), unlimited (Pro/Enterprise). Soft limit 100,000 (Pro), 1,000,000 (Enterprise).
• Edge Config size: 8 KB (Hobby), 64 KB (Pro), 512 KB (Enterprise). Write propagation up to 10 s.
• Middleware bundle size: 1 MB (Hobby), 2 MB (Pro), higher (Enterprise).
• Edge requests: 1 M (Hobby), 10 M (Pro). Overage $2/million.
• Bandwidth: 100 GB (Hobby), 1 TB (Pro). Overage $0.15/GB.
• CPU time: 4 CPU-hrs (Hobby), 16 CPU-hrs (Pro).
• ISR reads: 1 M (Hobby), 10 M (Pro).
• Deployments/day: 100 (Hobby), 6,000 (Pro).
• Domain API rate limits: 100 additions/hr, 50 verifications/hr, 100 removals/hr per team.
• Wildcard domains: supported on all plans; requires Vercel nameservers.
• Custom SSL certificates: Enterprise only.

Planning guidance

• Keep workloads short on both platforms; use queues/workflows for long jobs.
• Surface and enforce limits in plans and APIs/UI.
• Keep durable state in storage services (D1/Neon/R2/Vercel Blob), not in-memory.
• For Vercel: Edge Config is best for lightweight tenant metadata (<64 KB on Pro). Use a database for full tenant configuration when you exceed Edge Config size limits.
• For Cloudflare: D1 is single-threaded per database; shard or use database-per-tenant for high throughput.

Sources

• https://developers.cloudflare.com/workers/platform/limits/
• https://developers.cloudflare.com/d1/platform/limits/
• https://vercel.com/docs/multi-tenant/limits
• https://vercel.com/docs/edge-config/edge-config-limits
• https://vercel.com/pricing

Public Suffix List (PSL)

Use this reference when deciding whether to submit a tenant domain to the PSL.

What the PSL does

• Defines public suffixes where users can register names.
• Browsers use it to cap cookie scope (for example, no cookies on .co.uk).
• Shared cross-vendor list; registry rules vary and cannot be derived.

Why it matters for multi-tenant platforms

• Listing blocks cookies on the tenant suffix, isolating sibling subdomains.
• Isolation only; it does not confer trust or reputation.

Submission and validation (private domains)

• Private domains with untrusted subdomains can request PRIVATE inclusion.
• Submit a GitHub PR (owner/authorized rep); PRs are preferred and validated.
• Prefer DNS proof: _psl.<suffix> TXT with a PR link (RFC8553).
• Include a brief rationale (UGC/third-party subdomains); expect multi-week review.
• PSL is not a security or trust signal and must not bypass tracking protections.

Sources

• https://publicsuffix.org/learn/index.html
• https://publicsuffix.org/submit/
• https://github.com/publicsuffix/list/wiki/guidelines
• https://wiki.mozilla.org/Public_Suffix_List

Vercel domain management (custom domains + SSL)

Use this reference for programmatic domain lifecycle, SSL provisioning, verification, preview URLs, and troubleshooting.

Domain onboarding flow

• Tenant provides their domain in your UI or API.
• Call projectsAddProjectDomain via @vercel/sdk to register the domain on your Vercel project.
• Instruct tenant to set CNAME to cname.vercel-dns.com or A record to 76.76.21.21.
• Poll projectsVerifyProjectDomain or use webhooks for verification status.
• Store verified domain mapping in Edge Config and DB; begin serving tenant traffic on that hostname.

Wildcard domains

• Wildcard (*.acme.com) requires Vercel nameservers: ns1.vercel-dns.com, ns2.vercel-dns.com.
• Vercel issues individual SSL certificates per subdomain on the fly via DNS-01 challenge.
• Add the apex domain first, then add the wildcard domain in project settings.
• Supported on all plans; no per-subdomain configuration needed.

Custom domains (Vercel SDK)

• Use @vercel/sdk for programmatic CRUD: projectsAddProjectDomain, projectsGetProjectDomain, projectsVerifyProjectDomain, projectsRemoveProjectDomain.
• domainsDeleteDomain removes a domain from the account entirely (separate from project removal).
• Handle API errors: 409 (domain in use by another project), 403 (verification required), 429 (rate limited).
• Rate limits: 100 additions/hr, 50 verifications/hr, 100 removals/hr per team.
• Batch domain operations where possible to stay within rate limits.

Domain verification

• TXT record required when the domain is already in use on another Vercel project.
• Verification record: _vercel.domain.com TXT with the value provided by the API response.
• Poll verification status via SDK; most verifications complete within minutes once DNS propagates.
• Re-verify if DNS changes after initial verification or if ownership is transferred.

SSL certificates

• Automatic Let's Encrypt certificates via ACME protocol; no manual configuration.
• Standard/custom domains: HTTP-01 challenge (Vercel responds at /.well-known/acme-challenge/*).
• Wildcard domains: DNS-01 challenge (requires Vercel nameservers).
• Automatic renewal 14-30 days before expiration.
• CAA records must allow Let's Encrypt; do not block the ACME challenge path with redirects or middleware.
• Enterprise only: upload custom SSL certificates for compliance requirements.

Redirects (www/apex)

• Add both domain.com and www.domain.com to the project.
• Configure redirect from www to apex (or vice versa) via the SDK redirect parameter.
• Set canonical URL in <head> if serving the same tenant on both a subdomain and custom domain.
• Use 301 redirects for permanent domain consolidation; 307 for temporary.

Preview URLs

• Pattern: tenant---preview-deployment.vercel.app. Vercel routes to the deployment; your code receives the full hostname.
• Requires a custom preview deployment suffix; does not work with default .vercel.app.
• Middleware must parse the triple-dash separator: split on --- to extract tenant slug from preview hostname.
• Total hostname length must not exceed 253 characters (DNS limit); keep branch names concise.
• Enterprise only for full multi-tenant preview URL support.

Troubleshooting

• DNS not propagating: Wait up to 48 hours; verify with dig or whatsmydns.net. Most resolve in minutes.
• Verification failure: Confirm TXT record value matches exactly; check for CNAME flattening by DNS provider; ensure no trailing dots.
• Wildcard not working: Confirm nameservers point to Vercel; wildcard requires DNS-01 challenge which only works with Vercel nameservers.
• SSL not issuing: Ensure CAA records allow letsencrypt.org; check that middleware or redirects do not block /.well-known/acme-challenge/*.
• Infinite redirects: Check for conflicting redirect rules between Vercel config, middleware, and DNS provider (e.g. Cloudflare proxying).
• SEO duplicate content: Set canonical URLs; redirect non-canonical domain to canonical; use consistent domain in sitemaps.

Sources

• https://vercel.com/docs/multi-tenant/domain-management
• https://vercel.com/docs/domains/working-with-ssl
• https://vercel.com/docs/multi-tenant/preview-urls
• https://vercel.com/docs/multi-tenant/limits
• https://github.com/vercel/sdk
• https://vercel.com/docs/multi-tenant/api-reference

Vercel platform primitives (Next.js multi-tenancy)

Use this reference for routing, tenant resolution, data isolation, content patterns, and local development on Vercel.

Routing pattern (Middleware hostname rewrite)

• Middleware runs on Vercel's Edge Runtime; extracts hostname from request.headers.get('host').
• Rewrite URL to a dynamic catch-all segment: /domains/${hostname}${pathname}.
• Matcher excludes api, _next, and static files: /((?!api|_next|[\w-]+\.\w+).*).
• Handle three environments: *.localhost (dev), tenant---branch.vercel.app (preview), *.yourdomain.com (production).
• 404 when no tenant mapping exists; never fall through to default content.

Tenant identification (Vercel mechanics)

Strategy choice lives in the SKILL.md workflow; this is the per-strategy extraction logic.

• Subdomain-based: extract tenant from hostname.split('.')[0]. Requires wildcard DNS on the tenant domain.
• Custom domain: map the full hostname to a tenant via Edge Config or DB lookup. Tenant sets a CNAME/A record.
• Path-based: extract tenant from the first path segment. No per-tenant DNS/SSL.

App Router folder structure

• app/(main)/: brand/marketing pages on the apex domain.
• app/domains/[domain]/: tenant-specific routes; Middleware rewrites all tenant traffic here.
• app/domains/[domain]/layout.tsx: tenant layout with branding (logo, fonts, theme from DB).
• app/domains/[domain]/[slug]/page.tsx: tenant content pages.
• generateMetadata per tenant for title, description, favicon, canonical URL, and OG images.

Tenant context passing

• Middleware resolves tenant and sets x-tenant-id, x-tenant-slug, x-tenant-plan on the forwarded request headers (for rewrite/next), not on final response headers.
• Server Components read tenant from headers(); no prop drilling through layouts.
• API routes read tenant from request.headers.get('x-tenant-id').
• Middleware is the single authority for tenant identity; never trust client-supplied values.

Edge Config (tenant lookup)

• Sub-millisecond reads via push-based CDN replication; ideal for domain-to-tenant mappings.
• Store lightweight mappings: tenant_${hostname} -> { id, slug, plan }.
• Use @vercel/edge-config get() in Middleware for tenant resolution.
• Write propagation: up to 10 seconds globally.
• Size limits: 8 KB (Hobby), 64 KB (Pro), 512 KB (Enterprise). For large tenant sets, store only the mapping in Edge Config and fetch full config from DB.

Custom subpaths

• Catch-all route [...slug] handles tenant content under a path prefix (e.g. yourdomain.com/sites/tenant-slug/).
• Middleware rewrites subdomain traffic to path-based routes: tenant.yourdomain.com/guide -> /sites/tenant-slug/guide.
• Set assetPrefix in next.config.js to avoid static asset path conflicts across tenants.
• Subpath routing avoids DNS/SSL complexity per tenant but limits custom branding.

Per-tenant static files

• robots.txt, sitemap.xml, llms.txt must vary by tenant; do not use /public.
• Use route handlers at app/domains/[domain]/robots.txt/route.ts, app/domains/[domain]/sitemap.xml/route.ts, and app/domains/[domain]/llms.txt/route.ts to read tenant from params and return tenant-specific content.
• Set Content-Type headers explicitly (text/plain, application/xml).
• Cache with CDN-Cache-Control: s-maxage=3600; invalidate when tenant content changes.

Database patterns

• Shared schema + `tenant_id` (simplest): Include tenant_id on every tenant-aware table. Use with Neon (Vercel Postgres).
• Shared schema + RLS (defence-in-depth): Row-Level Security policy enforces tenant_id = current_setting('app.current_tenant_id'). Prevents leaks even if a query omits the WHERE clause.
• Database-per-tenant (strongest isolation): One Neon project per tenant. Inactive projects scale to zero. Manage via Neon API.
• Use Drizzle ORM or Prisma for schema and migration management.

Caching (ISR + revalidation)

• Use unstable_cache with tags for per-tenant content caching.
• Invalidate with revalidateTag('tenant-123-posts') on content changes.
• ISR serves stale content from the edge while revalidating in the background.
• Dynamic metadata (generateMetadata) produces per-tenant OG images, favicons, and sitemaps.

Local development

• Add *.localhost entries to /etc/hosts or rely on browser auto-resolution of *.localhost.
• Middleware hostname matching must handle hostname.includes('localhost') for local subdomains.
• No HTTPS required locally; access via http://tenant1.localhost:3000.

Sources

• https://vercel.com/docs/multi-tenant
• https://vercel.com/templates/next.js/platforms-starter-kit
• https://github.com/vercel/platforms
• https://vercel.com/docs/edge-config
• https://vercel.com/docs/multi-tenant/custom-subpaths
• https://vercel.com/docs/multi-tenant/static-files
• https://neon.com/docs/guides/multitenancy