SaaS Platform System Design

A system design case study for a SaaS platform covering multi-tenancy, RBAC, data isolation, subscriptions, metering, and platform operations.

Modern Software-as-a-Service (SaaS) platforms power thousands of organizations from a single cloud platform.

Applications such as Salesforce, ServiceNow, GitHub Enterprise, Atlassian Cloud, HubSpot, and Zendesk allow every customer (tenant) to securely store and manage their own data while sharing the same underlying infrastructure.

Designing these systems requires solving challenges around multi-tenancy, security, tenant isolation, scalability, customization, billing, and high availability.

In this article, we'll design the High-Level Architecture (HLD) of an enterprise SaaS platform.

Learning Objectives

In this article you'll learn:

What is SaaS?
Multi-Tenant Architecture
Business Model
Tenant Lifecycle
User Lifecycle
Functional Requirements
Non-Functional Requirements
Capacity Planning
High-Level Architecture
Core Microservices
Request Flow
Tenant Isolation Models

What is SaaS?

Software-as-a-Service (SaaS) is a cloud-based software delivery model where multiple customers use the same application through the internet.

Instead of installing software locally, customers subscribe to the platform.

Examples include:

CRM
HR Management
Project Management
IT Service Management
Accounting
Collaboration Tools

Business Model

Revenue typically comes from:

Monthly subscriptions
Annual subscriptions
Usage-based billing
Enterprise licensing
Premium add-ons
API usage
Marketplace integrations

Core Actors

Actor	Responsibility
Tenant Administrator	Manages organization
Organization User	Uses platform
Platform Administrator	Global platform management
Billing Provider	Subscription billing
Identity Provider	Authentication
Notification Service	Email, SMS, Push

Multi-Tenant Architecture

Multiple organizations share the same application while keeping data isolated.

flowchart LR

TenantA

TenantB

TenantC

TenantA --> SaaSPlatform

TenantB --> SaaSPlatform

TenantC --> SaaSPlatform

Tenant Lifecycle

flowchart LR

Signup

Signup --> Trial

Trial --> Subscription

Subscription --> Active

Active --> Upgrade

Upgrade --> Renewal

User Lifecycle

flowchart LR

Invite

Invite --> Registration

Registration --> Login

Login --> Active

Active --> RoleUpdate

RoleUpdate --> Deactivated

Example Tenant Hierarchy

Organization

├── Departments

│   ├── Engineering

│   ├── HR

│   ├── Finance

│   └── Sales

└── Users

Functional Requirements

Tenant Features

Organization onboarding
Organization profile
Custom branding
Custom domain
Subscription management
User invitations
Team management
API keys
Audit logs

User Features

Login
Logout
Password reset
MFA
User profile
Notifications
Activity history
Preferences

Admin Features

Tenant provisioning
Subscription management
Billing
Usage monitoring
Feature management
Tenant suspension
Tenant deletion
Global reporting

Non-Functional Requirements

Requirement	Target
Availability	99.99%
Login Response	<300 ms
API Response	<500 ms
Scalability	Millions of users
Security	Enterprise Grade
Data Isolation	Strong
Compliance	SOC2 / GDPR
Disaster Recovery	Multi-Region

Capacity Estimation

Assume:

250,000 organizations
15 Million users
500 Million API requests/day
3 Million logins/day

Peak traffic:

60,000 requests/second
15,000 concurrent logins
10,000 onboarding requests/hour

Storage Estimation

Assume:

Organization metadata = 100 KB
User profile = 20 KB
Audit logs = 5 GB/day

Estimated annual storage:

Organizations

≈ 25 GB

Users

≈ 300 GB

Audit Logs

≈ 1.8 TB/year

Document storage and attachments generally consume significantly more storage.

Multi-Tenant Isolation Models

Model 1

Shared Database

flowchart LR

TenantA

TenantB

TenantC

TenantA --> Database

TenantB --> Database

TenantC --> Database

Advantages

Lowest cost
Easy maintenance
Simple deployment

Disadvantages

Lowest isolation
Shared performance

Model 2

Shared Database with Separate Schemas

flowchart LR

Database

Database --> SchemaA

Database --> SchemaB

Database --> SchemaC

Advantages

Better isolation
Easier backup

Disadvantages

Schema management complexity

Model 3

Database per Tenant

flowchart LR

TenantA --> DBA

TenantB --> DBB

TenantC --> DBC

Advantages

Strong isolation
Easier compliance
Independent scaling

Disadvantages

Higher operational cost
More databases to manage

Model 4

Hybrid Model

flowchart LR

SmallTenants --> SharedDB

LargeTenants --> DedicatedDB

This is the architecture adopted by many enterprise SaaS providers.

High-Level Architecture

flowchart TD

Users

Users --> DNS

DNS --> Gateway

Gateway --> Authentication

Gateway --> Tenant

Gateway --> User

Gateway --> Billing

Gateway --> Notification

Gateway --> Audit

Enterprise Architecture

flowchart TD

Gateway

AuthenticationService

TenantService

OrganizationService

UserService

RoleService

BillingService

SubscriptionService

NotificationService

AuditService

FeatureFlagService

AnalyticsService

Gateway --> AuthenticationService

Gateway --> TenantService

Gateway --> OrganizationService

Gateway --> UserService

Gateway --> RoleService

Gateway --> BillingService

Gateway --> SubscriptionService

Gateway --> NotificationService

Gateway --> AuditService

Gateway --> FeatureFlagService

Gateway --> AnalyticsService

Core Microservices

Service	Responsibility
Authentication Service	Login & Identity
Tenant Service	Tenant management
Organization Service	Organization details
User Service	User management
Role Service	RBAC
Subscription Service	Plans
Billing Service	Payments
Notification Service	Email, SMS
Audit Service	Audit logs
Feature Flag Service	Feature rollout
Analytics Service	Usage analytics

Request Flow

Every request must be tenant-aware.

flowchart LR

User

User --> Gateway

