domma-cms 1.6.60 → 1.7.1

package/docs/MultiTenant.md

@@ -0,0 +1,176 @@
+# Theoretical: Multi-Tenancy in Domma CMS
+
+## Context
+
+Domma CMS is a file-based CMS (Fastify 5 ESM backend, Domma SPA admin, SSR public site). Every service currently assumes
+a single tenant - config, content, users, collections, and plugins all resolve from fixed module-level directory
+constants. The user asked whether multi-tenancy is **possible**, not to implement it.
+
+## Answer: Yes, But It's a Spectrum
+
+There are three viable approaches, each with a different trade-off between isolation, complexity, and operational
+overhead.
+
+---
+
+## Approach 1: Process-Per-Tenant (Simplest)
+
+Run a separate Domma CMS instance per tenant, each with its own `content/`, `config/`, and port.
+
+| Aspect               | Detail                                             |
+|----------------------|----------------------------------------------------|
+| **Isolation**        | Complete - separate processes, separate file trees |
+| **Code changes**     | Zero                                               |
+| **Operational cost** | High - N processes, N ports, reverse proxy routing |
+| **Tenant limit**     | ~50-100 before operational pain                    |
+| **Best for**         | Agency hosting a handful of client sites           |
+
+A reverse proxy (nginx/Caddy) maps `tenant1.example.com` → `:4096`, `tenant2.example.com` → `:4097`, etc. Each instance
+is a vanilla Domma CMS install.
+
+---
+
+## Approach 2: Single Process, Directory-Scoped Tenancy (Medium)
+
+One Fastify instance, tenant resolved from hostname/subdomain, all services parameterised by tenant ID.
+
+### What Changes
+
+**A. Tenant detection hook** (new - `server/middleware/tenant.js`)
+
+- Fastify `onRequest` hook derives `request.tenant` from subdomain or `X-Tenant` header
+- All downstream services receive tenant context
+
+**B. Config** (`server/config.js`)
+
+- `getConfig(name)` → `getConfig(name, tenantId)` resolving to `config/{tenantId}/{name}.json`
+- Startup singleton `config` (server/auth/content) stays global (shared infrastructure config)
+- Admin-editable config (site/navigation/plugins/presets) becomes per-tenant
+
+**C. Content & Collections** (`server/services/content.js`, `collections.js`)
+
+- Module-level constants (`PAGES_DIR`, `MEDIA_DIR`, `COLLECTIONS_DIR`) become functions: `getPagesDir(tenantId)` →
+  `content/{tenantId}/pages/`
+- Every exported function gains a tenant parameter
+- URL-to-file mapping scoped: `/about` → `content/{tenantId}/pages/about.md`
+
+**D. Users & Auth** (`server/services/users.js`, `server/middleware/auth.js`)
+
+- Users dir: `content/{tenantId}/users/`
+- JWT tokens include `tenantId` claim - validated on every request
+- Role caches keyed by `tenantId:roleName`
+
+**E. Storage Adapters** (`server/services/adapterRegistry.js`)
+
+- Cache key changes from `slug` to `{tenantId}:{slug}`
+- MongoDB: per-tenant database or `{tenantId}_` collection prefix
+- FileAdapter: tenant-scoped base directory
+
+**F. Renderer** (`server/services/renderer.js`)
+
+- Already reads config fresh per render - making `getConfig()` tenant-aware cascades naturally
+- Template cache keyed by `tenantId`
+- Custom CSS path: `content/{tenantId}/custom.css`
+
+**G. Plugins** (`server/services/plugins.js`, `server/services/hooks.js`) - **HARDEST PART**
+
+- Plugin code stays shared (global `plugins/` directory)
+- Enabled/disabled state + settings become per-tenant (via scoped `config/{tenantId}/plugins.json`)
+- Hook/shortcode/transform registries need namespacing - currently global `Map`s and a single `EventEmitter`
+- Plugin-registered Fastify routes need tenant middleware guards
+
+### Effort Estimate by Area
+
+| Area                  | Effort      | Why                                                  |
+|-----------------------|-------------|------------------------------------------------------|
+| Tenant detection hook | Low         | New file, ~30 lines                                  |
+| Config scoping        | Medium      | `getConfig`/`saveConfig` + directory structure       |
+| Content service       | Medium      | ~15 functions to parameterise                        |
+| Collections           | Medium      | Same pattern as content                              |
+| Users & auth          | Medium-High | JWT claims, role cache refactor                      |
+| Adapters              | Low-Medium  | Cache key change, already supports named connections |
+| Renderer              | Low         | Already re-reads config per render                   |
+| Plugins/hooks         | **High**    | Global registries, no teardown, route scoping        |
+| Admin SPA             | Medium      | API calls need tenant context (header or URL prefix) |
+| **Total**             | **Large**   | ~2-3 weeks full-time for an experienced developer    |
+
+### Directory Structure
+
+```
+config/
+  server.json              # shared infrastructure
+  auth.json                # shared infrastructure
+  content.json             # shared infrastructure
+  tenants.json             # NEW - tenant registry (id, hostname, plan, etc.)
+  {tenantId}/
+    site.json
+    navigation.json
+    plugins.json
+    presets.json
+
+content/
+  {tenantId}/
+    pages/
+    media/
+    users/
+    collections/
+    custom.css
+```
+
+---
+
+## Approach 3: MongoDB-Native Multi-Tenancy (Pro Only)
+
+For Pro users already on MongoDB - tenancy lives entirely in the database layer.
+
+- Each tenant gets a separate MongoDB database (strongest isolation) or a `tenantId` field on every document (weaker but
+  simpler)
+- `connectionManager.js` already supports named connections - extend to per-tenant connections
+- File-based content (pages, media) still needs directory scoping OR moves entirely to MongoDB (GridFS for media,
+  documents for pages)
+- Most natural extension of the existing adapter pattern
+
+---
+
+## The Five Hardest Problems
+
+1. **Plugin hook registries are global singletons.** The `EventEmitter`, `_shortcodes` Map, `_sanitizeExtensions`, and
+   `_transforms` Map in `hooks.js` have no tenant dimension. Options: (a) namespace keys as `{tenantId}:{hookName}`, (b)
+   per-tenant EventEmitter instances, (c) accept that plugins are global and only settings are per-tenant.
+
+2. **Module-level constants everywhere.** `PAGES_DIR`, `MEDIA_DIR`, `USERS_DIR`, `COLLECTIONS_DIR` are all `const` at
+   module scope. Every function using them would need refactoring to accept or derive tenant context. This is the bulk
+   of the mechanical work.
+
+3. **No request context threading.** There is no `AsyncLocalStorage` or similar mechanism to pass tenant context through
+   the call stack without explicitly threading it through every function parameter. Adding `AsyncLocalStorage` would be
+   the cleanest approach but touches every service boundary.
+
+4. **Admin SPA is a single build.** The admin panel (`admin/`) is served as static files and makes API calls without
+   tenant context. It would need to either: (a) send a tenant header with every API call, (b) be served from a
+   tenant-scoped URL, or (c) derive tenant from the page hostname.
+
+5. **Static asset isolation.** `public/css/site.css`, `public/js/site.js`, and theme assets are shared. Per-tenant
+   CSS/JS customisation would need a serving layer that overlays tenant-specific files on the shared base.
+
+---
+
+## Pragmatic Recommendation
+
+If multi-tenancy is a real future goal:
+
+1. **Start with Approach 1** (process-per-tenant) for immediate needs - zero code changes
+2. **Introduce `AsyncLocalStorage`** for tenant context propagation as a foundation
+3. **Scope config first** (`getConfig` + `saveConfig`) - lowest risk, highest leverage since the renderer already
+   re-reads config per render
+4. **Scope content second** - parameterise path helpers in content.js
+5. **Leave plugins global** with per-tenant settings - full plugin isolation is disproportionately expensive
+6. **MongoDB-native tenancy** for Pro users as the long-term path - the adapter pattern already supports this direction
+
+## Verification (If Implemented)
+
+1. Two tenants configured with different `site.json` (title, theme) serve distinct homepages from the same process
+2. Tenant A cannot access Tenant B's content, users, or media (path traversal guards)
+3. JWT from Tenant A is rejected on Tenant B's API routes
+4. Admin panel for each tenant shows only that tenant's pages/collections
+5. Shared plugins work for both tenants with independent settings