Building a multi-tenant CMS on Cloudflare Workers requires careful architectural decisions around data isolation, authentication, and caching strategies. This guide covers production-ready patterns for SaaS CMS platforms that need to scale globally while maintaining strict tenant boundaries.
Core Architecture Components
A robust multi-tenant CMS on Cloudflare Workers consists of several key components working together:
- Worker Runtime: Request routing and business logic
- D1 Database: Tenant data storage with isolation patterns
- KV Storage: Edge caching and session management
- R2 Storage: Media assets and file uploads
- Durable Objects: Real-time features and coordination
The edge-native approach eliminates traditional database scaling bottlenecks while providing sub-100ms response times globally.
Database Design for Tenant Isolation
Data isolation is critical for multi-tenant architectures. We implement a hybrid approach using row-level security combined with database sharding patterns.
Schema Design with Tenant Boundaries
Every table includes a tenant_id column as part of the primary key structure:
CREATE TABLE content (
id TEXT PRIMARY KEY,
tenant_id TEXT NOT NULL,
title TEXT NOT NULL,
body TEXT,
status TEXT DEFAULT 'draft',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_content_tenant ON content(tenant_id, status, created_at);
CREATE TABLE users (
id TEXT PRIMARY KEY,
tenant_id TEXT NOT NULL,
email TEXT NOT NULL,
role TEXT DEFAULT 'editor',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
CREATE UNIQUE INDEX idx_users_email_tenant ON users(email, tenant_id);This design ensures queries are automatically scoped to tenant boundaries while maintaining performance through proper indexing.
Query Patterns for Data Isolation
All database operations must include tenant context. Implement a query builder that automatically injects tenant filters:
class TenantDB {
constructor(db, tenantId) {
this.db = db;
this.tenantId = tenantId;
}
async getContent(status = null) {
let query = 'SELECT * FROM content WHERE tenant_id = ?';
let params = [this.tenantId];
if (status) {
query += ' AND status = ?';
params.push(status);
}
return this.db.prepare(query).bind(...params).all();
}
async createContent(data) {
return this.db.prepare(`
INSERT INTO content (id, tenant_id, title, body, status)
VALUES (?, ?, ?, ?, ?)
`).bind(
crypto.randomUUID(),
this.tenantId,
data.title,
data.body,
data.status || 'draft'
).run();
}
}Authentication and Authorization Patterns
Multi-tenant authentication requires careful session management and role-based access control across tenant boundaries.
JWT-Based Tenant Authentication
Use JWT tokens that embed tenant context and user permissions:
// JWT payload structure
const tokenPayload = {
sub: userId,
tenant_id: tenantId,
role: userRole,
permissions: ['content:read', 'content:write'],
exp: Math.floor(Date.now() / 1000) + (24 * 60 * 60)
};
// Middleware for token validation
async function authenticateRequest(request, env) {
const authHeader = request.headers.get('Authorization');
if (!authHeader?.startsWith('Bearer ')) {
return { error: 'Missing authentication' };
}
try {
const token = authHeader.split(' ')[1];
const payload = await verifyJWT(token, env.JWT_SECRET);
return {
userId: payload.sub,
tenantId: payload.tenant_id,
role: payload.role,
permissions: payload.permissions
};
} catch (error) {
return { error: 'Invalid token' };
}
}Role-Based Access Control
Implement granular permissions that work within tenant boundaries:
class TenantAuthorizer {
constructor(user) {
this.user = user;
}
canRead(resource, resourceTenantId = null) {
if (resourceTenantId && resourceTenantId !== this.user.tenantId) {
return false;
}
return this.user.permissions.includes(`${resource}:read`);
}
canWrite(resource, resourceTenantId = null) {
if (resourceTenantId && resourceTenantId !== this.user.tenantId) {
return false;
}
return this.user.permissions.includes(`${resource}:write`);
}
canAdmin() {
return this.user.role === 'admin';
}
}Per-Tenant Edge Caching Strategy
Effective caching in a multi-tenant system requires namespace isolation and cache invalidation strategies that don't leak between tenants.
KV-Based Tenant Caching
Structure cache keys with tenant prefixes to ensure complete isolation:
class TenantCache {
constructor(kv, tenantId) {
this.kv = kv;
this.tenantId = tenantId;
}
getCacheKey(resource, identifier) {
return `tenant:${this.tenantId}:${resource}:${identifier}`;
}
async get(resource, identifier) {
const key = this.getCacheKey(resource, identifier);
const cached = await this.kv.get(key, { type: 'json' });
return cached;
}
async set(resource, identifier, data, ttl = 3600) {
const key = this.getCacheKey(resource, identifier);
return this.kv.put(key, JSON.stringify(data), {
expirationTtl: ttl
});
}
async invalidate(resource, identifier = '*') {
if (identifier === '*') {
// Bulk invalidation requires listing and deleting
const prefix = `tenant:${this.tenantId}:${resource}:`;
const { keys } = await this.kv.list({ prefix });
await Promise.all(
keys.map(({ name }) => this.kv.delete(name))
);
} else {
const key = this.getCacheKey(resource, identifier);
await this.kv.delete(key);
}
}
}Content Delivery and Cache Headers
Implement smart cache headers that respect tenant boundaries:
async function handleContentRequest(request, env) {
const auth = await authenticateRequest(request, env);
if (auth.error) {
return new Response('Unauthorized', { status: 401 });
}
const cache = new TenantCache(env.CACHE_KV, auth.tenantId);
const contentId = new URL(request.url).pathname.split('/').pop();
// Try cache first
let content = await cache.get('content', contentId);
if (!content) {
// Fetch from database
const db = new TenantDB(env.DB, auth.tenantId);
content = await db.getContentById(contentId);
if (content) {
// Cache for 1 hour
await cache.set('content', contentId, content, 3600);
}
}
if (!content) {
return new Response('Not found', { status: 404 });
}
return new Response(JSON.stringify(content), {
headers: {
'Content-Type': 'application/json',
'Cache-Control': 'private, max-age=300',
'Vary': 'Authorization'
}
});
}Worker Request Router Implementation
A production multi-tenant CMS needs sophisticated routing that handles tenant context, authentication, and API versioning:
export default {
async fetch(request, env, ctx) {
const router = new TenantRouter();
// Public routes (no auth required)
router.get('/api/health', handleHealth);
router.post('/api/auth/login', handleLogin);
// Tenant-scoped routes (auth required)
router.get('/api/content', authenticatedHandler(handleListContent));
router.post('/api/content', authenticatedHandler(handleCreateContent));
router.get('/api/content/:id', authenticatedHandler(handleGetContent));
router.put('/api/content/:id', authenticatedHandler(handleUpdateContent));
router.delete('/api/content/:id', authenticatedHandler(handleDeleteContent));
// Admin routes (admin role required)
router.get('/api/admin/users', adminHandler(handleListUsers));
router.post('/api/admin/users', adminHandler(handleCreateUser));
return router.handle(request, env);
}
};
function authenticatedHandler(handler) {
return async (request, env, params) => {
const auth = await authenticateRequest(request, env);
if (auth.error) {
return new Response('Unauthorized', { status: 401 });
}
const context = {
user: auth,
db: new TenantDB(env.DB, auth.tenantId),
cache: new TenantCache(env.CACHE_KV, auth.tenantId),
authorizer: new TenantAuthorizer(auth)
};
return handler(request, env, params, context);
};
}Performance Optimization Strategies
Multi-tenant systems face unique performance challenges. Key optimization areas include connection pooling, query optimization, and cache warming.
Database Connection Management
D1 connections should be reused within the worker instance lifecycle:
class ConnectionManager {
constructor() {
this.connections = new Map();
}
getConnection(env, tenantId) {
const key = `db_${tenantId}`;
if (!this.connections.has(key)) {
this.connections.set(key, new TenantDB(env.DB, tenantId));
}
return this.connections.get(key);
}
}
// Global instance for connection reuse
const connectionManager = new ConnectionManager();Batch Operations and Query Optimization
Implement batch operations to reduce database round trips:
async function batchCreateContent(items, context) {
const statements = items.map(item =>
context.db.db.prepare(`
INSERT INTO content (id, tenant_id, title, body, status)
VALUES (?, ?, ?, ?, ?)
`).bind(
crypto.randomUUID(),
context.user.tenantId,
item.title,
item.body,
item.status || 'draft'
)
);
return context.db.db.batch(statements);
}Monitoring and Observability
Multi-tenant systems require careful monitoring to detect tenant-specific issues and resource consumption patterns.
Key metrics to track include per-tenant request volume, database query performance, cache hit rates, and error rates. Implement structured logging that includes tenant context:
function logTenantEvent(level, event, tenantId, data = {}) {
console.log(JSON.stringify({
timestamp: new Date().toISOString(),
level,
event,
tenant_id: tenantId,
...data
}));
}Security Considerations
Multi-tenant architectures introduce specific security vectors that require attention. Always validate tenant boundaries in authorization logic, implement rate limiting per tenant, and ensure cache isolation prevents data leakage.
Regular security audits should verify that no queries can access data outside the authenticated tenant's scope, and that cache keys properly namespace tenant data.
This architecture provides a foundation for building scalable SaaS CMS platforms that leverage Cloudflare's edge infrastructure while maintaining strict tenant isolation and optimal performance characteristics.