Multi-Tenant SaaS Architecture on Cloudflare Workers: Complete Guide

Why Cloudflare Workers for Multi-Tenant SaaS?

Cloudflare Workers provides ideal characteristics for multi-tenant applications:

Tenant Isolation Strategies

Strategy 1: Row-Level Isolation (Recommended for SaaS)

All tenants use the same database and tables. Data is isolated by a tenant_id column.

Strategy 2: Schema-Level Isolation

Each tenant gets their own database schema or separate database instance.

Recommended Architecture

Implementation Steps

// From subdomain
const tenant = new URL(request.url).hostname
  .split('.')[0]; // tenant.example.com → "tenant"

// From header
const tenant = request.headers.get('X-Tenant-ID');

// From path
const tenant = new URL(request.url)
  .pathname.split('/')[1]; // /tenant123/data → "tenant123"

// Get per-tenant Durable Object
const durableObject = env.TENANT_STATE.get(
  env.TENANT_STATE.idFromName(tenant)
);

// Store session data
await durableObject.fetch(new Request('http://tenant/session', {
  method: 'POST',
  body: JSON.stringify(sessionData)
}));

// Fetch user data for tenant
const user = await db
  .select('*')
  .from('users')
  .where('tenant_id', '=', tenant)
  .where('id', '=', userId)
  .single();

// Check rate limit for tenant
const rateLimitKey = `${tenant}:${Math.floor(Date.now() / 60000)}`;
const count = await durableObject.incrementCounter(rateLimitKey);

if (count > REQUESTS_PER_MINUTE) {
  return new Response('Rate limited', { status: 429 });
}

Complete Implementation Example

Here's a production-ready multi-tenant SaaS API:

import { Clodo } from '@clodo/framework';

interface Env {
  DB: D1Database;
  TENANT_STATE: DurableObjectNamespace;
}

const app = new Clodo();

// Middleware: Extract and validate tenant
app.use(async (req, next) => {
  // Extract tenant from subdomain
  const url = new URL(req.url);
  const tenant = url.hostname.split('.')[0];
  
  if (!tenant || tenant === 'www') {
    return new Response('Invalid tenant', { status: 400 });
  }
  
  // Attach to request context
  req.tenant = tenant;
  req.durableObject = req.env.TENANT_STATE.get(
    req.env.TENANT_STATE.idFromName(tenant)
  );
  
  return next();
});

// GET /api/users - List tenant's users
app.get('/api/users', async (req) => {
  const users = await req.db
    .select('id', 'name', 'email', 'created_at')
    .from('users')
    .where('tenant_id', '=', req.tenant)
    .all();
  
  return { users };
});

// POST /api/users - Create user
app.post('/api/users', async (req) => {
  const { name, email } = await req.json();
  
  // Validate
  if (!name || !email) {
    return { error: 'Name and email required' }, { status: 400 };
  }
  
  // Create user with tenant isolation
  const user = await req.db
    .insert('users')
    .values({
      tenant_id: req.tenant,
      name,
      email,
      created_at: new Date()
    })
    .returning('*');
  
  return { user }, { status: 201 };
});

// GET /api/users/:id - Get specific user
app.get('/api/users/:id', async (req) => {
  const { id } = req.params;
  
  const user = await req.db
    .select('*')
    .from('users')
    .where('tenant_id', '=', req.tenant)
    .where('id', '=', id)
    .single();
  
  if (!user) {
    return { error: 'User not found' }, { status: 404 };
  }
  
  return { user };
});

// GET /api/stats - Per-tenant analytics
app.get('/api/stats', async (req) => {
  const stats = await req.db
    .query.raw(`
      SELECT 
        COUNT(*) as total_users,
        COUNT(CASE WHEN created_at > datetime('now', '-30 days') 
              THEN 1 END) as new_users_30d
      FROM users
      WHERE tenant_id = ?
    `, [req.tenant]);
  
  return { stats: stats[0] };
});

export default app;

Request Routing Methods

Database Schema Design

Always include tenant_id on every table:

-- Users table with tenant isolation
CREATE TABLE users (
  id TEXT PRIMARY KEY,
  tenant_id TEXT NOT NULL,
  email TEXT NOT NULL,
  name TEXT NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  UNIQUE(tenant_id, email),
  FOREIGN KEY(tenant_id) REFERENCES tenants(id)
);

-- Create index for fast tenant queries
CREATE INDEX idx_users_tenant_id ON users(tenant_id);

-- Data table with tenant isolation
CREATE TABLE data (
  id TEXT PRIMARY KEY,
  tenant_id TEXT NOT NULL,
  user_id TEXT NOT NULL,
  content TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY(tenant_id) REFERENCES tenants(id),
  FOREIGN KEY(user_id) REFERENCES users(id)
);

CREATE INDEX idx_data_tenant_id ON data(tenant_id);

-- Tenants table (system-level)
CREATE TABLE tenants (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  subscription_tier TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Cost Comparison: Workers vs Lambda

Plus benefits: 0ms cold starts, global distribution, Durable Objects for free per-tenant state.

Production Considerations

Security

• ✅ Always filter by tenant_id in queries
• ✅ Validate tenant ownership before updates/deletes
• ✅ Use database foreign keys to enforce isolation
• ✅ Audit all per-tenant data access
• ❌ Never trust client-provided tenant_id (always use authenticated identity)

Monitoring & Observability

• Track per-tenant request counts (alert on abuse)
• Monitor per-tenant query latency
• Log data access for audit trails
• Set up cost alerts per tenant

Scaling Considerations

• At 100K tenants: Consider schema-level isolation
• At 1B+ requests/day: Shard Durable Objects by tenant
• Implement data archival after 1-2 years
• Plan for tenant-specific customizations early

Next Steps

• Start building: Get started with Clodo
• Compare frameworks: Clodo vs Hono vs Worktop
• Check costs: See Lambda cost savings
• See examples: Production examples
• Learn more: Full documentation

Building multi-tenant SaaS? This guide covers the fundamentals. For enterprise requirements (HIPAA, SOC2), schema-level isolation is recommended. Reach out to the Clodo team for architecture reviews.