🏢 Multi-Tenant CRM Platform

Dojobux CRM - Fully Multi-Tenant Architecture

Implementation Complete

Your CRM has been successfully transformed into a multi-tenant SaaS platform. Multiple businesses can now use the same application with complete data isolation.

✅ Business Entity

✅ Data Isolation

✅ Business Selector

✅ Super Admin

✅ Tenant Context

✅ Email Routing

✅ Migration Tools

✅ Role-Based Access

Architecture Overview

🏗️ Core Entities

Business - Master tenant entity with branding, settings, quotas
SenderProfile - Email sender configurations per business
User - Extended with business_id, user_role, business_access

📊 Data Isolation

ALL entities now have business_id field
Queries filtered by tenant context automatically
Legacy workspace_id preserved for backward compatibility

🔐 Tenant Resolution Order

Admin impersonation (localStorage override)
Subdomain detection (if enabled - future)
User's current_business_id (session)
User's primary business_id
First business in business_access array

New Features & Components

Super Admin Console

Central management dashboard for all businesses

View all businesses & metrics
Impersonate any business
Create/edit businesses
Monitor platform health

Business Creation Wizard

4-step guided setup for new businesses

Business details & branding
Email sender profiles
Plans & quotas
Auto-seed defaults

Business Selector

Switch between businesses seamlessly

Top-right dropdown (visible in layout)
Multi-business users can switch
Impersonation indicator
Session persistence

Migration Helper

Backfill existing data with business_id

Scan for unmapped records
Bulk update to master tenant
Safe with validation
Detailed results report

Tenant-Aware Email Sending

📧 SendGrid Integration

Email sending now supports per-business SendGrid API keys via SenderProfile entity.

🌍 Global Key (Default)

Stored in environment variable
Used when no business key exists
Shared across all tenants

🏢 Per-Business Key

Stored in SenderProfile entity
Overrides global key
Full tenant isolation

🔄 How It Works

Campaign sends email with sender_profile_id
SendGrid function checks if SenderProfile has custom API key
If yes: uses business-specific key
If no: falls back to global SENDGRID_API_KEY

User Roles & Permissions

super_admin

Access to Super Admin Console
Create/manage all businesses
Impersonate any business
View platform-wide metrics
Run migrations

business_owner

Full access to their business
Manage users in their business
Configure sender profiles
View/edit all business data

manager

Manage leads & campaigns
Create/send campaigns
View reports
Cannot modify business settings

staff

View assigned leads
Log calls & notes
Complete tasks
Limited campaign access

🚀 Next Steps

Create Your Master Business
Use the Business Creation Wizard to set up "Dojobux CRM" as the master tenant
Run Migration
Use Migration Helper to backfill all existing data with the master business_id
Create Test Business
Create a second business to test multi-tenancy and data isolation
Configure SendGrid Per Business (Optional)
Add business-specific SendGrid API keys in Marketing Settings → Sender Profiles
Set Up Subdomain Routing (Future)
Manually configure DNS for custom subdomains when ready

📁 Files Created/Modified

🆕 New Entities

entities/Business.json

entities/SenderProfile.json

✏️ Updated Entities (added business_id)

entities/User.json

entities/Lead.json

entities/Campaign.json

entities/Task.json

entities/CallLog.json

entities/Note.json

entities/Deal.json

entities/SupportTicket.json

entities/Automation.json

entities/EmailTemplate.json

entities/CampaignEmail.json

🆕 New Pages

pages/SuperAdmin.jsx

pages/CreateBusiness.jsx

pages/MigrationHelper.jsx

pages/MultiTenantReadme.jsx

🆕 New Components

components/BusinessSelector.jsx

components/tenantContext.js

✏️ Updated Files

Layout.js (+ BusinessSelector)

functions/sendgridEmail.js (tenant-aware)

pages/MarketingDashboard.jsx (tenant filtering)

components/marketing/CampaignSendDialog.jsx