Gateway --> Authentication

Authentication --> TenantValidation

TenantValidation --> Service

Service --> Database

Tenant Resolution

Tenant identification may happen using:

Custom domain
Subdomain

company.example.com

HTTP Header

X-Tenant-ID

JWT Claim

tenantId

Authentication Flow

flowchart LR

User

User --> Login

Login --> IdentityProvider

IdentityProvider --> JWT

JWT --> APIs

Authorization

Recommended authorization model:

RBAC
ABAC (optional)
Fine-grained permissions

Example Roles:

Super Admin
Tenant Admin
Manager
User
Read Only

Feature Management

Different subscription plans unlock different features.

Example

Plan	Features
Free	Basic
Starter	Basic + Reports
Professional	Reports + API
Enterprise	All Features

Subscription Lifecycle

flowchart LR

Trial

Trial --> Paid

Paid --> Upgrade

Upgrade --> Renewal

Renewal --> Cancellation

Security Requirements

The platform should implement:

OAuth2
OpenID Connect
JWT
MFA
TLS 1.3
AES-256 Encryption
RBAC
API Rate Limiting

High Availability

Critical services:

Authentication
Tenant Service
Billing
Subscription
User Service

Deploy multiple replicas across multiple availability zones.

Design Principles

Multi-Tenant by design
Database per service
Stateless APIs
Event-driven communication
Horizontal scalability
Strong tenant isolation
Idempotent APIs
Retry and timeout handling
Observability built in

Engineering Challenges

Enterprise SaaS platforms must solve:

Tenant isolation
Secure authentication
Enterprise RBAC
Subscription billing
Feature rollout
Noisy neighbor problem
Custom branding
Compliance
Zero downtime deployments
Multi-region replication

Low-Level Design, Database Design & Event-Driven Architecture

In Part 1, we designed the business requirements, tenant lifecycle, multi-tenant architecture, and high-level microservices.

In this article, we'll design the Low-Level Design (LLD) of a production-grade SaaS platform.

Topics covered:

Database Design
Entity Relationship Diagram
Tenant Database
Organization Database
User Database
Role & Permission Database
Subscription Database
Billing Database
Notification Database
Audit Database
REST API Design
Sequence Diagrams
Kafka Topics
Event-Driven Architecture
Tenant Context Propagation

Low-Level Architecture

Each business capability owns its own database.

flowchart LR

Gateway

Gateway --> Authentication

Gateway --> Tenant

Gateway --> Organization

Gateway --> User

Gateway --> Role

Gateway --> Subscription

Gateway --> Billing

Gateway --> Notification

Gateway --> Audit

Gateway --> FeatureFlag

Database Per Service

Benefits

Loose coupling
Independent deployment
Better scalability
Fault isolation
Technology flexibility
Independent backups

Database Architecture

flowchart TD

TenantService --> TenantDB

OrganizationService --> OrganizationDB

UserService --> UserDB

RoleService --> RoleDB

SubscriptionService --> SubscriptionDB

BillingService --> BillingDB

NotificationService --> NotificationDB

AuditService --> AuditDB

FeatureFlagService --> FeatureDB

Tenant Database

Tenant Table

Column	Type
tenant_id	UUID
tenant_name	VARCHAR
subdomain	VARCHAR
custom_domain	VARCHAR
plan	VARCHAR
status	VARCHAR
created_at	TIMESTAMP
updated_at	TIMESTAMP

Tenant Status

Trial
Active
Suspended
Expired
Deleted

Organization Database

Organization Table

Column	Type
organization_id	UUID
tenant_id	UUID
company_name	VARCHAR
country	VARCHAR
timezone	VARCHAR
currency	VARCHAR
logo_url	VARCHAR
created_at	TIMESTAMP

User Database

User Table

Column	Type
user_id	UUID
tenant_id	UUID
organization_id	UUID
first_name	VARCHAR
last_name	VARCHAR
email	VARCHAR
password_hash	VARCHAR
status	VARCHAR
created_at	TIMESTAMP

User Status

Pending
Active
Locked
Disabled

Role Database

Role Table

Column	Type
role_id	UUID
tenant_id	UUID
role_name	VARCHAR
description	VARCHAR

Permission Table

Column	Type
permission_id	UUID
permission_name	VARCHAR
module	VARCHAR

User Role Mapping

Column	Type
user_role_id	UUID
user_id	UUID
role_id	UUID

Subscription Database

Subscription Table

Column	Type
subscription_id	UUID
tenant_id	UUID
plan_name	VARCHAR
billing_cycle	VARCHAR
start_date	DATE
end_date	DATE
status	VARCHAR

Available Plans

Free
Starter
Professional
Enterprise

Billing Database

Invoice Table

Column	Type
invoice_id	UUID
tenant_id	UUID
amount	DECIMAL
currency	VARCHAR
invoice_status	VARCHAR
due_date	DATE

Payment Table

Column	Type
payment_id	UUID
invoice_id	UUID
payment_provider	VARCHAR
transaction_reference	VARCHAR
payment_status	VARCHAR
paid_at	TIMESTAMP

Feature Flag Database

Feature Table

Column	Type
feature_id	UUID
feature_name	VARCHAR
description	VARCHAR

Tenant Feature Mapping

Column	Type
tenant_feature_id	UUID
tenant_id	UUID
feature_id	UUID
enabled	BOOLEAN

Notification Database

Notification Table

Column	Type
notification_id	UUID
tenant_id	UUID
user_id	UUID
channel	VARCHAR
status	VARCHAR
created_at	TIMESTAMP

Audit Database

Audit Log

Column	Type
audit_id	UUID
tenant_id	UUID
user_id	UUID
action	VARCHAR
module	VARCHAR
ip_address	VARCHAR
created_at	TIMESTAMP

Entity Relationship Diagram

flowchart TD

Tenant

Organization

User

Role

Permission

Subscription

Invoice

Payment

Feature

Audit

Notification

