Multi-Tenant SaaS Architecture Using Django & React

Building a SaaS product almost always leads to one critical architectural decision early on: multi-tenancy.
How do you serve multiple organizations (tenants) from a single codebase while keeping data secure, scalable, and customizable?

In this blog, we’ll design a production-grade multi-tenant architecture using Django (backend) and React (frontend), covering:

• Organization-based data isolation
• Subdomain-based tenant routing
• Tenant-aware API and UI rendering
• Common pitfalls and best practices

This approach works especially well for ERP, accounting, CRM, and finance platforms.

 

---

1. What Is Multi-Tenancy?

Multi-tenancy means a single application instance serves multiple customers (organizations), while keeping their data logically isolated.

Common SaaS Examples

• company1.yourapp.com
• company2.yourapp.com

Each company:

• Has its own users
• Sees only its own data
• Shares the same codebase and infrastructure

 

---

2. Multi-Tenancy Models (Quick Overview)

Before choosing an approach, let’s briefly compare models:

 

 

This blog focuses on Row-Based Multi-Tenancy, which is the most common and scalable approach with Django + React.

 

---

3. Core Concept: Organization as the Tenant

At the heart of our architecture is an Organization model.

Django Organization Model

class Organization(models.Model):

    name = models.CharField(max_length=255)

    slug = models.SlugField(unique=True)

    is_active = models.BooleanField(default=True)

    created_at = models.DateTimeField(auto_now_add=True)

 

The slug will be used for:

• Subdomains (acme.yourapp.com)
   
• API tenant resolution
   
• UI branding

 

---

4. Organization-Based Data Isolation (Backend)

Every business-related model must be linked to an organization.

Example: Invoice Model

class Invoice(models.Model):

    organization = models.ForeignKey(

        Organization,

        on_delete=models.CASCADE,

        related_name="invoices"

    )

    invoice_number = models.CharField(max_length=50)

    total_amount = models.DecimalField(max_digits=10, decimal_places=2)

 

Key Rule

Every query must be organization-scoped

❌ Bad:

Invoice.objects.all()

 

✅ Good:

Invoice.objects.filter(organization=request.organization)

 

---

5. Resolving Tenant via Subdomain (Django Middleware)

We use the subdomain to identify the tenant.

Example Domain

https://acme.yourapp.com

Custom Middleware

class OrganizationMiddleware:

    def __init__(self, get_response):

        self.get_response = get_response

 

    def __call__(self, request):

        host = request.get_host().split(':')[0]

        subdomain = host.split('.')[0]

 

        try:

            request.organization = Organization.objects.get(slug=subdomain)

        except Organization.DoesNotExist:

            request.organization = None

 

        return self.get_response(request)

Middleware Placement

MIDDLEWARE = [

    'django.middleware.security.SecurityMiddleware',

    'yourapp.middleware.OrganizationMiddleware',

    ...

]

 

Now every request knows its organization.

 

---

6. Securing Data at the API Layer (DRF)

Base Tenant-Aware ViewSet

class TenantModelViewSet(ModelViewSet):

    def get_queryset(self):

        return super().get_queryset().filter(

            organization=self.request.organization

        )

 

    def perform_create(self, serializer):

        serializer.save(organization=self.request.organization)

Example Usage

class InvoiceViewSet(TenantModelViewSet):

    queryset = Invoice.objects.all()

    serializer_class = InvoiceSerializer

This guarantees:

• No cross-tenant data leaks
• No need to manually filter everywhere

 

---

7. User–Organization Relationship

A user can belong to one or multiple organizations.

User Organization Mapping

class OrganizationUser(models.Model):

    user = models.ForeignKey(User, on_delete=models.CASCADE)

    organization = models.ForeignKey(Organization, on_delete=models.CASCADE)

    role = models.CharField(max_length=50)

Benefits

• Role-based access per organization
• Same email across multiple companies
• Clean permission handling

 

---

8. React Frontend: Tenant Awareness

The frontend must also be tenant-aware.

Detect Tenant from Subdomain

export const getTenant = () => {

  const host = window.location.hostname;

  return host.split(".")[0];

};

 

Store Tenant in Context

const TenantContext = React.createContext();

 

export const TenantProvider = ({ children }) => {

  const tenant = getTenant();

 

  return (

    <TenantContext.Provider value={tenant}>

      {children}

    </TenantContext.Provider>

  );

};

 

Wrap your app:

<TenantProvider>

  <App />

</TenantProvider>

 

---

9. Tenant-Aware API Calls (React)

All API calls automatically hit the correct tenant via subdomain.

axios.defaults.baseURL = `${window.location.protocol}//${window.location.host}/api`;

 

No tenant ID in query params = clean & secure APIs.

 

---

10. Tenant-Specific UI Rendering

Dynamic Branding

const tenantThemes = {

  acme: { primary: "#0A3D62" },

  globex: { primary: "#1B9C85" },

};

 

const theme = tenantThemes[tenant] || defaultTheme;

Feature Toggles per Tenant

if (tenant === "enterprise") {

  showAdvancedReports();

}

This enables:

• White-label SaaS
• Per-customer customization
• Tier-based features

 

---

11. Authentication in Multi-Tenant Systems

Key rules:

• Users authenticate globally
• Authorization is tenant-specific

Login Flow

1. User logs in
2. Backend returns:
   • User info
   • Accessible organizations
3. User selects organization (if multiple)
4. Subdomain redirects accordingly

 

---

12. Common Pitfalls (And How to Avoid Them)

❌ Forgetting organization filters

Fix: Base tenant-aware ViewSets

❌ Hardcoding tenant IDs

Fix: Always derive from request/subdomain

❌ Signals without tenant context

Fix: Pass organization explicitly in signals/events

❌ Shared cache without tenant key

Fix: Use tenant-prefixed cache keys

 

---

13. Performance & Scaling Tips

• Add DB indexes on organization_id
• Use select_related("organization")
• Cache tenant settings (Redis)
• Rate-limit APIs per tenant
• Background jobs must include tenant context

 

---

14. When This Architecture Is Ideal

 ✅ Accounting / ERP systems
✅ CRM platforms
✅ HR & Payroll SaaS
✅ Inventory & Billing systems

❌ Heavy regulatory isolation needs (use DB-per-tenant instead)

 

---

Conclusion

A well-designed multi-tenant architecture with Django & React provides:

• Strong data isolation
• Clean APIs
• Scalable infrastructure
• Tenant-aware UI customization

By resolving tenants via subdomains, enforcing organization-level filtering, and building tenant-aware frontend logic, you can confidently scale your SaaS without rewriting your core architecture.