Improve the frontend 4

services/tenant/app/models/tenants.py

@@ -84,15 +84,39 @@ class Tenant(Base):
         return f"<Tenant(id={self.id}, name={self.name})>"
 
 class TenantMember(Base):
-    """Tenant membership model for team access"""
+    """
+    Tenant membership model for team access.
+
+    This model represents TENANT-SPECIFIC roles, which are distinct from global user roles.
+
+    TENANT ROLES (stored here):
+    - owner: Full control of the tenant, can transfer ownership, manage all aspects
+    - admin: Tenant administrator, can manage team members and most operations
+    - member: Standard team member, regular operational access
+    - viewer: Read-only observer, view-only access to tenant data
+
+    ROLE MAPPING TO GLOBAL ROLES:
+    When users are created through tenant management (pilot phase), their tenant role
+    is mapped to a global user role in the Auth service:
+    - tenant 'admin'  → global 'admin'   (system-wide admin access)
+    - tenant 'member' → global 'manager' (management-level access)
+    - tenant 'viewer' → global 'user'    (basic user access)
+    - tenant 'owner'  → No automatic global role (owner is tenant-specific)
+
+    This mapping is implemented in app/api/tenant_members.py lines 68-76.
+
+    Note: user_id is a cross-service reference (no FK) to avoid circular dependencies.
+    User enrichment is handled at the service layer via Auth service calls.
+    """
     __tablename__ = "tenant_members"
-    
+
     id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
     tenant_id = Column(UUID(as_uuid=True), ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False)
     user_id = Column(UUID(as_uuid=True), nullable=False, index=True)  # No FK - cross-service reference
-    
+
     # Role and permissions specific to this tenant
-    role = Column(String(50), default="member")  # owner, admin, member, viewer
+    # Valid values: 'owner', 'admin', 'member', 'viewer'
+    role = Column(String(50), default="member")
     permissions = Column(Text)  # JSON string of permissions
     
     # Status