Tenant --> Organization

Organization --> User

User --> Role

Role --> Permission

Tenant --> Subscription

Subscription --> Invoice

Invoice --> Payment

Tenant --> Feature

Tenant --> Audit

User --> Notification

Tenant Context Propagation

Every request must carry tenant information.

flowchart LR

Client

Client --> Gateway

Gateway --> JWT

JWT --> TenantContext

TenantContext --> Services

Tenant Context contains:

Tenant ID
Organization ID
User ID
Roles
Subscription Plan

Request Flow

sequenceDiagram

Client->>Gateway: HTTP Request

Gateway->>Authentication: Validate JWT

Authentication-->>Gateway: User + Tenant

Gateway->>Tenant Service: Validate Tenant

Tenant Service-->>Gateway: Tenant Active

Gateway->>Business Service: Forward Request

Business Service-->>Client: Response

Organization Onboarding Flow

flowchart LR

Signup

Signup --> Tenant

Tenant --> Organization

Organization --> AdminUser

AdminUser --> TrialPlan

TrialPlan --> WelcomeEmail

User Invitation Flow

flowchart LR

Admin

Admin --> InviteUser

InviteUser --> Email

Email --> Registration

Registration --> ActiveUser

REST API Design

Tenant APIs

Create Tenant

POST /api/v1/tenants

Get Tenant

GET /api/v1/tenants/{tenantId}

Update Tenant

PUT /api/v1/tenants/{tenantId}

Suspend Tenant

POST /api/v1/tenants/{tenantId}/suspend

Organization APIs

Create Organization

POST /api/v1/organizations

Get Organization

GET /api/v1/organizations/{id}

User APIs

Invite User

POST /api/v1/users/invite

Activate User

POST /api/v1/users/activate

Get Users

GET /api/v1/users

Authentication APIs

POST /api/v1/auth/login

Refresh Token

POST /api/v1/auth/refresh

Logout

POST /api/v1/auth/logout

Subscription APIs

Create Subscription

POST /api/v1/subscriptions

Upgrade Plan

POST /api/v1/subscriptions/upgrade

Cancel Subscription

POST /api/v1/subscriptions/cancel

Billing APIs

Generate Invoice

POST /api/v1/invoices

Get Invoice

GET /api/v1/invoices/{invoiceId}

Record Payment

POST /api/v1/payments

{
  "email":"[email protected]",
  "password":"********"
}

{
  "accessToken":"jwt-token",
  "tenantId":"TEN1001",
  "organizationId":"ORG101",
  "userId":"USR10001",
  "roles":[
    "TENANT_ADMIN"
  ]
}

Event-Driven Architecture

Microservices communicate asynchronously using Kafka.

flowchart LR

Tenant

Tenant --> Kafka

User --> Kafka

Billing --> Kafka

Notification --> Kafka

Kafka --> Analytics

Kafka --> Audit

Kafka Topics

Topic	Producer	Consumer
tenant-created	Tenant Service	Organization Service
organization-created	Organization Service	Notification Service
user-invited	User Service	Notification Service
user-activated	User Service	Audit Service
subscription-created	Subscription Service	Billing Service
subscription-upgraded	Subscription Service	Notification Service
invoice-generated	Billing Service	Notification Service
payment-completed	Billing Service	Subscription Service
feature-enabled	Feature Service	Analytics Service
audit-created	Audit Service	Reporting Service

Sample Kafka Event

{
  "event":"TENANT_CREATED",
  "tenantId":"TEN1001",
  "organizationId":"ORG101",
  "plan":"TRIAL",
  "createdAt":"2026-08-10T10:15:00Z"
}

Data Consistency

Strong consistency:

User registration
Subscription creation
Payment processing
Role assignment

Eventually consistent:

Notifications
Analytics
Reporting
Audit dashboards

Error Handling

Error	Solution
Duplicate Tenant	Unique domain validation
Duplicate User	Unique email constraint
Payment Failure	Retry with idempotency
Notification Failure	Kafka retry
Tenant Suspended	Reject requests
Invalid JWT	Re-authentication

Best Practices

Every table should include tenant_id where applicable.
Always validate tenant ownership before accessing data.
Use UUIDs instead of sequential IDs.
Never trust tenant information from client requests alone.
Propagate tenant context through JWT claims or secure headers.
Publish domain events using Kafka.
Encrypt passwords using strong hashing algorithms.
Store audit logs separately from transactional data.
Make APIs idempotent where retries are possible.

Enterprise SaaS Architecture

flowchart TD

Gateway

Gateway --> Identity

Gateway --> Tenant

Gateway --> User

Gateway --> Billing

Gateway --> Feature

Gateway --> Notification

Gateway --> Audit

Gateway --> Analytics

Multi-Tenant Database Models

There are four common models.

Model	Isolation	Cost	Scalability
Shared Database	Low	Very Low	High
Shared Schema	Medium	Low	High
Schema per Tenant	High	Medium	Medium
Database per Tenant	Very High	High	High

Shared Database

flowchart LR

TenantA

TenantB

TenantC

TenantA --> Database

TenantB --> Database

TenantC --> Database

Pros

Lowest infrastructure cost
Easy maintenance
Simple backups

Cons

Weakest isolation
Shared resource contention

Schema per Tenant

flowchart LR

Database

Database --> SchemaA

Database --> SchemaB

Database --> SchemaC

Pros

Better isolation
Easier migration

Cons

Schema management complexity

Database per Tenant

flowchart LR

TenantA --> DB1

TenantB --> DB2

TenantC --> DB3

Advantages

Strong isolation
Easier compliance
Independent backup
Independent scaling

Ideal for enterprise customers.

Hybrid Deployment

flowchart LR

SmallTenants --> SharedDB

MediumTenants --> SchemaDB

EnterpriseTenants --> DedicatedDB

This model provides the best balance of cost and scalability.

Tenant Routing

Every request is routed using tenant metadata.

flowchart LR

Request

