Multi-tenant SaaS — closure-captured tenantId per Builder

Walkthrough

1. 1

   Closure-capture `tenantId` in the Builder constructor — the engine never sees it

   The engine takes onBrowse and saveUrl as constructor options. Both are CALLBACKS / strings that the engine invokes when a browse / save happens. The host writes the closure; the closure captures tenantId from the surrounding scope. Per Builder instance, the tenantId is BAKED in for the lifetime of the editor.

   Two editors with two tenantIds = two closures = two different upload/save URLs. The engine bundle (dist/builder.js, dist/builder.css) is loaded ONCE; the tenant-aware behaviour lives entirely in the host's constructor calls. Multi-tenant is a HOST concern, not an engine concern.

   This is what the SPEC means by "Builder.js core stays tenant-unaware." There is no tenantId field on the Builder instance, no constructor option called tenant, no tenant:active event on the bus. The engine's entire surface is tenant-naive.

   JavaScript Copy

   function buildEditorFor(tenantId) {
     // tenantId is closure-captured; the engine never sees it.
     return new Builder({
       mainContainer:     '#' + tenantId + '-canvas',
       widgetsContainer:  '#' + tenantId + '-widgets',
       settingsContainer: '#' + tenantId + '-settings',
   
       // Asset browse — host opens its picker. Closure captures tenantId
       // and attaches it via extraFields so the upload POST carries
       // tenant context server-side.
       onBrowse: function (handleUrl) {
         DemoFileBrowser.pickFile(
           function (r) { handleUrl(r.url); },
           {
             endpoint:    '/backend/asset-upload.php',
             extraFields: { tenantId: tenantId },   // ← closure-captured
           }
         );
       },
   
       // Save URL — closure-captured tenantId in the query string.
       // /backend/save.php reads tenantId server-side + routes to
       // TenantRegistry::saveDirFor(tenantId).
       saveUrl: '/backend/save.php?tenantId=' + encodeURIComponent(tenantId),
     });
   }
   
   const editorA = buildEditorFor('acme-corp');
   const editorB = buildEditorFor('globex-llc');
   
   // editorA.saveUrl  → '/backend/save.php?tenantId=acme-corp'
   // editorB.saveUrl  → '/backend/save.php?tenantId=globex-llc'
   // editorA's onBrowse will POST tenantId=acme-corp; editorB → globex-llc.
   // One engine bundle. Two complete tenant isolations.

2. 2

   Backend registry — `_lib/TenantRegistry.php` answers "what is this tenant allowed to access?"

   Three concerns, three methods. The class doesn't authenticate (that's _lib/Auth.php's job in the demo backend); it assumes a validated tenant ID and answers what they're ALLOWED to access:

   • listForTenant($tenantId) — returns the filtered ThemeManifest[] this tenant can use. The demo ships three fixtures: Acme + Stark see all 63 themes; Globex sees only the 5 basic-email samples.
   • assetRootFor($tenantId) — returns the absolute filesystem path / S3 prefix where this tenant's uploads land. /backend/asset-upload.php reads tenantId from POST + uses this to build the destination key.
   • saveDirFor($tenantId) — returns the directory key for this tenant's saved pages. /backend/save.php reads tenantId from query string + writes under the saves root + this dir.

   Production buyers swap the hardcoded TENANT_FIXTURES for a database query (SELECT theme_dir FROM tenant_themes WHERE tenant_id = ?), an LDAP lookup, or a feature-flag service call. Cache layer (Redis with 5-minute TTL) and telemetry (`error_log("tenant.theme_list tenant=$tid count=$n")`) are typical extensions.

   PHP Copy

   // Single-file class; demo/backend/_lib/TenantRegistry.php.
   final class TenantRegistry
   {
       private const TENANT_FIXTURES = [
           'acme-corp' => [
               'displayName' => 'Acme Corp',
               'themeDirs'   => ['*'],   // all themes
               'sampleAllowList' => null,
               'assetRoot'   => '/tmp/builderjs-demo/tenants/acme-corp',
               'saveDir'     => 'acme-corp',
           ],
           'globex-llc' => [
               'displayName' => 'Globex LLC',
               'themeDirs'   => ['default'],
               'sampleAllowList' => [
                   'master/sample/email/Blank',
                   'master/sample/email/Minimal',
                   'master/sample/email/SimpleText',
                   'master/sample/email/Gallery',
                   'master/sample/email/SellProducts',
               ],
               'assetRoot'   => '/tmp/builderjs-demo/tenants/globex-llc',
               'saveDir'     => 'globex-llc',
           ],
           // ...
       ];
   
       public function listForTenant(string $tenantId): array { /* filter */ }
       public function assetRootFor(string $tenantId): string { /* lookup */ }
       public function saveDirFor(string $tenantId): string  { /* lookup */ }
   }

