Roles Management — Design Doc
Feature: Roles & Permissions management screen in the Manage portal
Status: [To Build]
Author: Moble Joseph
Date: 2026-04-26
Background
Roles in Leadmetrics v3 are currently hardcoded strings at two levels:
| Level | Field | Values |
|---|---|---|
| Platform (User) | User.role | super_admin, admin, member, reviewer |
| Tenant membership | TenantMember.role | admin, member, reviewer |
There is no Role or Permission model in the database. Role checks throughout the API and portals are plain string comparisons. There is no UI anywhere to manage, document, or extend roles.
Goals
- Give superadmins a dedicated screen to view, create, edit, and delete roles
- Optionally add granular permission assignments per role
- Protect built-in system roles from destructive edits
Two Implementation Options
See Option A — Simple Roles and Option B — Dynamic Roles with Permissions for full specs.
| Dimension | Option A (Simple) | Option B (Dynamic) |
|---|---|---|
| DB changes | Role table only | Role + Permission + RolePermission |
| Custom roles | No | Yes |
| Permission granularity | No | Yes — resource × action matrix |
| Auth check changes | None | Every route + middleware |
| Effort | ~1 day | ~3–4 days |
| Risk | Low | High (breaking) |
Recommendation: Ship Option A first. It unblocks UI/documentation needs immediately. Option B can be layered on top when permission granularity becomes a product requirement.
Open Questions
- Should tenant admins be able to create custom roles scoped to their tenant, or is this superadmin-only?
- If Option B: what is the full list of resources and actions? (Draft in Option B spec)
- Should built-in role identifiers (
super_admin,admin, etc.) be renameable, or label-only editable? - Do we need role assignment history / audit trail beyond the existing
writeAuditLog?