Multi-User Spaces Architecture

Overview

Spaces now support multi-user collaboration with granular role-based access control (RBAC). This enables teams and organizations to work together in shared workspaces while maintaining security and proper permission boundaries.

🎯 Core Concepts

Space Types

1. Personal Space (Default)

   • Owned by a single user
   • No additional members
   • All operations allowed for owner

2. Team Space

   • Shared among team members
   • Multiple users with different roles
   • Collaborative workspace for small teams

3. Organization Space

   • Enterprise-level workspace
   • Can be linked to an organization entity
   • Supports billing, analytics, and advanced management

👥 Roles & Permissions

Predefined Roles

Owner

• Full Control: Can do everything
• Can delete the space
• Can manage billing (future feature)
• Can invite/remove any user
• Cannot be removed or have role changed

Admin

• Can manage universes, pages, and flows
• Can invite and remove users
• Can change space settings
• Cannot: Manage billing or delete space

Editor

• Can create and edit content
• Can create universes, pages, and flows
• Can deploy universes
• Cannot: Delete universes, invite users, or change settings

Contributor

• Can edit existing content
• Cannot: Create new universes or deploy
• Limited to content editing only

Viewer

• Read-only access
• Can view all content
• Cannot: Make any changes

Permission Matrix

📦 Data Structure

Space Interface

interface Space {
  id: string;
  name: string;
  ownerId: string; // Primary owner/creator
  spaceSlug: string;

  // Multi-user support
  members?: SpaceMember[];
  organizationId?: string;
  type?: 'personal' | 'team' | 'organization';

  // ... other properties
}

Space Member Interface

interface SpaceMember {
  userId: string;
  email: string;
  displayName?: string;
  role: SpaceRole;
  permissions: SpacePermissions;
  joinedAt: Date | string;
  invitedBy: string;
  status: 'active' | 'pending' | 'suspended';
}

Space Permissions Interface

interface SpacePermissions {
  // Universe management
  canCreateUniverse: boolean;
  canEditUniverse: boolean;
  canDeleteUniverse: boolean;
  canDeployUniverse: boolean;

  // Content management
  canCreatePages: boolean;
  canEditPages: boolean;
  canDeletePages: boolean;
  canCreateFlows: boolean;
  canEditFlows: boolean;
  canDeleteFlows: boolean;

  // Space management
  canInviteUsers: boolean;
  canRemoveUsers: boolean;
  canChangeSettings: boolean;
  canManageBilling: boolean;
  canDeleteSpace: boolean;

  // Access level
  canViewAnalytics: boolean;
  canExportData: boolean;
}

🛠️ Usage Examples

Check User Permissions

import { hasPermission, getUserRole } from '@libs-foundational/core-models';

// Check if user can create a universe
if (hasPermission(space, userId, 'canCreateUniverse')) {
  // User can create universe
  await createUniverse(...);
}

// Get user's role
const role = getUserRole(space, userId);
console.log(`User role: ${role}`); // 'owner', 'admin', 'editor', etc.

Invite a New Member

import { createSpaceMember } from '@libs-foundational/core-models';

// Create a new member with admin role
const newMember = createSpaceMember(
  'user-123',
  '[email protected]',
  'admin',
  currentUserId,
  'John Doe'
);

// Add to space
space.members = [...(space.members || []), newMember];
await saveSpace(space);

Update Member Role

import { updateMemberRole } from '@libs-foundational/core-models';

// Find member and update their role
const member = space.members?.find(m => m.userId === targetUserId);
if (member) {
  const updatedMember = updateMemberRole(member, 'editor');
  
  // Replace in members array
  space.members = space.members?.map(m => 
    m.userId === targetUserId ? updatedMember : m
  );
  
  await saveSpace(space);
}

Guard Routes with Permissions

import { canPerformAction } from '@libs-foundational/core-models';

// In a route guard
canActivate(route: ActivatedRouteSnapshot): boolean {
  const space = this.spaceService.currentSpace();
  const userId = this.authService.currentUserId();
  
  // Check if user can deploy universes
  if (!canPerformAction(space, userId, 'canDeployUniverse')) {
    this.router.navigate(['/unauthorized']);
    return false;
  }
  
  return true;
}

🔮 Future Enhancements

Phase 1 (Current)

• ✅ Basic role-based access control
• ✅ Permission checking utilities
• ✅ Owner/Admin/Editor/Contributor/Viewer roles

Phase 2 (Next)

• Custom roles with custom permissions
• Permission inheritance (space → universe → page)
• Audit logs for permission changes

Phase 3 (Future)

• Organization management
• Billing integration based on team size
• Activity tracking per user
• Team analytics and insights

Phase 4 (Advanced)

• Advanced permission policies (IP restrictions, time-based access)
• OAuth/SAML integration for enterprise SSO
• Automated user provisioning
• Advanced team workflows

🎯 Best Practices

1. Always Check Permissions: Before allowing any destructive operation, check user permissions
2. Use Default Roles: Start with predefined roles for consistency
3. Audit Changes: Log when permissions or roles are changed
4. Clear Communication: Show users what they can/cannot do in the UI
5. Graceful Degradation: Hide features users don't have access to rather than showing error messages

🔒 Security Considerations

1. Owner is Immutable: Space owner cannot be changed or removed
2. Permission Hierarchy: Admins cannot have more permissions than owner
3. Pending Status: New members start as "pending" until they accept the invitation
4. Suspended Access: Members can be suspended without being removed
5. Billing Protection: Only owner can manage billing to prevent unauthorized changes

📚 Related Documentation

• Space Architecture
• User Authentication (to be created)
• Organization Management (to be created)