# 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