Complete User Management Guide

How Users Invite Team Members

Location: Settings → Team

1. Access Team Management:

• Go to Settings in the main navigation
• Click Team tab
• You'll see all current team members

2. Invite User:

• Click "+ Invite User" button (top right)
• Fill in the invitation form:
• • Email Address (required): The email of the person to invite
  • Name (optional): Their name (can be set during acceptance if not provided)
  • Role (required): Choose from:
  • Member: Standard access
  • Admin: Full access (can manage users)
  • Guest: Read-only access
• Click "Send Invitation"

3. What Happens:

• Invitation record is created in database
• Email is sent to the invited user via UserInvitationNotification
• Invitation link expires in 7 days
• User slot is reserved but not consumed until acceptance

4. User Accepts:

• Invited user clicks link in email
• If new user: Creates account, sets password, joins team
• If existing user: Automatically added to team and logged in
• Invitation is marked as accepted
• User slot is consumed

Alternative: Manual User Creation

Via Artisan Command (for super admins):

php artisan user:assign-to-tenant user@example.com --tenant=1 --role=admin

CRUD Implementation Status

✅ User CRUD - FULLY IMPLEMENTED

Create (Invite):

• ✅ TeamManagement::inviteUser() - Creates invitation
• ✅ InvitationController::accept() - Creates user account
• ✅ Email notification sent

Read (View):

• ✅ TeamManagement component displays all team members
• ✅ Search functionality
• ✅ Pagination support
• ✅ Shows roles, join dates, email addresses

Update:

• ✅ TeamManagement::updateUser() - Updates name and role
• ✅ Modal-based edit form
• ✅ Role can be changed
• ✅ Name can be updated

Delete (Remove):

• ✅ TeamManagement::removeUser() - Removes user from tenant
• ✅ TenantService::removeUserFromTenant() - Detaches user
• ✅ User slot is freed up

✅ Invitation CRUD - FULLY IMPLEMENTED

Create:

• ✅ UserInvitation::createInvitation() - Static factory method
• ✅ TeamManagement::inviteUser() - Creates invitation

Read:

• ✅ TeamManagement::pendingInvitations - Shows pending invitations
• ✅ InvitationController::showAcceptForm() - Displays acceptance form

Update:

• ✅ resendInvitation() - Resends invitation email
• ✅ Invitation can be accepted (updates accepted_at)

Delete:

• ✅ cancelInvitation() - Deletes invitation

⚠️ Role/Permission CRUD - PARTIALLY IMPLEMENTED

Read:

• ✅ Roles exist in database via RolePermissionSeeder
• ✅ Permissions exist in database
• ✅ RoleManager component displays roles (basic)
• ✅ HasTenantRoles trait provides role/permission checks

Create/Update/Delete:

• ⚠️ RoleManager component exists but seems basic (needs review)
• ⚠️ No visible UI for creating custom roles
• ⚠️ No visible UI for managing permissions per role
• ✅ Roles can be assigned to users via assignTenantRole()
• ✅ Permissions can be assigned via givePermissionTo()

Current Roles:

• owner - Full tenant access
• admin - Nearly full access
• member - Standard access
• guest - Read-only access

Recommendation:

Consider enhancing RoleManager component to allow:

• Creating custom roles
• Assigning permissions to roles
• Managing permissions per role
• UI for role/permission CRUD

Where and How Users Are Managed

Primary Location: Settings → Team

Features Available:

• View all team members
• Invite new users
• Edit user roles
• Remove users
• View pending invitations
• Resend/cancel invitations
• Search team members
• See available user slots

Access Control

Who Can Manage Users:

• Owner: Full access to manage team
• Admin: Can invite and manage users
• Member: Cannot manage team (403 error)
• Guest: Cannot manage team (403 error)

Permission Check:

// In TeamManagement::mount()
$role = $user->getTenantRole($tenant);
if (!in_array($role, ['owner', 'admin'])) {
    abort(403, 'You do not have permission to manage team members.');
}

Super Admin Panel: /admin

Super Admins can:

• View all users across all tenants
• View all tenants
• Manage resellers
• Set super admin status
• Impersonate tenants for support

Location: https://dashboard.swellsystem.com/admin

Role Assignment and Permission System

How Roles Work

Role Assignment:

1. During Invitation: Role is selected when inviting user
2. After Invitation: Role is stored in tenant_user pivot table
3. Via Code: Can assign via $user->assignTenantRole('admin')

Role Storage:

