goplt/docs/content/adr/0025-multitenancy-model.md

ADR-0025: Multi-tenancy Model

Status

Accepted

Context

The platform may need multi-tenancy support for SaaS deployments. Options:

1. Shared database with tenant_id column - Single DB, row-level isolation
2. Schema-per-tenant - Single DB, separate schemas
3. Database-per-tenant - Separate databases

Each has trade-offs for isolation, performance, and operational complexity.

Decision

Use shared database with tenant_id column (optional feature):

1. Model: Single PostgreSQL database with tenant_id column on tenant-scoped tables
2. Isolation: Row-level via Ent interceptors (automatic filtering)
3. Tenant resolution: From header (X-Tenant-ID), subdomain, or JWT claim
4. Optional: Can be disabled for single-tenant deployments

Rationale:

• Simplest operational model (single database)
• Good performance (can index tenant_id)
• Easy to implement (Ent interceptors)
• Can migrate to schema-per-tenant later if needed
• Flexible (can support both single and multi-tenant)

Consequences

Positive

• Simple operations (single database)
• Good performance with proper indexing
• Easy to implement
• Flexible (optional feature)

Negative

• Requires careful query design (ensure tenant_id filtering)
• Data isolation at application level (not database level)
• Potential for data leakage if bugs occur

Implementation Notes

• Make tenant_id optional (nullable) for single-tenant mode
• Add Ent interceptor to automatically filter by tenant_id
• Resolve tenant from context via middleware
• Add tenant_id to JWT claims
• Document tenant isolation guarantees
• Consider adding tenant_id to all tenant-scoped tables