Common Role Patterns

This guide covers proven patterns for structuring roles in different organizational contexts.

Pattern 1: Department-Based

Organize by organizational departments.

Roles

hr          - Human Resources
finance     - Finance/Accounting
engineering - Engineering/Development
sales       - Sales team
marketing   - Marketing team
legal       - Legal department
all-staff   - Everyone

Document Structure

/hr/
  └── policies.pdf (aclRoles: hr)
  └── handbook.pdf (aclRoles: all-staff)
  
/finance/
  └── budget.pdf (aclRoles: finance)
  └── expense-policy.pdf (aclRoles: all-staff)
  
/engineering/
  └── architecture.pdf (aclRoles: engineering)

User Role Assignment

function getDepartmentRoles(user) {
  const roles = ['all-staff'];
  
  const deptMap = {
    'Human Resources': 'hr',
    'Finance': 'finance',
    'Engineering': 'engineering'
  };
  
  if (deptMap[user.department]) {
    roles.push(deptMap[user.department]);
  }
  
  return roles;
}

Best for: Traditional organizations with clear departmental boundaries.

Pattern 2: Hierarchical

Control access based on seniority level.

Roles

employee    - All employees (base level)
manager     - People managers
director    - Department heads
vp          - Vice presidents
executive   - C-suite

Document Classification

Document Type	Required Role
General policies	`employee`
Team guidelines	`manager`
Strategic plans	`director`
Board materials	`executive`

Cumulative Assignment

Higher levels get all lower roles:

function getHierarchyRoles(level) {
  const levels = ['employee', 'manager', 'director', 'vp', 'executive'];
  const index = levels.indexOf(level);
  
  if (index === -1) return ['employee'];
  return levels.slice(0, index + 1);
}

// Director gets: ['employee', 'manager', 'director']

Best for: Organizations where information flows down the hierarchy.

Pattern 3: Project-Based

Isolate access by project or team.

Roles

project-alpha    - Project Alpha team
project-beta     - Project Beta team
project-gamma    - Project Gamma team
project-lead     - Cross-project visibility
engineering      - All engineers

Document Structure

/projects/alpha/
  └── specs.pdf (aclRoles: project-alpha, project-lead)
  └── designs.pdf (aclRoles: project-alpha)
  
/projects/beta/
  └── specs.pdf (aclRoles: project-beta, project-lead)
  
/engineering/
  └── standards.pdf (aclRoles: engineering)

Dynamic Assignment

function getProjectRoles(user) {
  const roles = [];
  
  // Add each project the user is on
  user.projects.forEach(project => {
    roles.push(`project-${project.slug}`);
  });
  
  // Project leads see all project specs
  if (user.isProjectLead) {
    roles.push('project-lead');
  }
  
  // All engineers see engineering docs
  if (user.isEngineer) {
    roles.push('engineering');
  }
  
  return roles;
}

Best for: Organizations with multiple concurrent projects or client engagements.

Pattern 4: Clearance Levels

Tiered access based on security classification.

Roles

public       - Unclassified information
internal     - Internal use only
confidential - Need-to-know basis
restricted   - Highly sensitive

Inclusive Assignment

Higher clearance includes lower:

function getClearanceRoles(clearanceLevel) {
  const levels = ['public', 'internal', 'confidential', 'restricted'];
  const index = levels.indexOf(clearanceLevel);
  
  return levels.slice(0, index + 1);
}

// 'confidential' clearance: ['public', 'internal', 'confidential']

Document Tagging

// Upload with appropriate classification
await upload({
  file: 'financial-projections.pdf',
  aclRoles: ['confidential']  // Only confidential+ clearance
});

await upload({
  file: 'company-news.pdf',
  aclRoles: ['internal']  // All employees
});

Best for: Regulated industries, government, or security-conscious organizations.

Pattern 5: Hybrid (Department + Level)

Combine department and hierarchy for fine-grained control.

Roles

hr              - HR department
hr-manager      - HR managers
finance         - Finance department
finance-manager - Finance managers
all-staff       - Everyone
manager         - All managers (cross-dept)

