Skip to content

Role-Based Permission System Implementation Summary

✅ What's Been Implemented

Backend (Already Exists)

  1. Database Schema
  2. permissions table - stores all available permissions
  3. roles table - team-specific roles with editable flag
  4. role_permissions junction table - many-to-many relationship

  5. Migration file: 2025_12_17_0002_seed_permissions_catalog.py

  6. Default Permissions Seeded

  7. * - All permissions (wildcard)
  8. team.manage - Manage team settings and roles
  9. team.invite - Invite team members
  10. events:read - Read SSE events
  11. billing.view - View billing
  12. billing.edit - Edit billing
  13. server.create - Create server
  14. server.restart - Restart server

  15. server.delete - Delete server

  16. Default Roles Created per Team

  17. Owner (not editable): Has * permission
  18. Manager (editable): Has team., billing., server.*, events:read

  19. Developer (editable): Has server.*, events:read

  20. API Endpoints

  21. GET /api/v1/rbac/permissions - List all permissions
  22. GET /api/v1/rbac/teams/{teamId}/roles - List team roles
  23. POST /api/v1/rbac/teams/{teamId}/roles - Create custom role
  24. PATCH /api/v1/rbac/teams/{teamId}/roles/{roleId} - Update role metadata
  25. PUT /api/v1/rbac/teams/{teamId}/roles/{roleId}/permissions - Update role permissions
  26. DELETE /api/v1/rbac/teams/{teamId}/roles/{roleId} - Delete role

  27. PUT /api/v1/rbac/teams/{teamId}/members/{userId}/role - Assign role to member

  28. Security Features

  29. Automatic session revocation when permissions change
  30. Owner role protection (cannot be edited/deleted)
  31. In-use role protection (cannot delete roles assigned to members)
  32. Cross-tenant access prevention

Frontend (Newly Created)

  1. Type Definitions (frontend/src/features/teams/types/team.types.ts) 

    interface Permission {
  slug: string;
  description: string;
}

interface Role {
  id: number;
  team_id: number;
  name: string;
  description: string | null;
  is_editable: boolean;
  permissions: string[];
}

const DEFAULT_ROLE_PERMISSIONS = {
  Owner: ['*'],
  Manager: [...],
  Developer: [...]
}

  2. Service Methods (frontend/src/features/teams/services/teamService.ts)

  3. getPermissions() - Fetch all available permissions
  4. getRoles(teamId) - Fetch team roles
  5. createRole(teamId, name, description, permissionSlugs) - Create custom role
  6. updateRolePermissions(teamId, roleId, permissionSlugs) - Update permissions
  7. deleteRole(teamId, roleId) - Delete role

  8. assignMemberRole(teamId, userId, roleId) - Assign role to member

  9. RoleManagement Component (frontend/src/features/teams/components/RoleManagement.tsx)

Features: - Grid display of all team roles - Role cards showing name, description, and first 3 permissions - Hover tooltip showing ALL permissions with descriptions - Visual badges for "System" and "Default" roles - "Create Custom Role" button (only for users with team.manage permission)

Create Role Dialog: - Name and description fields - Grouped permission checkboxes by category (team, billing, server, events) - Select All / Deselect All buttons - Permission counter - Validation (name required, at least one permission)

Edit Permissions Dialog: - Same checkbox interface as create - Pre-selected with current role permissions - Only available for editable roles

Role Card Actions: - "Edit Permissions" button (for editable roles) - "Delete" button with confirmation (for editable roles) - Actions hidden for system roles and non-managers

📋 How to Use

1. Import the Component

import { RoleManagement } from '@/features/teams/components';

2. Use in Your Page

function TeamSettingsPage() {
  const user = useCurrentUser(); // Your auth hook

  return (
    <RoleManagement
      teamId={user.team_id}
      currentUserPermissions={user.permissions}
    />
  );
}

3. Permission Requirements

  • View roles: Any team member
  • Create/Edit/Delete roles: team.manage or * permission

🎨 UI Features

Role Card Display

  • Name with system/default badges
  • Description text
  • First 3 permissions as chips
  • "+X more" indicator

Hover Tooltip

  • Shows complete permission list
  • Permission name formatted (e.g., "Server Create")
  • Permission description
  • Dark theme with arrow pointer
  • Scrollable for long lists

Dialogs

  • Full-screen overlay
  • Responsive design
  • Category-grouped permissions
  • Real-time validation
  • Error handling with user feedback

🔒 Security Notes

  1. Permissions from Database: All permissions are stored in and fetched from the database (not hardcoded)

  2. Default Roles on Team Creation: When a new team is created, the backend automatically seeds Owner, Manager, and Developer roles

  3. Session Security: Changing role permissions automatically revokes all sessions for affected users

  4. Protected Roles: Owner role cannot be modified or deleted

  5. In-Use Protection: Roles assigned to members cannot be deleted

📁 Files Modified/Created

Created:

  • ✅ frontend/src/features/teams/components/RoleManagement.tsx - Main component
  • ✅ frontend/src/features/teams/components/index.ts - Export barrel
  • ✅ frontend/src/app/team-settings/roles/page.example.tsx - Usage example
  • ✅ This summary file

Modified:

  • ✅ frontend/src/features/teams/types/team.types.ts - Added Permission interface
  • ✅ frontend/src/features/teams/services/teamService.ts - Added RBAC methods
  • ✅ docs/architecture/team_management.md - Updated TDD with implementation guide

Already Existed (Backend):

  • ✅ backend/app/infrastructure/database/models/rbac.py - Models
  • ✅ backend/app/modules/rbac/router.py - API endpoints
  • ✅ backend/app/modules/rbac/service.py - Business logic
  • ✅ backend/app/modules/rbac/schemas.py - Pydantic schemas
  • ✅ backend/app/infrastructure/database/migrations/versions/2025_12_17_0002_seed_permissions_catalog.py - Permission seeding

🚀 Next Steps

  1. Integrate into Team Settings Page: 

    // In your team settings page
import { RoleManagement } from '@/features/teams/components';

<RoleManagement
  teamId={currentTeamId}
  currentUserPermissions={currentUserPermissions}
/>

  2. Add to Navigation: Add a "Roles & Permissions" link in your team settings sidebar

  3. Customize Styling: The component uses Tailwind classes - adjust colors to match your design system

  4. Add More Permissions: Update the migration file to add new permissions as your app grows

❓ FAQ

Q: Where are permissions stored? A: In the permissions database table, seeded via Alembic migration.

Q: Can I add more permissions later? A: Yes! Create a new Alembic migration to insert additional permissions.

Q: How do I show default permissions on hover? A: The component automatically shows all permissions in a tooltip when you hover over any role card.

Q: Can users create completely custom roles? A: Yes! Users with team.manage permission can create custom roles with any combination of permissions (except the wildcard *).

Q: What happens to users when I change role permissions? A: Their sessions are automatically revoked, forcing them to re-authenticate with the new permissions.

Q: Can I edit the Owner role? A: No, the Owner role is system-protected and cannot be edited or deleted.