• Pivot Table: tenant_user.role column stores tenant-specific role
• Spatie Permission: Roles can also be stored in model_has_roles (tenant-scoped)

Example Roles:

• owner - Tenant creator, cannot be changed
• admin - Full access within tenant
• member - Standard user access
• guest - Read-only access

How Permissions Work

Permission System:

• Uses Spatie Laravel Permission with tenant scoping
• Permissions are tenant-scoped (via team_id)
• Roles have permissions attached
• Users inherit permissions through roles

Checking Permissions:

In Code:

// Check permission
if (!$user->hasTenantPermission('crm.create')) {
    abort(403, 'You do not have permission.');
}

// Check role
if (!$user->hasTenantRole('admin')) {
    abort(403, 'You must be an admin.');
}

In Middleware:

Route::middleware(['auth', 'permission:crm.create'])->group(function () {
    // Protected routes
});

In Views:

@can('crm.create')
    <button>Create Contact</button>
@endcan

@role('admin')
    <a href="/settings">Settings</a>
@endrole

Permission Structure

Format: {module}.{action}

Examples:

• crm.view - View CRM records
• crm.create - Create CRM records
• crm.edit - Edit CRM records
• crm.delete - Delete CRM records
• projects.view - View projects
• finance.approve - Approve financial transactions
• tenant.users.manage - Manage team members
• tenant.settings.edit - Edit tenant settings

Default Permissions by Role

Owner:

• All permissions for all modules
• Tenant management permissions

Admin:

• Most permissions (typically excludes billing)
• User management permissions
• Settings management

Member:

• View permissions for active modules
• Create/edit permissions for own records
• Limited delete permissions

Guest:

• View permissions only
• No create/edit/delete permissions

Billing Impact

User Limits

User limits are enforced based on your subscription plan:

During Trial:

• Business plan limits apply (25 users)
• No billing until trial ends
• Full access during trial period

Adding Users

Before Limit:

• No additional charge
• User is added immediately
• No billing impact

At Limit:

• Cannot invite more users
• Error message: "Cannot invite user. Plan allows X users."
• Options:

1. Purchase User Add-Ons: Settings → Billing → Add-Ons → User Add-Ons
2. Upgrade Plan: Upgrade to higher tier

User Add-Ons:

• Charged monthly on your billing cycle
• Prorated if purchased mid-cycle
• Add to your base user limit

Example:

• Professional plan (10 users)
• Purchase 5 user add-ons ($6/user = $30/month)
• Total capacity: 15 users
• Monthly charge: Base plan + $30

Removing Users

User Slot Freed:

• When user is removed, their slot becomes immediately available
• Can invite new user to fill the slot
• Note: User add-on subscriptions are NOT automatically cancelled
• You must manually cancel add-on if removing users permanently

Best Practice:

• Remove users before billing cycle ends
• Cancel user add-on subscription if removing permanently
• Prevents charges for unused add-on slots

Billing Integration

Automatic Checks:

• Tenant::canAddUser() checks limits before adding
• Includes add-on count in calculation: limit + addonCount
• Throws exception if limit reached

Add-On Purchase:

• Go to Settings → Billing
• Click "Add-Ons" → "User Add-Ons"
• Enter quantity
• Complete Stripe checkout
• Add-ons added to user_addons_count field
• Limit updated immediately

Notifications

When Invitations Are Sent

Email Notification:

• UserInvitationNotification sent immediately
• Queued (sent in background via Laravel queues)
• Includes:
• Invitation link (unique token, expires in 7 days)
• Company name
• Inviter's name
• Assigned role
• Expiration date

Delivery Channels:

• Email only (via via() method returning ['mail'])

Notification Template:

• Subject: "You've been invited to join {Company} on SWELLEnterprise"
• Greeting: Personalized with inviter's name
• Action button: "Accept Invitation" (links to /invitations/accept/{token})
• Expiration notice

When Users Join

Current Implementation:

• No automatic notifications sent when invitation is accepted
• Business owner is NOT notified when user accepts
• Team members are NOT notified when new members join

Optional Enhancement:

You could add:

• UserAddedNotification when user accepts invitation
• TeamMemberJoinedNotification to notify team members
• Implement via observers or in InvitationController::accept()

Notification System

Laravel Notifications:

• Uses Laravel's notification system
• Queued for performance
• Respects tenant SMTP settings if configured

Channels Available:

• Email (current)
• Database (can be enabled)
• Push notifications (if configured)

