[0.1.1] User Role Switching

1. Front Matter

• Title: User Role Switching

• Author: scorevi

• Reviewers: dyorgie

• Created: April 2026

• Status: Approved

• References:

  • Issue: [0.1.1] User Role Switching #406

  • Milestone: [0] Auth & Security

2. Introduction & Goals

• Problem Summary: Users with multiple roles (e.g., Creator + Reviewer) need to quickly switch between role contexts without admin intervention or re-authentication. This enables testing and visualizing different role views.

• Goals:

  • Allow users to switch between their assigned roles via account menu

  • Update navigation and dashboard context instantly

  • Maintain session across role switches

• Non-Goals:

  • Role assignment (admin function)

  • Permission escalation (strict hierarchy)

  • Multi-session support

• Glossary:

  • Role Context: The current active role determining UI and permissions

  • Role Hierarchy: SUPER_ADMIN > ADMIN > AGENCY > CREATOR/REVIEWER/LEARNER

3. High-Level Architecture

• System Diagram:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Account Menu   │────▶│  Role Switcher  │────▶│  Context Update │
│  (User Dropdown)│     │  (Component)    │     │  (Auth Context) │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                │
                                ▼
                        ┌─────────────────┐
                        │  Navigation     │
                        │  (Route Change) │
                        └─────────────────┘

• Technologies Used:

  • React Context - Role state management

  • Clerk Metadata - Store user's available roles

  • Shadcn/UI - Dropdown menu components

4. Detailed Design & Implementation

• Data Model / Schema: No custom tables. Roles stored in Clerk user metadata as publicMetadata.roles: string[].

• API Specification: Role switching is client-side only, no API endpoints required.

• Logic & Workflows:

  Role Switch Flow:

  1. User clicks role switcher in account menu

  2. Available roles fetched from Clerk metadata

  3. User selects new role

  4. RoleContext updated with new role

  5. Navigation redirects to role's dashboard

  Role-Specific Dashboards:

  • CREATOR → /creator

  • REVIEWER → /reviewer

  • LEARNER → /learner

  • ADMIN → /admin

  • AGENCY → /agency

  Key Files:

  • components/ui/role-switcher.tsx - Dropdown component

  • components/context/role-context.tsx - State management

5. Infrastructure & Operations

• Dependencies:

  • Clerk - User metadata storage

• Monitoring & Alerting: No specific monitoring. Role switching is client-side only.

• Deployment Plan: No migrations required. Feature flag optional.

6. Testing & Quality Assurance

• Test Strategy:

  • Manual: Role switch UI, navigation redirect

  • Unit: RoleContext provider logic

• Known Limitations:

  • View-as only (does not change actual permissions)

  • Requires page navigation to see role-specific content

7. Maintenance & Support

• Troubleshooting:

  • Roles not showing → Check Clerk metadata publicMetadata.roles

  • Wrong dashboard → Verify role-to-route mapping

• Changelog:

  • 1.0 (Apr 2026): Initial implementation

Document Version

1.0 - Approved, Feature deployed to production, 04/22/2026