Request --> Gateway

Gateway --> TenantResolver

TenantResolver --> Database

Tenant identification may come from:

JWT
Custom Domain
Subdomain
API Header

Tenant Context

Every service receives:

Tenant ID

Organization ID

User ID

Roles

Plan

Region

Never trust client-supplied tenant identifiers without validation.

Redis Multi-Tenant Cache

Redis stores frequently accessed data.

Cache:

User session
Tenant configuration
Branding
Feature flags
Permissions
API tokens

Cache Key Design

Example

tenant:1001:user:205

tenant:1001:roles

tenant:1001:branding

tenant:1001:features

Namespacing prevents cache collisions.

Cache Architecture

flowchart LR

Application

Application --> Redis

Redis --> Database

Recommended TTL

Data	TTL
User Session	30 Minutes
Branding	1 Hour
Feature Flags	5 Minutes
Tenant Config	15 Minutes
Permissions	10 Minutes
API Keys	30 Minutes

CQRS

Separate reads from writes.

Write Side

Create Tenant
Invite User
Upgrade Plan
Billing
User Management

Read Side

Reports
Dashboards
Audit Search
User Search
Analytics

CQRS Architecture

flowchart LR

Client

Client --> CommandAPI

Client --> QueryAPI

CommandAPI --> WriteDB

WriteDB --> Kafka

Kafka --> ReadDB

ReadDB --> QueryAPI

Saga Pattern

Tenant onboarding spans multiple services.

Workflow

Create Tenant
Create Organization
Create Administrator
Create Trial Subscription
Enable Features
Send Welcome Email

Saga Flow

flowchart TD

Tenant

Tenant --> Organization

Organization --> User

User --> Subscription

Subscription --> Notification

Compensation Flow

If subscription creation fails:

flowchart LR

TenantCreated

TenantCreated --> Rollback

Rollback --> TenantDeleted

Feature Flags

Feature flags enable controlled rollout.

Examples

AI Assistant
Advanced Analytics
Workflow Automation
Webhooks
API Access

Feature Evaluation

flowchart LR

Request

Request --> FeatureService

FeatureService --> Enabled

FeatureService --> Disabled

White Label Branding

Enterprise customers may customize:

Logo
Colors
Login Page
Email Templates
Domain
Favicon

Branding Flow

flowchart LR

Tenant

Tenant --> Branding

Branding --> UI

Role-Based Access Control (RBAC)

flowchart LR

User

User --> Roles

Roles --> Permissions

Permissions --> Resource

Sample Roles

Role	Access
Platform Admin	Global
Tenant Admin	Organization
Manager	Department
Employee	Assigned Features
Auditor	Read Only

OAuth2 Authentication

Authentication Flow

flowchart LR

User

User --> Login

Login --> IdentityProvider

IdentityProvider --> AccessToken

AccessToken --> APIs

Supported Grant Types

Authorization Code
Client Credentials
Refresh Token

OpenID Connect

OIDC extends OAuth2 by providing identity information.

Claims

User ID
Name
Email
Tenant ID
Roles

SAML Single Sign-On

Enterprise customers often integrate with:

Microsoft Entra ID
Okta
Ping Identity
Google Workspace

SCIM Provisioning

SCIM automates:

User creation
User updates
User deletion
Group synchronization

API Rate Limiting

Prevent abuse.

Limits may apply per:

User
Tenant
API Key
Subscription Plan

Example Limits

Plan	Requests / Minute
Free	100
Starter	1,000
Professional	10,000
Enterprise	Custom

Webhooks

Notify external systems automatically.

Events

Tenant Created
User Invited
User Deleted
Subscription Upgraded
Payment Completed
Invoice Generated

Webhook Flow

flowchart LR

Application

Application --> Kafka

Kafka --> WebhookService

WebhookService --> CustomerAPI

Webhook Retry Strategy

Retry with exponential backoff
Store failed deliveries
Dead Letter Queue
Idempotency keys
Signature validation

API Versioning

Recommended strategy

/api/v1

/api/v2

Avoid breaking existing clients.

Noisy Neighbor Problem

Problem

One tenant consumes excessive resources, impacting others.

Solutions

Resource quotas
Rate limiting
Auto scaling
Dedicated databases
Dedicated compute nodes
Per-tenant monitoring

Multi-Region Architecture

flowchart LR

Users

Users --> RegionA

Users --> RegionB

RegionA --> DatabaseA

RegionB --> DatabaseB

Benefits

Lower latency
High availability
Disaster recovery
Regulatory compliance

Compliance

Enterprise SaaS platforms commonly support:

SOC 2
GDPR
HIPAA
ISO 27001
PCI DSS (if processing payments)

Security Best Practices

Implement:

OAuth2
OpenID Connect
SAML
SCIM
MFA
RBAC
TLS 1.3
AES-256
Secret Rotation
API Rate Limiting

Data Protection

Protect:

Personal Information
Payment Data
API Keys
Password Hashes
Audit Logs
Encryption Keys

Audit Logging

Every action should record:

Tenant ID
User ID
IP Address
Action
Resource
Timestamp
Correlation ID

Search Architecture

Use Elasticsearch/OpenSearch for:

User search
Audit search
Organization search
Activity logs
Global administration

Performance Optimization

Use:

Redis
Read Replicas
Connection Pooling
Batch Processing
Kafka
Async Notifications
CDN
Compression

Reliability Patterns

Use

Retry
Timeout
Circuit Breaker
Bulkhead
Dead Letter Queue
Outbox Pattern
Idempotency Keys

Best Practices

Prefer a hybrid tenant isolation model.
Include tenant context in every request.
Cache tenant metadata and feature flags.
Use CQRS for reporting workloads.
Use Saga Pattern for tenant onboarding.
Secure APIs with OAuth2 and OIDC.
Support enterprise SSO using SAML.
Automate user lifecycle with SCIM.
Protect APIs using tenant-aware rate limiting.
Continuously monitor tenant-specific metrics.