Summary: Business Owner Workflow

Scenario: Inviting Your Team

As a business owner, here's the complete workflow:

1. Check Your Plan:

• Go to Settings → Billing
• See your current plan and user limit
• Check current user count

2. Plan for Growth:

• If near limit, purchase add-ons or upgrade
• User add-ons: $4-8/user/month (depending on plan)
• Upgrading plan gives you more included users

3. Invite Team Members:

• Go to Settings → Team
• Click "+ Invite User"
• Enter email, name (optional), and role
• Click "Send Invitation"
• User receives email immediately

4. Assign Roles:

• Owner: Yourself (assigned during registration)
• Admin: Managers who need full access
• Member: Regular team members
• Guest: Clients/consultants who need read-only access

5. Manage Permissions:

• Roles control what users can do
• Permissions are inherited through roles
• Can customize permissions per role (via code or role manager)

6. Monitor Team:

• View all team members in Settings → Team
• See pending invitations
• Edit roles as needed
• Remove users who leave

7. Handle Billing:

• When at limit, purchase add-ons or upgrade
• User slots are freed when users are removed
• Monitor usage vs. plan limits

Impact on Paid Plan

Adding Users:

• No charge if within plan limit
• Additional charge if purchasing add-ons ($4-8/user/month)
• Upgrade plan for higher included user count

Removing Users:

• User slot freed immediately
• Can add new user to fill slot
• Important: Cancel user add-on subscription if not replacing user

Trial Period:

• Business plan limits apply (25 users)
• No billing until trial ends
• Full access during trial

Access Control Examples

Example 1: Member Can Only View CRM

Goal: Team member should view CRM but not create/edit.

Setup:

1. Invite user with "Member" role
2. Customize member role permissions:

   $memberRole = Role::findByName('member');
   $memberRole->revokePermissionTo('crm.create');
   $memberRole->revokePermissionTo('crm.edit');
   $memberRole->givePermissionTo('crm.view');

Result:

• User can view contacts/companies/leads
• Cannot create, edit, or delete
• Access controlled via permissions

Example 2: Guest for Read-Only Projects Access

Goal: Client can view projects but not modify.

Setup:

1. Invite user with "Guest" role
2. Ensure guest role has projects.view permission
3. Revoke all create/edit/delete permissions

Result:

• Guest can view projects
• Cannot create tasks or edit projects
• Read-only access enforced

Example 3: Admin with Limited Modules

Goal: Manager should manage users but only access CRM.

Setup:

1. Invite user with "Admin" role
2. Customize admin permissions:

   $adminRole = Role::findByName('admin');
   // Remove project/finance permissions
   $adminRole->revokePermissionTo(['projects.view', 'finance.view']);
   // Keep CRM and user management
   $adminRole->givePermissionTo(['crm.view', 'crm.create', 'crm.edit', 'tenant.users.manage']);

Result:

• Admin can manage users and CRM
• Cannot access projects or finance modules
• Permissions restrict module access

CRUD Capabilities Summary

✅ Implemented

1. User Invitations: Full CRUD
2. User Management: Full CRUD (via TeamManagement component)
3. Role Assignment: Can assign roles when inviting and when editing users
4. Permission System: Spatie Permission with tenant scoping
5. Billing Integration: User limits enforced, add-ons supported
6. Notifications: Invitation emails sent automatically

⚠️ Partially Implemented

1. Role Management: Basic RoleManager component exists but may need enhancement
2. Permission UI: No visible UI for managing permissions per role (can be done via code)

Recommended Enhancements

1. Role Manager UI: Full CRUD interface for creating/editing roles
2. Permission Assignment: UI for assigning permissions to roles
3. Join Notifications: Notify owner/admins when users accept invitations
4. User Activity: Track when users were added/removed/role changed

Next Steps

For business owners wanting to invite their team:

1. Review Your Plan: Check user limit in Settings → Billing
2. Invite Team: Go to Settings → Team → Invite User
3. Assign Roles: Choose appropriate roles (Member, Admin, Guest)
4. Monitor Usage: Track user count vs. plan limit
5. Manage as Needed: Edit roles or remove users as team changes

For developers wanting to enhance the system:

1. Role Manager: Enhance RoleManager component for full CRUD
2. Permission UI: Add UI for managing permissions per role
3. Notifications: Add join notifications
4. Activity Log: Track user management actions

For more information:

• Team Management
• Billing & Subscriptions
• User Invitations & Roles

Updated on: 13/03/2026