Matrix Assignment

function getHybridRoles(user) {
  const roles = ['all-staff'];
  
  // Department role
  roles.push(user.department.toLowerCase());
  
  // Department + level role
  if (user.isManager) {
    roles.push(`${user.department.toLowerCase()}-manager`);
    roles.push('manager'); // Cross-department manager role
  }
  
  return roles;
}

Document Examples

Document	ACL	Who Can Access
HR Policy	`hr`	All HR
HR Manager Guide	`hr-manager`	HR managers only
Manager Handbook	`manager`	All managers
Company Handbook	`all-staff`	Everyone

Best for: Organizations needing both departmental and hierarchical control.

Pattern 6: Client/Customer Based

For agencies or service providers managing multiple clients.

Roles

client-acme      - Acme Corp engagement
client-betainc   - Beta Inc engagement
account-manager  - All account managers
internal         - Internal staff only

Document Structure

/clients/acme/
  └── proposal.pdf (aclRoles: client-acme, account-manager)
  └── contract.pdf (aclRoles: client-acme)
  
/internal/
  └── playbook.pdf (aclRoles: internal)

Best for: Agencies, consultancies, managed service providers.

Choosing a Pattern

If your org has…	Consider…
Clear departments	Department-based
Strong hierarchy	Hierarchical
Project teams	Project-based
Sensitivity levels	Clearance levels
Complex structure	Hybrid
Multiple clients	Client-based

Combining Patterns

You can mix patterns as needed:

function getAllRoles(user) {
  const roles = new Set();
  
  // Base role
  roles.add('all-staff');
  
  // Department
  roles.add(user.department.toLowerCase());
  
  // Hierarchy
  if (user.level === 'manager') {
    roles.add('manager');
  }
  
  // Projects
  user.projects.forEach(p => roles.add(`project-${p}`));
  
  // Clearance
  getClearanceRoles(user.clearance).forEach(r => roles.add(r));
  
  return [...roles];
}

Getting Started

Core Concepts

Roles & Access Control

Code Examples

Reference

Common Role Patterns

Common Role Patterns

Pattern 1: Department-Based

Roles

Document Structure

User Role Assignment

Pattern 2: Hierarchical

Roles

Document Classification

Cumulative Assignment

Pattern 3: Project-Based

Roles

Document Structure

Dynamic Assignment

Pattern 4: Clearance Levels

Roles

Inclusive Assignment

Document Tagging

Pattern 5: Hybrid (Department + Level)

Roles

Matrix Assignment

Document Examples

Pattern 6: Client/Customer Based

Roles

Document Structure

Choosing a Pattern

Combining Patterns

Next Steps

Getting Started

Core Concepts

Roles & Access Control

Code Examples

Reference

​Common Role Patterns

​Pattern 1: Department-Based

​Roles

​Document Structure

​User Role Assignment

​Pattern 2: Hierarchical

​Roles

​Document Classification

​Cumulative Assignment

​Pattern 3: Project-Based

​Roles

​Document Structure

​Dynamic Assignment

​Pattern 4: Clearance Levels

​Roles

​Inclusive Assignment

​Document Tagging

​Pattern 5: Hybrid (Department + Level)

​Roles

​Matrix Assignment

​Document Examples

​Pattern 6: Client/Customer Based

​Roles

​Document Structure

​Choosing a Pattern

​Combining Patterns

​Next Steps

Common Role Patterns

Pattern 1: Department-Based

Roles

Document Structure

User Role Assignment

Pattern 2: Hierarchical

Roles

Document Classification

Cumulative Assignment

Pattern 3: Project-Based

Roles

Document Structure

Dynamic Assignment

Pattern 4: Clearance Levels

Roles

Inclusive Assignment

Document Tagging

Pattern 5: Hybrid (Department + Level)

Roles

Matrix Assignment

Document Examples

Pattern 6: Client/Customer Based

Roles

Document Structure

Choosing a Pattern

Combining Patterns

Next Steps