Production Goals

A modern SaaS platform should provide:

99.99% uptime
Zero-downtime deployments
Horizontal scalability
Secure tenant isolation
Automatic failover
Enterprise monitoring
Fast API responses
Disaster recovery

Enterprise Production Architecture

flowchart TD

Users

Users --> DNS

DNS --> CDN

CDN --> WAF

WAF --> LoadBalancer

LoadBalancer --> APIGateway

APIGateway --> Kubernetes

Kubernetes --> AuthService

Kubernetes --> TenantService

Kubernetes --> UserService

Kubernetes --> BillingService

Kubernetes --> NotificationService

Kubernetes --> AnalyticsService

Infrastructure Stack

Layer	Technology
DNS	Route53 / Cloud DNS
CDN	CloudFront / Azure CDN
WAF	AWS WAF
API Gateway	Kong / Spring Cloud Gateway
Load Balancer	ALB / NGINX
Containers	Docker
Orchestration	Kubernetes
Messaging	Kafka
Cache	Redis
Database	PostgreSQL
Search	Elasticsearch
Monitoring	Prometheus
Dashboard	Grafana
Logging	ELK / OpenSearch
Tracing	Jaeger / OpenTelemetry

Docker

Each microservice is packaged as a Docker image.

Advantages:

Consistent deployments
Dependency isolation
Faster delivery
Easy rollback
Immutable infrastructure

Sample Dockerfile

FROM eclipse-temurin:21-jre

WORKDIR /app

COPY target/tenant-service.jar app.jar

EXPOSE 8080

ENTRYPOINT ["java","-jar","app.jar"]

Kubernetes Architecture

flowchart TD

Ingress

Ingress --> Gateway

Gateway --> AuthPods

Gateway --> TenantPods

Gateway --> UserPods

Gateway --> BillingPods

Gateway --> NotificationPods

Gateway --> AnalyticsPods

Kubernetes Resources

Resource	Purpose
Pod	Running Application
Deployment	Replica Management
Service	Internal Networking
Ingress	External Routing
ConfigMap	Configuration
Secret	Credentials
StatefulSet	Stateful Services
HorizontalPodAutoscaler	Auto Scaling

Namespace Strategy

production

staging

uat

development

sandbox

Benefits

Resource isolation
Easier administration
Environment separation
Better security

Service Discovery

Applications communicate using Kubernetes DNS.

Example

tenant-service

billing-service

notification-service

analytics-service

Services are discovered dynamically without hardcoded IP addresses.

Internal Communication

flowchart LR

Gateway

Gateway --> Authentication

Authentication --> Tenant

Tenant --> Billing

Billing --> Notification

API Gateway Responsibilities

Authentication
Authorization
Routing
SSL Termination
Rate Limiting
Request Validation
API Aggregation
Logging

Load Balancing

flowchart LR

Users

Users --> LoadBalancer

LoadBalancer --> Pod1

LoadBalancer --> Pod2

LoadBalancer --> Pod3

Benefits

High availability
Better throughput
Fault tolerance
Low latency

Auto Scaling

Scale based on:

CPU
Memory
Active Sessions
Request Rate
Kafka Consumer Lag
Queue Length
API Latency

Recommended Scaling Priority

Service	Priority
Authentication	Critical
Tenant	Critical
User	High
Billing	Critical
Notification	High
Analytics	Medium
Audit	Medium

CI/CD Pipeline

flowchart LR

Developer

Developer --> Git

Git --> Build

Build --> UnitTests

UnitTests --> IntegrationTests

IntegrationTests --> SecurityScan

SecurityScan --> DockerImage

DockerImage --> Registry

Registry --> Kubernetes

Continuous Integration

Pipeline Steps

Source Checkout
Compile
Unit Testing
Integration Testing
Static Code Analysis
Dependency Scanning
Build Docker Image
Push to Registry

Continuous Delivery

Development

↓

QA

↓

UAT

↓

Performance Testing

↓

Security Testing

↓

Production

Deployment Strategies

Rolling Deployment

flowchart LR

OldVersion

OldVersion --> MixedVersion

MixedVersion --> NewVersion

Ideal for

Notification Service
Analytics Service
Audit Service

Blue-Green Deployment

flowchart LR

Users

Users --> Blue

Blue --> Green

Ideal for

Authentication
Tenant Service
Billing Service

Canary Deployment

5%

↓

20%

↓

50%

↓

100%

Use for

New Features
AI Services
Recommendation Engine
Search Improvements

Monitoring Architecture

flowchart LR

Applications

Applications --> Metrics

Applications --> Logs

Applications --> Traces

Metrics --> Prometheus

Prometheus --> Grafana

Logs --> ELK

Traces --> Jaeger

Infrastructure Metrics

Monitor:

CPU
Memory
Disk Usage
Network Traffic
JVM Heap
Kafka Lag
Redis Hit Ratio
Database Connections

Business Metrics

Track:

Active Tenants
Active Users
New Registrations
Subscription Renewals
Monthly Recurring Revenue
API Requests
Login Success Rate
Feature Usage

Tenant Metrics

Per tenant monitor:

API Calls
Storage Usage
Concurrent Users
Login Attempts
Subscription Status
Error Rate

Golden Signals

Signal	Description
Latency	Response Time
Traffic	Requests per Second
Errors	Failed Requests
Saturation	Resource Utilization

Logging Strategy

Every request should include:

Trace ID
Correlation ID
Tenant ID
User ID
Session ID
Request ID
Timestamp
Response Time

Sample Structured Log

{
  "traceId":"TR123456",
  "tenantId":"TEN1001",
  "userId":"USR101",
  "operation":"CreateUser",
  "status":"SUCCESS",
  "responseTime":45
}

Distributed Tracing

A single request may pass through many services.

flowchart LR

Gateway

Gateway --> Authentication

Authentication --> Tenant

Tenant --> Billing

Billing --> Notification

The same Trace ID follows the request across every service.

