Improve the frontend 4

frontend/src/types/roles.ts

@@ -1,21 +1,47 @@
 /**
  * Role Types - Must match backend role definitions exactly
+ *
+ * This system uses TWO DISTINCT role systems for fine-grained access control:
+ *
+ * 1. GLOBAL USER ROLES (Auth Service):
+ *    - System-wide permissions across the platform
+ *    - Managed by the Auth service
+ *    - Stored in the User model
+ *    - Used for cross-tenant operations and platform administration
+ *
+ * 2. TENANT-SPECIFIC ROLES (Tenant Service):
+ *    - Organization/tenant-level permissions
+ *    - Managed by the Tenant service
+ *    - Stored in the TenantMember model
+ *    - Used for per-tenant access control and team management
+ *
+ * ROLE MAPPING (Tenant → Global):
+ * When creating users through tenant management, tenant roles are mapped to global roles:
+ *   - tenant 'admin'  → global 'admin'   (full administrative access)
+ *   - tenant 'member' → global 'manager' (management-level access)
+ *   - tenant 'viewer' → global 'user'    (basic user access)
+ *   - tenant 'owner'  → No automatic mapping (owner is tenant-specific)
+ *
+ * This mapping ensures users have appropriate platform-level permissions
+ * that align with their organizational role.
  */
 
 // Global User Roles (Auth Service)
+// Platform-wide roles for system-level access control
 export const GLOBAL_USER_ROLES = {
-  USER: 'user',
-  ADMIN: 'admin',
-  MANAGER: 'manager',
-  SUPER_ADMIN: 'super_admin',
+  USER: 'user',           // Basic authenticated user
+  ADMIN: 'admin',         // System administrator
+  MANAGER: 'manager',     // Mid-level management access
+  SUPER_ADMIN: 'super_admin', // Full platform access
 } as const;
 
 // Tenant-Specific Roles (Tenant Service)
+// Organization-level roles for tenant-scoped operations
 export const TENANT_ROLES = {
-  OWNER: 'owner',
-  ADMIN: 'admin', 
-  MEMBER: 'member',
-  VIEWER: 'viewer',
+  OWNER: 'owner',     // Tenant owner (full control, can transfer ownership)
+  ADMIN: 'admin',     // Tenant administrator (team management, most operations)
+  MEMBER: 'member',   // Standard team member (regular operations)
+  VIEWER: 'viewer',   // Read-only observer (view-only access)
 } as const;
 
 // Combined role types