Guild Roles & Permissions System

Overview

The guild platform supports two types of roles:

1. WoW-Synced Roles (Blizzard guilds only) - Automatically imported from WoW with wowRank (0-9)
2. Custom Roles (All guilds) - User-created organizational roles with wowRank = null

Every WoW guild configures rank permissions differently! This system allows you to mirror your guild's specific permission setup within the app.

How It Works

WoW-Synced Roles (Blizzard Guilds)

For guilds synced from Battle.net, roles are automatically imported with WoW rank numbers:

Rank	Default Permissions	Immutable
0 (Guild Master)	Full control (always enabled)	Yes
1 (Top Officer)	Can manage guild settings, members, and events	No
2 (Officer)	Can manage members and events (not guild settings)	No
3-9 (Members)	Read-only access	No

Important:

• WoW-synced roles cannot be deleted
• wowRank cannot be changed (tied to Blizzard API data)
• Permissions can be customized to match your guild setup
• Guild Master (rank 0) permissions are always enforced and cannot be disabled

Custom Roles (Standalone Guilds Only)

Standalone (non-synced) guilds can create custom roles to build their own rank structure:

• Purpose: Organize members by activity, responsibility, or team
• No WoW Rank: Custom roles always have wowRank = null
• Fully Manageable: Can be created, edited, and deleted freely
• Example Uses: "Raid Team A", "Mythic+ Pushers", "Social Members", "Alt Characters"

How to Create:

1. Go to your guild page
2. Click the Ranks tab
3. Click Create Custom Role
4. Set name and permissions
5. Assign members to the role

Blizzard-synced guilds

In-game synced guilds cannot create custom roles. Their role list is determined entirely by the WoW rank structure (ranks 0–9) synced from Battle.net. Officers can still customize permissions on each synced rank.

Customizing Permissions

After roles are created (synced or custom), customize permissions to match your guild's structure:

1. Go to Ranks tab
2. Click Manage Role or Permissions button
3. Toggle permissions to match your needs
4. Save changes

Available Permissions

Guild Management

• Update guild settings (roster privacy, etc.)
• Edit rank names
• Manage role permissions

Typical usage: Rank 0-1 only

Member Management

• Invite new members
• Kick members
• View full roster (regardless of privacy settings)

Typical usage: Ranks 0-2 (officers), but varies by guild

Event Management

• Create guild events/raids
• Update event details
• Delete events

Typical usage: Ranks 0-2 (officers), but some guilds give this to raid leaders

Example Usage Scenarios

Scenario 1: WoW Guild - Relaxed Recruiting

Your WoW guild lets all raiders (rank 3) invite friends:

1. Go to Ranks tab
2. Find "Raider" (rank 3) → Click Manage Role
3. Enable "Member Management" permission
4. Save

Now rank 3 members can invite in the app, matching your WoW setup.

Scenario 2: Standalone Guild - Custom Raid Team Role

Create a custom role for your progression raid team (standalone guilds only):

1. Click Create Custom Role
2. Name: "Mythic Raid Team"
3. Enable "Event Management" (so they can organize their own raid events)
4. Save
5. Assign your mythic raiders to this role

Now your raid team has event management permissions regardless of rank.

Scenario 3: Standalone Guild - Department Structure

Organize a standalone guild by departments:

1. Create roles: "PvP Team", "Mythic+ Group", "Achievement Hunters", "Casuals"
2. Assign appropriate permissions (e.g., PvP Team gets event management)
3. Assign members to multiple roles as needed

Custom roles let you organize beyond WoW's 10-rank limitation.

Scenario 4: Standalone Guild - Alt Character Organization

Create a custom "Alt Characters" role:

1. Create custom role: "Alt Characters"
2. Set permissions to read-only (no management abilities)
3. Assign all alt characters to this role
4. Main characters keep their primary rank roles

This keeps your roster organized while preserving rank structure.

Best Practices

When to Create Custom Roles

• ✅ Organizing raid teams or PvP groups
• ✅ Tracking alt characters
• ✅ Assigning temporary responsibilities (e.g., "Event Coordinator")
• ✅ Cross-rank activities (members from multiple ranks working together)
• ✅ Standalone guilds (all roles are custom)

When to Update Permissions

• ✅ You change rank permissions in WoW (update synced role permissions)
• ✅ You restructure your officer hierarchy
• ✅ Creating new custom roles for specific activities
• ✅ Adjusting permissions based on trust/activity level

Important Rules

Cannot Do:

• ❌ Delete WoW-synced roles (they're tied to in-game data)
• ❌ Change wowRank of synced roles (immutable)
• ❌ Assign wowRank to custom roles (custom = no rank)
• ❌ Delete roles with active members assigned
• ❌ Disable Guild Master (rank 0) permissions
• ❌ Create custom roles in Blizzard-synced guilds (roles are managed in-game)

Can Do:

• ✅ Create custom roles in standalone guilds
• ✅ Assign members to multiple roles (standalone guilds)
• ✅ Delete custom roles (if no members assigned)
• ✅ Edit role names and permissions anytime
• ✅ Customize WoW-synced role permissions (but not wowRank)

Technical Details

Where Permissions Are Stored

Permissions are stored in Role.permissions (JSONB field in database):

{
  "canManageGuild": true,
  "canManageMembers": true,
  "canManageEvents": false,
  "canViewAttendance": true
}

How CASL Uses Permissions

The AbilityFactory reads these permissions and creates CASL authorization rules:

if (permissions.canManageMembers) {
  can([Action.Invite, Action.Kick], 'Membership');
}

Backend Enforcement

All API endpoints check CASL abilities:

@Patch('guilds/:guildId/roles/:roleId/permissions')
@RequireAbilities({ action: Action.Update, subject: 'Guild' })
updatePermissions() { ... }

So even if someone bypasses the frontend, the backend enforces permissions.

Common Questions

Q: Do I have to set this for every rank? A: No! The defaults work for most guilds. Only customize ranks that differ from the defaults.

Q: Will these permissions affect in-game WoW? A: No. These permissions only apply within this application. They should mirror your WoW guild settings for consistency.

Q: What's the difference between WoW-synced roles and custom roles? A: WoW-synced roles come from Blizzard API with a wowRank (0-9) and cannot be deleted. Custom roles are created by you with wowRank = null and can be freely managed.

Q: Can I give a custom role a WoW rank number? A: No. Custom roles are always wowRank = null. Only Blizzard-synced roles have rank numbers.

Q: What if I make a mistake? A: Just edit the role again. Custom roles can be deleted if needed (as long as no members are assigned).

Q: Can I see what permissions a rank currently has? A: Yes! The Ranks tab shows a summary under the "Permissions" column.

Q: Why can't the app just read permissions from WoW automatically? A: Unfortunately, the Battle.net API doesn't expose guild rank permission flags. We can only see the rank number and name.

Troubleshooting

Problem: A member says they can't do something they should be able to do in-game.

Solution:

1. Check their WoW rank number
2. Go to Ranks → Find that rank
3. Click "Permissions" and verify they match WoW
4. Update if needed

Problem: After re-syncing characters, permissions reset.

Solution: Character sync resets permissions to defaults. After sync, re-apply your customizations using the Permissions Editor.

Future improvement: We could store custom permission profiles and re-apply them after sync.