Health Checks

Spring Boot Actuator

GET /actuator/health

GET /actuator/liveness

GET /actuator/readiness

Kubernetes automatically removes unhealthy pods from service.

Alerting

Condition	Severity
Authentication Failure Rate > 2%	Critical
Billing Failure Rate > 2%	Critical
API Latency > 500 ms	Critical
Kafka Consumer Lag	Warning
Redis Memory > 90%	Warning
Pod CrashLoop	Critical
Database Replication Failure	Critical
Certificate Expiring Soon	Warning

Backup Strategy

Protect data using:

Hourly incremental backups
Daily full backups
Weekly archives
Cross-region replication
Immutable backup storage

Regularly perform restore validation.

Disaster Recovery

Prepare for:

Region failure
Database outage
Kubernetes cluster failure
Kafka outage
Redis outage
Identity Provider outage

Disaster Recovery Architecture

flowchart TD

PrimaryRegion

PrimaryRegion --> DatabaseA

PrimaryRegion --> KafkaA

DatabaseA --> Replication

KafkaA --> Replication

Replication --> SecondaryRegion

SecondaryRegion --> DatabaseB

SecondaryRegion --> KafkaB

Recovery Objectives

Objective	Target
Recovery Point Objective (RPO)	Near Zero
Recovery Time Objective (RTO)	Less Than 30 Minutes

Production Failure Scenarios

Authentication Service Failure

Recovery

Redirect traffic
Restart pods
Retry authentication
Use standby replicas

Database Failure

Recovery

Promote replica
Redirect traffic
Restore writes
Verify replication

Kafka Failure

Recovery

Retry producers
Retry consumers
Dead Letter Queue
Multi-broker replication

Redis Failure

Recovery

Automatic failover
Cache rebuild
Fallback to database

Kubernetes Node Failure

Recovery

Reschedule pods
Replace node
Rebalance workloads

Region Failure

Recovery

DNS failover
Activate standby region
Promote secondary databases
Resume tenant traffic

Production Security

Enterprise SaaS platforms implement:

TLS 1.3
Mutual TLS
Secret Rotation
Kubernetes Network Policies
RBAC
Container Image Scanning
Runtime Threat Detection
Zero Trust Networking

Performance Optimization

Improve performance with:

Redis caching
Read replicas
Connection pooling
Async processing
Kafka partitioning
CDN
Response compression

Cost Optimization

Reduce cloud costs using:

Horizontal Pod Autoscaler
Cluster Autoscaler
Reserved Instances
Spot Instances for batch jobs
Storage lifecycle policies
Log retention policies
Right-sized Kubernetes nodes

Production Readiness Checklist

Area	Status
Docker Images	✓
Kubernetes	✓
CI/CD	✓
Security	✓
Monitoring	✓
Logging	✓
Distributed Tracing	✓
Backup Validation	✓
Disaster Recovery	✓
Alerting	✓
Auto Scaling	✓
Rollback Strategy	✓

Production Operations

Operations teams monitor:

Tenant health
Authentication success
Billing pipeline
User registrations
Kafka consumer lag
Redis health
API latency
Database performance
Infrastructure utilization
Operational costs

Best Practices

Keep services stateless.
Scale services independently.
Use Blue-Green deployments for critical services.
Automate rollback on deployment failures.
Propagate Trace IDs across all services.
Encrypt tenant data at rest and in transit.
Continuously monitor tenant-specific SLAs.
Regularly test backup restoration.
Perform load, stress, and chaos testing.
Automate infrastructure provisioning with Infrastructure as Code.

Enterprise Scale

Large SaaS platforms commonly support:

Millions of users
Hundreds of thousands of tenants
Billions of API requests
Millions of authentication requests
Thousands of deployments every month

Challenge 1 — Tenant Onboarding

A new organization should become operational within minutes.

Workflow

Signup

↓

Tenant Creation

↓

Organization

↓

Administrator

↓

Trial Subscription

↓

Welcome Email

↓

Ready

Challenges

Duplicate domains
Email verification
Subscription provisioning
Initial feature configuration

Solutions

Saga Pattern
Idempotent APIs
Asynchronous provisioning
Event-driven onboarding

Challenge 2 — Tenant Migration

Enterprise customers often outgrow shared infrastructure.

Migration

flowchart LR

SharedDatabase

SharedDatabase --> Migration

Migration --> DedicatedDatabase

Migration Steps

Create dedicated database
Copy tenant data
Verify consistency
Switch traffic
Archive old records

Challenge 3 — Noisy Neighbor Problem

One tenant consumes excessive resources.

Examples

Large reports
Bulk imports
Massive API traffic
Long-running searches

Solutions

CPU quotas
Memory quotas
Per-tenant rate limiting
Separate worker pools
Dedicated databases
Dedicated Kubernetes nodes

Resource Isolation

flowchart LR

TenantA --> PoolA

TenantB --> PoolB

Enterprise --> DedicatedCluster

Challenge 4 — Subscription Upgrade

Example

Starter

↓

Professional

↓

Enterprise

Upgrade Tasks

Enable new features
Increase API quota
Update billing
Enable integrations
Notify users

Challenge 5 — Billing Failure

Possible causes

Card expired
Bank declined payment
Payment gateway unavailable
Fraud detection
Network timeout

Solutions

Retry with exponential backoff
Backup payment provider
Grace period
Customer notification

Billing Workflow

flowchart LR

Invoice

Invoice --> PaymentGateway

PaymentGateway --> Success

PaymentGateway --> Retry

Retry --> BackupGateway

Challenge 6 — Feature Rollout

New functionality should not be released to every customer simultaneously.

Deployment Strategy

Internal

↓

Beta Customers

↓

5%

↓

20%

↓

50%

↓

100%

Use Feature Flags for controlled releases.

Challenge 7 — Zero-Downtime Schema Migration

Never stop production traffic.

Recommended Strategy

Add new columns
Deploy new application
Backfill data
Switch reads
Remove legacy columns

