Multi-Tenancy

Multi-tenancy is a foundational architectural principle of the MATIH Platform, not a feature added after the fact. Every component -- from the database layer to the Kubernetes infrastructure -- is designed to securely isolate tenant data while sharing the same underlying compute resources.

Isolation Model

The platform implements a hybrid isolation model that operates at four distinct layers, providing defense in depth:

Layer	Mechanism	Implementation
Infrastructure	Kubernetes namespace per tenant	Dedicated namespace with NetworkPolicy, ResourceQuota, RBAC
Network	Network policies	Per-namespace ingress/egress rules, TLS everywhere
Application	Thread-local tenant context	`TenantContextHolder` with `ThreadLocal` storage
Data	Schema-per-tenant	Per-tenant PostgreSQL schemas via Hibernate multi-tenancy

Each layer operates independently. A failure at one layer does not compromise the others.

Tenant Lifecycle

Each tenant passes through a well-defined provisioning workflow:

Phase	Action	Outcome
1. Validate	Check tenant details and uniqueness	Tenant record created
2. Create Namespace	Provision Kubernetes namespace	Isolated namespace with RBAC
3. Deploy Secrets	Create required Kubernetes secrets	Credentials provisioned
4. Deploy Databases	Provision per-tenant PostgreSQL schemas	Data isolation established
5. Deploy Services	Helm install Data Plane services	Workloads running
5.5. Deploy Ingress	NGINX ingress controller, DNS zone, TLS	External access enabled
6. Configure	Apply tenant-specific configuration	Custom settings active
7. Verify	Health check all deployed services	All services healthy
8. Activate	Mark tenant as active	Tenant ready for users

Per-Tenant Resources

Each tenant receives its own set of isolated resources:

Resource	Isolation Method	Example
Kubernetes namespace	Dedicated namespace	`matih-data-plane-acme-corp`
Database schemas	Schema-per-tenant	`acme_corp` schema in PostgreSQL
DNS zone	Child zone per tenant	`acme.matih.ai`
TLS certificate	Per-tenant cert via cert-manager	Wildcard for tenant domain
NGINX ingress controller	Dedicated per namespace	Own LoadBalancer IP
Redis key namespace	Tenant-prefixed keys	`acme-corp:service:key`
Kafka partitioning	Tenant ID as message key	Ordering within tenant stream
Resource quotas	Per-namespace quotas	CPU, memory, pod limits

Tenant Context Propagation

The tenant context flows through every layer of the request processing chain:

1. Browser sends request with JWT token
   Authorization: Bearer <token with tenant_id claim>

2. Kong Gateway validates JWT and extracts tenant_id
   Adds header: X-Tenant-ID: acme-corp

3. Backend service establishes context
   TenantContextHolder.setTenantId("acme-corp")

4. Service layer reads context
   TenantContext.requireCurrentTenantId() --> "acme-corp"

5. Repository layer scopes database queries
   SET search_path TO 'acme_corp';

6. Event publishing includes tenant context
   DataPlaneEvent.tenantId = "acme-corp"
   Kafka message key = "acme-corp"

Resource Quotas by Tier

Tenant tiers determine the resource allocation and feature access:

Tier	CPU Quota	Memory Quota	Max Users	Features
Free	2 cores	4Gi	5	Basic analytics
Professional	8 cores	16Gi	50	Full analytics, AI chat
Enterprise	Custom	Custom	Unlimited	All features, custom models

Security Guarantees

Guarantee	Mechanism
No cross-tenant data access	Schema-per-tenant isolation in PostgreSQL
No cross-namespace communication	Kubernetes NetworkPolicies
No resource starvation	Kubernetes ResourceQuotas per namespace
No cache pollution	Tenant-prefixed Redis keys
No event leakage	Tenant ID as Kafka partition key
No identity spoofing	Tenant ID extracted from server-signed JWT

Architecture: Multi-Tenancy -- Full architectural deep dive
Security: Tenant Isolation -- Security-focused isolation details
Observability -- Per-tenant monitoring

Data Governance Observability