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, fetchesTenantConfig, 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
TenantConfigon 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
- Never hard-code brand strings, colors, keys, locales, or business thresholds — read them from the contract.
- New brand-varying behavior → add a
featureFlagor config field, document it here, and default it safely. - Secrets only via env/k8s secrets, never the DB config document.
- New tenant goes live via the Tenant Onboarding Runbook.