Avoid destructive schema changes during active deployments.

Challenge 8 — Enterprise Integrations

Customers integrate with:

Microsoft Entra ID
Okta
Google Workspace
Slack
Microsoft Teams
Salesforce
ServiceNow
Jira
SAP

Use

REST APIs
Webhooks
OAuth2
SCIM
SAML

Challenge 9 — Audit & Compliance

Every important action should be recorded.

Example

Event	Logged
Login	✓
User Invitation	✓
Password Reset	✓
Permission Change	✓
Billing Update	✓
Subscription Upgrade	✓
API Key Creation	✓

Challenge 10 — Regional Failure

Potential failures

Cloud outage
Database outage
Kubernetes cluster failure
Identity provider outage

Recovery

DNS failover
Multi-region routing
Database promotion
Automatic traffic switching

Scalability Strategy

flowchart TD

Gateway

Gateway --> Authentication

Gateway --> Tenant

Gateway --> User

Gateway --> Billing

Gateway --> Notification

Gateway --> Analytics

Gateway --> Audit

Every service scales independently.

Database Scaling

Techniques

Read replicas
Connection pooling
Database partitioning
Archive inactive tenants
Online indexing

Kafka Scaling

Topic

↓

256 Partitions

↓

Thousands of Consumers

Benefits

High throughput
Parallel processing
Fault tolerance

Redis Scaling

flowchart LR

Applications

Applications --> RedisCluster

RedisCluster --> Node1

RedisCluster --> Node2

RedisCluster --> Node3

Cache

Tenant configuration
Branding
Sessions
Permissions
Feature flags
API tokens

Reliability Patterns

Use

Retry
Timeout
Circuit Breaker
Bulkhead
Dead Letter Queue
Outbox Pattern
Idempotency Keys

Architecture Trade-offs

Shared vs Dedicated Database

Shared Database	Dedicated Database
Lower Cost	Higher Isolation
Easier Operations	Better Compliance
Resource Sharing	Independent Scaling

REST vs Event-Driven

REST	Kafka
Immediate Response	Asynchronous Processing
Easier Debugging	Loose Coupling
Request/Response	Event Streaming

JWT vs Session

JWT	Session
Stateless	Server Managed
Better Scalability	Easier Revocation
API Friendly	Traditional Applications

SQL vs NoSQL

SQL	NoSQL
Billing	Activity Logs
Tenant Data	Analytics
ACID Transactions	Flexible Schema

Shared Cache vs Tenant Cache

Shared Cache	Tenant Namespace
Simpler	Better Isolation
Lower Memory	Prevents Key Collision
Easier Setup	Safer for Multi-Tenant Systems

Low latency and disaster recovery.

Common Production Issues

Issue	Solution
Duplicate Tenant	Domain uniqueness validation
Duplicate User	Unique email constraint
Subscription Failure	Retry with Saga compensation
Billing Failure	Retry + backup gateway
Cache Inconsistency	Cache invalidation events
Kafka Consumer Lag	Scale consumer group
Slow Search	Elasticsearch optimization
Database Hotspots	Partitioning
Pod CrashLoop	Kubernetes self-healing
Region Failure	Automated failover

Best Practices

Make every service tenant-aware.
Use hybrid tenant isolation.
Encrypt tenant data at rest and in transit.
Apply per-tenant quotas.
Cache tenant metadata.
Implement feature flags.
Keep audit logs immutable.
Monitor tenant-level SLAs.
Automate backup verification.
Regularly perform chaos engineering.

Common Design Mistakes

Using Global Database Queries

Always filter by tenant.

Missing Tenant Context

Every request should include validated tenant context.

Maintain isolated credentials.

Hardcoding Subscription Features

Use configurable feature flags.

Ignoring Audit Logging

Every administrative action should be traceable.

Synchronous Integrations

Use asynchronous processing whenever possible.

Missing Idempotency

Protect retries from creating duplicate resources.

30 SaaS Platform System Design Interview Questions

1. What is a Multi-Tenant SaaS Platform?

A platform where multiple organizations share the same application while maintaining logical or physical data isolation.

2. What are the different tenant isolation models?

Shared database, shared schema, schema-per-tenant, database-per-tenant, and hybrid.

3. Which model is best?

Hybrid is commonly preferred because it balances cost, isolation, and operational complexity.

4. Why include Tenant ID in every request?

To ensure data isolation, authorization, routing, and auditing.

5. How is tenant context propagated?

Through validated JWT claims, secure headers, or tenant resolution at the API Gateway.

6. Why use API Gateway?

Authentication, routing, rate limiting, logging, and request validation.

7. Why use Kafka?

To decouple services and process asynchronous events reliably.

8. Why use Redis?

Fast access to sessions, feature flags, tenant configuration, and permissions.

9. Why use CQRS?

To separate transactional writes from read-heavy dashboards and reports.

10. Why use Saga Pattern?

To coordinate distributed business transactions such as onboarding and subscription changes.

11. How do you prevent noisy neighbors?

Per-tenant quotas, rate limits, resource isolation, and dedicated infrastructure for large tenants.

12. How do you migrate a tenant?

Create a new environment, synchronize data, validate, switch traffic, and decommission the old location.

13. How do feature flags help?

They enable controlled rollouts without redeploying applications.

14. Why support SAML?

Enterprise customers often require Single Sign-On with their identity providers.

15. What is SCIM?

A standard for automated user and group provisioning.

16. How do you secure APIs?

OAuth2, JWT, TLS 1.3, RBAC, rate limiting, and API validation.

17. What data should be cached?

Tenant configuration, branding, permissions, sessions, and feature flags.

18. What should not be cached?

Billing transactions, payment status, and highly transactional financial data.

19. How do you implement audit logging?

Capture immutable records containing tenant, user, action, resource, timestamp, and correlation ID.

20. How do you scale globally?

Deploy active-active or active-passive multi-region architectures with replicated services and databases.

