# User Roles & Permissions Matrix

## 1. Roles

| Role | Scope | Description |
|---|---|---|
| **Super Admin** | Platform-wide | Anthropic-style platform owner. Manages all agencies, candidates, plans, settings, payments. |
| **Agency Owner** | Single agency (tenant) | Full control within their own agency: recruiters, billing, jobs, candidate database access. |
| **Recruiter** | Single agency, permission-scoped | Day-to-day hiring work: search, ATS, messaging, interviews. Permissions can be restricted per-recruiter by the Agency Owner. |
| **Candidate** | Own profile only | Job seeker; manages own profile, applications, messages. |
| **Support Staff** *(optional)* | Single agency, limited | Read-mostly access to help Agency Owner triage (e.g. respond to messages, view applications) without billing/admin rights. |

## 2. Permission Modules

Permissions are stored as `module.action` slugs (e.g. `jobs.create`, `candidates.unlock`) in the `permissions` table and mapped to roles via `role_permissions`. Agency Owners can additionally fine-tune **recruiter-level** permission overrides via a `user_permission_overrides` table (grant/revoke on top of role defaults) — this satisfies the "Team Permissions" requirement under Agency Features.

## 3. Full Matrix

Legend: ✅ Full access · 🟡 Scoped/limited · ❌ No access

| Module / Action | Super Admin | Agency Owner | Recruiter | Candidate | Support Staff |
|---|:---:|:---:|:---:|:---:|:---:|
| **Agencies** |
| View all agencies | ✅ | ❌ | ❌ | ❌ | ❌ |
| Approve/reject agency verification | ✅ | ❌ | ❌ | ❌ | ❌ |
| Suspend/activate agency | ✅ | ❌ | ❌ | ❌ | ❌ |
| Edit own agency profile | ❌ | ✅ | ❌ | ❌ | ❌ |
| **Recruiters / Team** |
| Invite/remove recruiters | ❌ | ✅ | ❌ | ❌ | ❌ |
| Set recruiter permissions | ❌ | ✅ | ❌ | ❌ | ❌ |
| View team activity | ❌ | ✅ | 🟡 own only | ❌ | 🟡 own only |
| **Jobs** |
| Create/edit/delete job | ❌ | ✅ | 🟡 if granted | ❌ | ❌ |
| Publish/unpublish job | ❌ | ✅ | 🟡 if granted | ❌ | ❌ |
| Mark featured/urgent | ❌ | ✅ (billing-gated) | ❌ | ❌ | ❌ |
| View own agency jobs | ❌ | ✅ | ✅ | ❌ | ✅ |
| Browse/apply to public jobs | ❌ | ❌ | ❌ | ✅ | ❌ |
| **Candidate Database / Search** |
| Search candidates | ❌ | ✅ | ✅ (plan-limited) | ❌ | 🟡 view only |
| Reveal contact info | ❌ | ✅ (credit/plan-gated) | ✅ (credit/plan-gated) | ❌ | ❌ |
| Download resume | ❌ | ✅ (credit/plan-gated) | ✅ (credit/plan-gated) | ❌ | ❌ |
| Unlock full profile | ❌ | ✅ (credit-gated) | ✅ (credit-gated) | ❌ | ❌ |
| Tag / note candidates | ❌ | ✅ | ✅ | ❌ | 🟡 notes only |
| Save / shortlist candidates | ❌ | ✅ | ✅ | ❌ | ❌ |
| **Applications / ATS** |
| View applications (own agency) | ❌ | ✅ | ✅ | ❌ | ✅ |
| Move ATS pipeline stage | ❌ | ✅ | ✅ | ❌ | ❌ |
| Assign recruiter to application | ❌ | ✅ | 🟡 self-assign | ❌ | ❌ |
| Apply to jobs | ❌ | ❌ | ❌ | ✅ | ❌ |
| View own applications | ❌ | ❌ | ❌ | ✅ | ❌ |
| **Interviews** |
| Schedule/reschedule/cancel | ❌ | ✅ | ✅ | ❌ | ❌ |
| Submit feedback | ❌ | ✅ | ✅ | ❌ | ❌ |
| View own interview invites | ❌ | ❌ | ❌ | ✅ | ❌ |
| **Messaging** |
| Message candidates | ❌ | ✅ (credit-gated) | ✅ (credit-gated) | ❌ | 🟡 if granted |
| Reply to recruiter | ❌ | ❌ | ❌ | ✅ | ❌ |
| **Candidate Profile** |
| Edit own profile | ❌ | ❌ | ❌ | ✅ | ❌ |
| Set privacy controls | ❌ | ❌ | ❌ | ✅ | ❌ |
| **Billing / Subscription** |
| View/change plan | ❌ | ✅ | ❌ | ❌ | ❌ |
| Manage payment methods | ❌ | ✅ | ❌ | ❌ | ❌ |
| Purchase credits | ❌ | ✅ | ❌ | ❌ | ❌ |
| View invoices | ❌ | ✅ | ❌ | ❌ | ❌ |
| Request refund | ❌ | ✅ | ❌ | ❌ | ❌ |
| Manage all agencies' billing | ✅ | ❌ | ❌ | ❌ | ❌ |
| Configure plans & credit costs (global) | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Wallet** |
| Add funds / view ledger | ❌ | ✅ | ❌ | ❌ | ❌ |
| **Reports** |
| Platform-wide reports | ✅ | ❌ | ❌ | ❌ | ❌ |
| Agency reports (own agency) | ❌ | ✅ | 🟡 own performance | ❌ | ❌ |
| **Settings** |
| Global settings (SMTP, SEO, payment gateways) | ✅ | ❌ | ❌ | ❌ | ❌ |
| Agency-level notification prefs | ❌ | ✅ | 🟡 own prefs | 🟡 own prefs | 🟡 own prefs |
| **Audit / Activity Logs** |
| View platform audit log | ✅ | ❌ | ❌ | ❌ | ❌ |
| View own agency activity | ❌ | ✅ | 🟡 own actions | ❌ | ❌ |
| **Reviews** |
| Moderate company reviews | ✅ | ❌ | ❌ | ❌ | ❌ |
| Leave a company review | ❌ | ❌ | ❌ | ✅ | ❌ |

## 4. Enforcement Points

1. **Route-level:** `RoleGuard` filter checks role on every route group (`app/Config/Filters.php` route-to-permission map).
2. **Service-level:** every write operation in a Service class re-validates permission (`PermissionService::can($user, 'jobs.create')`) — defense in depth, not just filter-level.
3. **Plan/credit-level:** separate from RBAC — `SubscriptionLimitService` and `CreditService` gate actions like contact reveal regardless of role permission (a Recruiter can have the *permission* but still be blocked by plan limits/credit balance).
4. **UI-level:** menu items and buttons hidden via a shared `can()` view helper — cosmetic only, never the actual security boundary.