Multi-Tenancy

Goal

Build a multi-tenant system where each company's data is completely isolated from others, while allowing users to belong to multiple tenants.

Isolation Strategy

• Shared database with row-level isolation (not database-per-tenant)
• tenantId column on every tenant-specific table
• Every query filters by tenantId - no exceptions
• Zero cross-tenant data access - enforced at repository level

Three-Level Hierarchy

User-Tenant Relationship

• Users exist globally (single account across platform)
• Users connect to tenants via UserTenant join table
• Users can belong to multiple tenants (e.g., consultant working for multiple companies)
• Users switch between tenants via tenant selector

Security Rules

1. Every table (except Tenant) has tenantId column

   Note: User.tenantId is optional because Auth.js PrismaAdapter creates the user record before the createUser event fires to assign tenant context. See Phase 01 for details.

2. Every repository method takes tenantId as first parameter
3. Every query includes WHERE tenantId = ?
4. AuthGuard verifies user has access to requested tenant
5. Session includes current tenantId and systemRole context (enriched via Auth.js session callback)
6. Audit logging tracks all tenant-scoped operations

Key Implementation Points

• Tenant context extracted from JWT in AuthGuard
• Repository methods enforce tenant filtering
• Platform admins can impersonate tenants for support
• Tenant deletion cascades all related data

---

Implementation details to be defined during development