21. How do you version APIs?

Use URI versioning such as /api/v1 or /api/v2 while maintaining backward compatibility.

22. What deployment strategy is safest?

Blue-Green or Canary deployments with automated rollback.

23. Which metrics should be monitored?

API latency, authentication success, active tenants, subscription renewals, Kafka lag, and infrastructure utilization.

24. Why use Kubernetes?

Container orchestration, self-healing, service discovery, and auto scaling.

25. How do you isolate enterprise customers?

Dedicated databases, compute nodes, and networking where appropriate.

26. How do you ensure compliance?

Encryption, audit logging, access control, data retention policies, and regulatory controls.

27. How do you secure secrets?

Use centralized secret management with automatic rotation.

28. How do webhooks improve integrations?

They push real-time events to external systems instead of requiring polling.

29. How do you reduce cloud costs?

Auto scaling, right-sized infrastructure, storage lifecycle policies, and workload optimization.

30. What is the most important SaaS design principle?

Every component should be tenant-aware, secure, scalable, and operationally observable.

SaaS Platform Architecture Cheat Sheet

Area	Recommended Technology
Architecture	Microservices
Authentication	OAuth2 + OpenID Connect
Enterprise SSO	SAML 2.0
User Provisioning	SCIM
API Gateway	Kong / Spring Cloud Gateway
Cache	Redis
Messaging	Kafka
Database	PostgreSQL
Search	Elasticsearch
Distributed Workflow	Saga Pattern
Read Optimization	CQRS
Feature Rollout	Feature Flags
Deployment	Kubernetes
Monitoring	Prometheus + Grafana
Logging	ELK / OpenSearch
Tracing	OpenTelemetry + Jaeger
Disaster Recovery	Multi-Region

Complete Enterprise SaaS Architecture

flowchart TD

Users

Users --> Gateway

Gateway --> AuthenticationService

Gateway --> TenantService

Gateway --> OrganizationService

Gateway --> UserService

Gateway --> RoleService

Gateway --> FeatureFlagService

Gateway --> BillingService

Gateway --> SubscriptionService

Gateway --> NotificationService

Gateway --> AuditService

Gateway --> AnalyticsService

Gateway --> IntegrationService

BillingService --> Kafka

SubscriptionService --> Kafka

UserService --> Kafka

NotificationService --> Kafka

Kafka --> ReportingService

Kafka --> SearchIndexer

Kafka --> DataWarehouse

AuthenticationService --> IdentityDatabase

TenantService --> TenantDatabase

UserService --> UserDatabase

BillingService --> BillingDatabase

AnalyticsService --> AnalyticsDatabase

FeatureFlagService --> Redis

Production Readiness Checklist

Area	Ready
Multi-Tenant Isolation	✅
Authentication	✅
RBAC	✅
SSO	✅
SCIM	✅
Feature Flags	✅
Kafka Integration	✅
Redis Caching	✅
Kubernetes	✅
CI/CD	✅
Monitoring	✅
Logging	✅
Distributed Tracing	✅
Disaster Recovery	✅
Compliance	✅

Final Summary

Building an enterprise SaaS platform requires much more than creating REST APIs. Modern SaaS systems must provide secure multi-tenancy, strong tenant isolation, identity management, subscription billing, feature management, integrations, observability, and cloud-native scalability.

Throughout this five-part series, we designed a production-ready SaaS platform covering business requirements, high-level architecture, low-level design, advanced multi-tenant patterns, security, deployment, observability, disaster recovery, and operational best practices.

By combining Java, Spring Boot, Kafka, Redis, PostgreSQL, Elasticsearch, OAuth2, CQRS, Saga Pattern, Docker, and Kubernetes, engineering teams can build highly available SaaS platforms that securely serve millions of users across hundreds of thousands of organizations.

Key Takeaways

✅ Design every service to be tenant-aware.
✅ Choose the appropriate tenant isolation strategy for each customer segment.
✅ Use event-driven communication with Kafka.
✅ Cache tenant metadata and feature flags using Redis.
✅ Apply CQRS for reporting and analytics.
✅ Use Saga Pattern for distributed business workflows.
✅ Secure access with OAuth2, OIDC, RBAC, SAML, and SCIM.
✅ Continuously monitor tenant-specific SLAs and infrastructure metrics.
✅ Automate deployments and disaster recovery.
✅ Build scalable, resilient, cloud-native enterprise platforms.

SaaS Platform System Design

Learning Objectives

What is SaaS?

Business Model

Core Actors

Multi-Tenant Architecture

Tenant Lifecycle

User Lifecycle

Example Tenant Hierarchy

Functional Requirements

Tenant Features

User Features

Admin Features

Non-Functional Requirements

Capacity Estimation

Storage Estimation

Multi-Tenant Isolation Models

Model 1

Shared Database

Model 2

Shared Database with Separate Schemas

Model 3

Database per Tenant

Model 4

Hybrid Model

High-Level Architecture

Enterprise Architecture

Core Microservices

Request Flow

Tenant Resolution

Authentication Flow

Authorization

Feature Management

Subscription Lifecycle

Security Requirements

High Availability

Design Principles

Engineering Challenges

Low-Level Design, Database Design & Event-Driven Architecture

Low-Level Architecture

Database Per Service

Database Architecture

Tenant Database

Tenant Table

Tenant Status

Organization Database

Organization Table

User Database

User Table

User Status

Role Database

Role Table

Permission Table

User Role Mapping

Subscription Database

Subscription Table

Available Plans

Billing Database

Invoice Table

Payment Table

Feature Flag Database

Feature Table

Tenant Feature Mapping

Notification Database

Notification Table

Audit Database

Audit Log

Entity Relationship Diagram

Tenant Context Propagation

Request Flow

Organization Onboarding Flow

User Invitation Flow

REST API Design

Tenant APIs

Organization APIs

User APIs

Authentication APIs

Subscription APIs

Billing APIs

Sample Login Request