Skip to main content

Multi-Tenancy & White-Label

Model: per-tenant deployment​

Each company (tenant) runs in its own isolated deployment — a dedicated Kubernetes namespace with its own Medusa, NestJS, Payload, Postgres, Mongo, Redis, and object-storage bucket. All tenants are built from one templated pipeline off the same codebase.

Why per-tenant (not shared multi-tenant): strong data isolation per brand, independent scaling, contained blast radius, simpler compliance. The cost — more infra per brand — is acceptable for a small number of medium/large brands and is automated away by the pipeline.

The Tenant Config Contract​

The application is tenant-agnostic. Everything brand-specific is supplied as configuration. No brand name, color, business rule, or key is hard-coded. The contract has two parts:

A. Environment variables (12-factor — secrets & wiring)​

# Identity
TENANT_ID=utlsolar
TENANT_NAME="UTL Solar"
PRIMARY_DOMAIN=utlsolar.com
DEFAULT_LOCALE=en-IN
SUPPORTED_LOCALES=en-IN,hi-IN,ta-IN

# Data
DATABASE_URL=postgres://... # Medusa
MONGODB_URI=mongodb://... # domains + Payload
REDIS_URL=redis://...

# Object storage (branding + media)
S3_ENDPOINT=...
S3_BUCKET=utlsolar-assets
S3_ACCESS_KEY=... # secret
S3_SECRET_KEY=... # secret

# Payments (Hyperswitch + connectors)
HYPERSWITCH_URL=...
HYPERSWITCH_API_KEY=... # secret
RAZORPAY_KEY_ID=... / CCAVENUE_... / CASHFREE_...

# Courier / marketplaces / automation
SHIPROCKET_EMAIL=... / SHIPROCKET_PASSWORD=... # secret
AMAZON_SPAPI_*=... / FLIPKART_*=... # secret
N8N_URL=http://n8n.<ns>.svc.cluster.local # in-cluster
N8N_WEBHOOK_SECRET=... / ZAPIER_WEBHOOK_SECRET=... / PABBLY_WEBHOOK_SECRET=...

# Compliance
GSTIN=... / LEGAL_ENTITY_NAME=... / EINVOICE_*=...

B. Tenant config document (DB — branding & behavior)​

A TenantConfig document (Mongo) served by the Tenant Config & Branding service. Non-secret, hot-reloadable, editable by admins:

{
"tenantId": "utlsolar",
"branding": {
"logoUrl": "s3://utlsolar-assets/logo.svg",
"faviconUrl": "...",
"heroImages": ["..."],
"colorTokens": { "primary": "#0B7", "accent": "#FFB400", "…": "…" },
"fontFamily": "Inter"
},
"locales": { "default": "en-IN", "supported": ["en-IN","hi-IN","ta-IN"] },
"currency": "INR",
"featureFlags": {
"amazonChannel": true, "flipkartChannel": false,
"amc": true, "loyalty": true, "affiliate": true,
"crossVendorService": true, "subsidyWorkflow": true
},
"service": { "crossVendorPaid": true, "defaultSlaHours": 48 },
"contact": { "supportPhone": "...", "whatsapp": "...", "supportEmail": "..." }
}

Secrets → env. Branding/behavior → DB. Anything an admin should change without a redeploy goes in the config document.

How branding flows to the surfaces​

  • Web: Next.js reads TENANT_ID, fetches TenantConfig, injects color tokens as CSS variables at the layout root — which TailwindCSS + shadcn/ui + Tailwind UI consume, so the same components rebrand per tenant with no rebuild; logo/hero served from the tenant bucket via CDN. See Frontend & Design System.
  • Apps: RN apps fetch TenantConfig on launch; theme provider applies tokens; assets cached.
  • Templates: invoices, emails, warranty cards, PDFs all pull logo/colors/contact from config.

Feature flags​

Each module checks featureFlags so a tenant can enable/disable capabilities (e.g. a brand without a marketplace presence sets amazonChannel: false). Flags are read centrally and exposed to clients via the BFF.

Rules for contributors​

  1. Never hard-code brand strings, colors, keys, locales, or business thresholds — read them from the contract.
  2. New brand-varying behavior → add a featureFlag or config field, document it here, and default it safely.
  3. Secrets only via env/k8s secrets, never the DB config document.
  4. New tenant goes live via the Tenant Onboarding Runbook.