3. 3

   Why the engine STAYS tenant-naive — and when to reconsider

   Tempting alternative: bake tenantId into the Builder constructor + read this.tenantId from internal call sites. We rejected it for three reasons documented in multi-tenant/SPEC.md §4:

   1. Engine ownership creep. Tenant identity is a host concern. The engine doesn't know what a tenant IS or how to authenticate one. Pushing tenant-awareness into the engine means the engine takes positions on tenant SCOPE / LIFECYCLE / AUTH — none of which it has business answering.
   2. Bundle size for tenant-naive apps. Most BuilderJS deployments are single-tenant. Adding tenant hooks to the engine means even tenant-naive apps ship the hook code. Closure capture in HOST code keeps the engine bundle the same regardless.
   3. Closure capture works. The pattern in Step 1 gives complete isolation — events / pinSet / recent-colors / active-controls are all per-Builder-instance (W6.A.A.4 multi-instance refactor proved this). Adding engine-side hooks would solve a problem we don't have.

   When to reconsider: if a real SaaS use-case surfaces that closure capture CAN'T solve (e.g., a tenant-scoped engine lifecycle hook that needs to be observable across instances + cleaned up on tenant archive), file a SPEC.md amendment with a worked example showing why closure capture fails. Until then, tenant-naive engine + tenant-aware host stays canonical.

   PHP Copy

   // Backend wiring — /backend/save.php (sketch).
   //
   // The engine POSTs to whatever URL the buyer-app supplied at construct
   // time. The buyer-app's PHP handler reads tenantId from the query string
   // (or POST), validates it, and routes to the registry.
   
   require_once __DIR__ . '/_lib/Validator.php';
   require_once __DIR__ . '/_lib/Auth.php';
   require_once __DIR__ . '/_lib/ThemeRegistry.php';
   require_once __DIR__ . '/_lib/TenantRegistry.php';
   
   use DemoBuilder\Validator;
   use DemoBuilder\Auth;
   use DemoBuilder\ThemeRegistry;
   use DemoBuilder\TenantRegistry;
   
   Auth::requireSession();   // host's auth path — re-uses session validator.
   
   $tenantId = Validator::make($_GET)
       ->required('tenantId')
       ->regex('/^[A-Za-z0-9_-]+$/')
       ->validateOrFail()['tenantId'];
   
   // Defense-in-depth — re-validate that this tenantId is one this user
   // has permission for. The host's auth layer answers this; we just call.
   Auth::requireTenantAccess($tenantId);
   
   $themes   = new ThemeRegistry(__DIR__ . '/../themes');
   $registry = new TenantRegistry($themes);
   $saveDir  = $registry->saveDirFor($tenantId);
   
   // Now write the page payload under $savesRoot/$saveDir/$pageId.json.
   // (Validator already vetted the JSON shape; Storage handles the IO.)
   $savesRoot = __DIR__ . '/../var/saves';
   if (!is_dir($savesRoot . '/' . $saveDir)) {
       mkdir($savesRoot . '/' . $saveDir, 0755, true);
   }
   // ...write the file, return JsonResponse::ok(['ok' => true])