# Roles & Permissions Analysis

## Project Understanding

**"Business And Birthday"** is a subscription-based membership platform combining business networking (portfolios, rankings, advertising) with birthday celebration rewards for premium Titan members. Features include Paystack payment integration, referral system, content moderation, wallet management, and session tracking with daily hour limits.

---

## Current State

### Existing Roles (5)

| Role | Slug | Purpose |
|------|------|---------|
| Admin | `admin` | Full system access (all 20 permissions) |
| User | `user` | Newly registered — basic navigation + content submission |
| Customer | `customer` | Profile completed — can perform transactions |
| Titan Member | `titan_member` | Premium subscription member — wallet, portfolio, content |
| Content Reviewer | `content_reviewer` | Moderate submitted content |

### Existing Permissions (20)

| # | Permission | Slug | Category |
|---|------------|------|----------|
| 1 | Manage Customers | `manage_customers` | Core System |
| 2 | Manage Users | `manage_users` | Core System |
| 3 | Manage Roles | `manage_roles` | Core System |
| 4 | Manage Permissions | `manage_permissions` | Core System |
| 5 | Manage Transactions | `manage_transactions` | Financial |
| 6 | Perform Transactions | `perform_transactions` | Financial |
| 7 | Navigate Application | `navigate_application` | Core System |
| 8 | View Ledger | `view_ledger` | Financial |
| 9 | Manage Ledger | `manage_ledger` | Financial |
| 10 | Approve Ledger | `approve_ledger` | Financial |
| 11 | View Reports | `view_reports` | Financial |
| 12 | Manage Subscriptions | `manage_subscriptions` | Subscriptions |
| 13 | Review Content | `review_content` | Content |
| 14 | Manage Portfolios | `manage_portfolios` | Portfolios |
| 15 | Manage Birthday Rewards | `manage_birthday_rewards` | Birthdays |
| 16 | Manage Ads | `manage_ads` | Ads |
| 17 | View Member Rankings | `view_member_rankings` | Rankings |
| 18 | View Wallet | `view_wallet` | Wallet |
| 19 | Submit Content | `submit_content` | Content |
| 20 | Manage Own Portfolio | `manage_own_portfolio` | Portfolios |

---

## Recommended New Roles (3 additional)

### 1. `super_admin`
- **Purpose:** Complete system ownership — can manage other admins, access audit logs, configure system-wide settings. Protected from deletion.
- **Why needed:** Currently any `admin` can delete/disable other admins via `manage_users`. Super admin provides a safety layer above regular admins.
- **Key difference from admin:** Has `manage_system_settings` which admin does not. Cannot be deleted or deactivated by regular admins.

### 2. `moderator`
- **Purpose:** Mid-level administrative user who handles day-to-day community management — users, content, portfolios, ads.
- **Why needed:** The current `content_reviewer` role is too narrow. Moderators handle user management, content moderation, portfolio approvals, and ad oversight without access to roles/permissions/system config.

### 3. `accountant` / `finance`
- **Purpose:** View financial data — transactions, ledgers, subscription revenue, reports — without system management capabilities.
- **Why needed:** Separates financial visibility from full admin access. An accountant can view `manage_transactions`, `view_ledger`, `view_reports`, `view_subscription_analytics` without being able to manage users or system settings.

---

## Recommended New Permissions (10 additional)

| # | Permission | Slug | Category | Description |
|---|------------|------|----------|-------------|
| 1 | Manage Own Ads | `manage_own_ads` | Ads | Users create/edit/delete their own advertisements |
| 2 | View Birthday Eligibility | `view_birthday_eligibility` | Birthdays | Users check their own birthday reward eligibility |
| 3 | View Birthday Analytics | `view_birthday_analytics` | Birthdays | Admin view of birthday reward statistics |
| 4 | Manage Referral Programs | `manage_referral_programs` | Referrals | Configure referral rewards and programs |
| 5 | View Referral Analytics | `view_referral_analytics` | Referrals | View referral statistics and top referrers |
| 6 | Export Data | `export_data` | System | Export users, transactions, reports |
| 7 | View Audit Logs | `view_audit_logs` | System | Access system activity/audit trail |
| 8 | Manage System Settings | `manage_system_settings` | System | Configure app-wide settings (super_admin only) |
| 9 | View Subscription Analytics | `view_subscription_analytics` | Subscriptions | View subscription revenue and plan distribution |
| 10 | Manage Sessions | `manage_sessions` | Sessions | Force-terminate user sessions |
| 11 | Manage Notifications | `manage_notifications` | Notifications | Send/manage system-wide notifications |

---

## Full Permission-Role Mapping Matrix

| Permission | Super Admin | Admin | Moderator | Accountant | Content Reviewer | Titan Member | Customer | User |
|------------|:-----------:|:-----:|:---------:|:----------:|:----------------:|:------------:|:--------:|:----:|
| **Core System** | | | | | | | | |
| `navigate_application` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `manage_users` | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `manage_roles` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `manage_permissions` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `manage_customers` | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **Financial** | | | | | | | | |
| `manage_transactions` | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| `perform_transactions` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| `view_ledger` | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| `manage_ledger` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `approve_ledger` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `view_reports` | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Subscriptions** | | | | | | | | |
| `manage_subscriptions` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `view_subscription_analytics` | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Content** | | | | | | | | |
| `review_content` | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
| `submit_content` | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ |
| **Portfolios** | | | | | | | | |
| `manage_portfolios` | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `manage_own_portfolio` | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
| **Birthdays** | | | | | | | | |
| `manage_birthday_rewards` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `view_birthday_eligibility` | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| `view_birthday_analytics` | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Ads** | | | | | | | | |
| `manage_ads` | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `manage_own_ads` | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
| **Rankings** | | | | | | | | |
| `view_member_rankings` | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
| **Wallet** | | | | | | | | |
| `view_wallet` | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| **Referrals** | | | | | | | | |
| `manage_referral_programs` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `view_referral_analytics` | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| **System** | | | | | | | | |
| `manage_system_settings` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `view_audit_logs` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `export_data` | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| `manage_sessions` | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `manage_notifications` | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |

---

## Implementation Priority

1. **Critical:** Add new permissions to `PermissionsEnum.php` and new roles to `RolesEnum.php`
2. **Critical:** Update `RolePermissionSeeder.php` with new permission-role mappings
3. **High:** Add middleware/permission checks to controllers for new permissions
4. **Medium:** Create `super_admin` protection logic (prevent deletion/editing by regular admins)
5. **Nice-to-have:** Role-based admin dashboard sections (finance tab for accountant, moderation queue for moderator)