Setting Up Roles

Roles define what users can see and do in MovaLab. This guide walks you through creating roles, assigning permissions, and building your organizational hierarchy.

Overview

MovaLab uses Role-Based Access Control (RBAC) to manage user permissions. Every user is assigned exactly one role, and that role determines their capabilities throughout the system.

Key Concepts

Role

A named collection of permissions that can be assigned to users. Examples: Designer, Project Manager, Admin.

Permission

A specific capability like VIEW_PROJECTS or EDIT_TASKS. Roles bundle multiple permissions together.

Hierarchy Level

A numeric value (1-10) that determines reporting relationships. Lower numbers = higher authority.

Department

An organizational unit. Roles can be scoped to specific departments for access control.

Default Roles

MovaLab comes with pre-configured roles: Superadmin, Admin, Manager, Team Lead, Member, and Unassigned. You can modify these or create new roles to match your organization.

Creating Roles

Navigate to Settings → User Management → Roles to create and manage roles.

Step-by-Step Guide

Access Role Management

Go to Settings > User Management > Roles tab. You'll see a list of existing roles and an 'Add Role' button.

Create New Role

Click 'Add Role' and enter a name (e.g., 'Senior Designer'). Choose a descriptive name that reflects the role's function.

Set Hierarchy Level

Assign a hierarchy level (1-10). Level 1 is highest authority (CEO), Level 10 is entry-level. This affects reporting relationships and visibility.

Assign Department (Optional)

Optionally scope the role to a specific department. Department-scoped roles only see resources within their department.

Configure Permissions

Select the permissions this role should have. Permissions are grouped by category (Projects, Tasks, Accounts, etc.).

Set Reports To

Define which role this one reports to. This builds your org chart and determines approval workflows.

Role Configuration Fields

Field	Required	Description
name	Yes	Unique role name (e.g., "Project Manager")
description	No	Brief description of role responsibilities
hierarchy_level	Yes	1-10 scale (1 = highest authority)
department_id	No	Scope role to specific department
reports_to	No	ID of the role this one reports to
permissions	Yes	Array of permission strings

Understanding Permissions

Permissions control what actions users can perform. MovaLab has ~40 granular permissions organized into categories.

Permission Categories

Project Permissions

VIEW_PROJECTS, CREATE_PROJECT, EDIT_PROJECT, DELETE_PROJECT, MANAGE_PROJECT_MEMBERS

Task Permissions

VIEW_TASKS, CREATE_TASK, EDIT_TASK, DELETE_TASK, ASSIGN_TASKS

Account Permissions

VIEW_ACCOUNTS, CREATE_ACCOUNT, EDIT_ACCOUNT, DELETE_ACCOUNT

Admin Permissions

MANAGE_ROLES, MANAGE_USERS, MANAGE_DEPARTMENTS, VIEW_AUDIT_LOGS

Workflow Permissions

MANAGE_WORKFLOWS, CREATE_WORKFLOW, EDIT_WORKFLOW, RUN_WORKFLOWS

Override Permissions

VIEW_ALL_PROJECTS, EDIT_ALL_PROJECTS, VIEW_ALL_ACCOUNTS (admin-level)

Base vs Override Permissions

Base Permissions

Apply only to resources the user is assigned to. A user with VIEW_PROJECTS can only see projects they're a member of.

VIEW_PROJECTS, EDIT_TASKS

Override Permissions

Grant access to ALL resources regardless of assignment. Use for admin roles only.

VIEW_ALL_PROJECTS, EDIT_ALL_ACCOUNTS

Security Note

Override permissions are powerful and should only be assigned to admin-level roles. Always follow the principle of least privilege.

Organizational Hierarchy

Define reporting relationships between roles to build your org chart and enable hierarchical workflows.

Hierarchy Levels

Level 1: Executive (CEO, Founder)
Level 2: C-Suite (CTO, CFO, COO)
Level 3: VP / Director
Level 4: Senior Manager
Level 5: Manager
Level 6: Team Lead
Level 7: Senior IC
Level 8: Mid-level IC
Level 9: Junior IC
Level 10: Entry Level / Intern

Example Org Structure

                    CEO (Level 1)
                        │
         ┌──────────────┼──────────────┐
         │              │              │
    CTO (L2)       CFO (L2)       COO (L2)
         │
    ┌────┴────┐
    │         │
Eng Dir   Design Dir
  (L3)       (L3)
    │         │
 Eng Lead  Design Lead
   (L6)       (L6)
    │         │
Engineers  Designers
  (L8)       (L8)

Hierarchy Features

Reporting Chains

Define who reports to whom. Managers can see their direct reports' work.

Approval Workflows

Route approvals up the chain based on hierarchy levels.

Visibility Rules

Higher levels can view resources of their reports (configurable).

Org Chart Visualization

Interactive org chart generated from role relationships.

Best Practices

Start with default roles

MovaLab's default roles cover most use cases. Modify them rather than creating from scratch.

Follow least privilege

Give roles only the permissions they need. It's easier to add permissions than deal with security issues.

Use descriptive names

Name roles by function (Project Manager, Senior Designer) not by person. Roles should be transferable.

Document role purposes

Use the description field to explain what each role is for. Future admins will thank you.

Review permissions quarterly

Audit role permissions regularly. Remove unused permissions and update as responsibilities change.

Avoid permission sprawl

Keep the number of roles manageable (5-15 for most orgs). Too many roles become hard to maintain.

Test before deploying

Create a test user with the new role and verify they can (and can't) do what's expected.

Role Examples

Here are common role configurations for different agency structures.

Project Manager

Manages projects and tasks, assigns work, but doesn't manage users or system settings.

{
  "name": "Project Manager",
  "hierarchy_level": 5,
  "permissions": [
    "VIEW_PROJECTS",
    "CREATE_PROJECT",
    "EDIT_PROJECT",
    "MANAGE_PROJECT_MEMBERS",
    "VIEW_TASKS",
    "CREATE_TASK",
    "EDIT_TASK",
    "DELETE_TASK",
    "ASSIGN_TASKS",
    "VIEW_ACCOUNTS",
    "VIEW_PROJECT_ANALYTICS"
  ]
}

Designer

Works on assigned projects and tasks, logs time, but can't create projects or manage others.

{
  "name": "Designer",
  "hierarchy_level": 8,
  "department_id": "design-department-uuid",
  "permissions": [
    "VIEW_PROJECTS",
    "VIEW_TASKS",
    "EDIT_TASK",
    "MANAGE_TASK_STATUS",
    "LOG_TIME",
    "VIEW_OWN_TIME"
  ]
}

Department Lead

Manages a specific department, can view all department resources, approves time.

{
  "name": "Design Lead",
  "hierarchy_level": 6,
  "department_id": "design-department-uuid",
  "permissions": [
    "VIEW_PROJECTS",
    "CREATE_PROJECT",
    "EDIT_PROJECT",
    "VIEW_ALL_DEPARTMENT_PROJECTS",
    "VIEW_TASKS",
    "CREATE_TASK",
    "EDIT_TASK",
    "ASSIGN_TASKS",
    "VIEW_DEPARTMENT_TIME",
    "APPROVE_TIME",
    "VIEW_DEPARTMENT_ANALYTICS"
  ]
}