List Files | Just Commands | Repo | Logs

← back | Copy

# Multi-Organization Membership System

## Overview

This document describes the behavior and architecture of multi-organization membership in the pricebook platform, as discovered through testing issue #53: "Make sure user can join multiple orgs via invite links".

## Key Insights

### 1. ActiveOrg-Based Visibility Model

The system implements **"active organization switching"** rather than simultaneous multi-organization access. Users can join multiple organizations but can only interact with one organization context at a time.

**Key Behavior:**
- Users have an `activeOrg` field that determines their current organizational context
- When a user joins a new organization, their `activeOrg` is automatically updated to the most recently joined organization
- Users can only see profiles, roles, and data from their currently active organization

### 2. Permission Model

The profile collection uses strict permission rules that enforce activeOrg-based access:

```javascript
"listRule": "@request.auth.id != \"\" && org.id = @request.auth.activeOrg"
```

**Implications:**
- Users can only list profiles from organizations where `org.id = @request.auth.activeOrg`
- Organization owners can only see users whose `activeOrg` matches their organization
- Cross-organization visibility is not possible without switching active organization

### 3. Profile Persistence Architecture

**Data Model:**
- Users maintain separate `profile` records in each organization they join
- Each profile links: `user` → `organization` and contains organization-specific `roles`
- Profile records persist even when a user's `activeOrg` changes
- Roles are assigned per-profile, allowing different roles in different organizations

**Workflow:**
1. User joins Organization A via invite link → `activeOrg` = A, profile created in A
2. User joins Organization B via invite link → `activeOrg` = B, profile created in B
3. User can only interact with Organization B data (current `activeOrg`)
4. Organization A owner cannot see user in their profiles list (user's `activeOrg` ≠ A)

## Testing Results

### Test Coverage: `multipleOrgMembership.js`

✅ **User Registration & Organization Creation**
- Test user and organization owners can register successfully
- Multiple organizations can be created by different owners

✅ **Invite Link Functionality**
- Users can join multiple organizations via `/organization/:id/join` URLs
- Each join creates a separate profile record
- `activeOrg` field updates to most recently joined organization

✅ **Profile Visibility Rules**
- Users see only profiles from their active organization
- Organization owners see only users whose `activeOrg` matches their organization
- Profile isolation works correctly across organizations

✅ **Role Management**
- Users can be assigned different roles in different organizations
- Roles are maintained separately per organization profile
- Role assignment only works within the user's active organization context

## Architectural Implications

### For User Experience
- Users need to "switch" active organizations to interact with different org contexts
- No simultaneous cross-organization data access
- Organization switching mechanism would be required for full multi-org workflow

### For Development
- UI components should respect activeOrg context
- API calls are automatically scoped to user's active organization
- Cross-organization operations require activeOrg switching

### For Organization Management
- Organization admins can only manage users who are "active" in their organization
- Users who join other organizations may become "invisible" to previous org admins
- Role assignments and permissions are contextual to active organization

## Related Issues

- **Issue #53**: "Make sure user can join multiple orgs via invite links" ✅ **RESOLVED**
- **Issue #54**: "User should be able to switch active org" - Required for full multi-org UX
- **Issue #52**: "Admin should be able to add users to an organization" - Works within activeOrg constraints

## Test Files

- **Test Implementation**: `tests/api-e2e/multipleOrgMembership.js`
- **Common API Functions**: `tests/api-e2e/common.js` (updated with proper `this.pb` references)

---

*Last Updated: 2025-09-16*
*Test Status: All core multi-organization membership scenarios passing ✅*