RoleManager

• RoleManager
  • Overview
  • Data Structure
    • State Schema
    • Enums and Types
    • Additional Structures
  • Core Functionality
    • Main Feature Groups
  • Workflow Integration
  • API Methods
    • Role Management
    • Role Information
    • Permission Management
    • Approval Operations
    • System Operations
  • Key Features
  • Layer System Integration
    • How the Layer System Works
    • Authorization Performance Benefits
    • Layer Management Methods
    • Layer File Structure

Overview

The RoleManager class serves as the central authority for role-based access control (RBAC) within the Program Management system, managing role definitions, permissions, and authorization workflows.

General Purpose:

• Manages role creation, updates, and status changes with workflow approval integration
• Defines and maintains permission mappings across all system classes
• Provides centralized authorization services through Layer-based deployment and state management
• Handles role approval workflows and status transitions
• Singleton instance with 'default' ID managing all role configurations

Data Structure

State Schema

interface RoleManagerState {
  private: {
    roleHash: string
    roles: Record<string, Role>
    lastDeploymentTime?: number
  }
  public: object
}

interface Role {
  id: string
  name: string
  description?: string
  level: RoleLevel
  createdBy: StateManagerActor
  permissions: Record<ClassKey, string[]>
  status: RoleStatus
  createdAt?: string
  updatedAt?: string
}

Enums and Types

enum RoleLevel {
  SUPER = 1,    // Super Roles can access all methods without permission checks
  NORMAL = 10   // Normal roles require explicit permissions
}

enum RoleStatus {
  ACTIVE = 'active',
  INACTIVE = 'inactive'
}

enum RoleEvents {
  ROLE_CREATE = 'role_create',
  ROLE_UPDATE = 'role_update',
  ROLE_STATUS_UPDATE = 'role_status_update'
}

Additional Structures

interface Permission<T extends string = string, K extends ClassKey = ClassKey> {
  key: T
  classId: K
  label: string
  methods: string[]
}

interface StateManagerActor {
  id: string
  // Additional actor properties
}

Core Functionality

Main Feature Groups

• Role Lifecycle Management: Create, update, and manage roles with workflow approval integration
• Permission System: Centralized permission definitions mapped to system classes and methods
• Authorization Services: Layer-based role deployment for high-performance authorization checks
• Level-Based Hierarchy: Role level system controlling user management capabilities
• Status Management: Role activation and deactivation through approval workflows
• Deployment Integration: Automatic role synchronization with system layers

Workflow Integration

The RoleManager extends WorkflowCompatibleStateManager and integrates with the workflow system:

• Status Transitions: Workflow rules manage role status changes from inactive to active
• Events: Role creation, updates, and status changes trigger workflow processing
• Approval Integration: All significant operations go through approval workflows before completion
• Business Rules: Workflow configuration defines approval requirements and role hierarchy validation

API Methods

Role Management

• createRole (WRITE) - Create a new role with Normal level and Inactive status
  • Sets initial status to inactive and triggers role creation workflow
• updateRole (WRITE) - Update existing role information and permissions
  • Requires role existence validation and triggers update workflow
• updateStatus (WRITE) - Update role status
  • Manages status transitions through workflow rules

Role Information

• getRole (READ) - Retrieve role details by ID
• listRoles (READ) - List roles with filtering and pagination
  • Supports filtering by status and search terms with configurable pagination

Permission Management

• getPermissions (STATIC) - Get list of all available permissions
  • Returns comprehensive permission mappings across all system classes

Approval Operations

• approve (QUEUED_WRITE) - Process role approval workflows
  • Applies JSON patches from approval records and updates role status

System Operations

• getRolesForAuthentication (READ) - Get roles for authentication purposes
  • Optimized for authorization service consumption
• saveRolesToLayerAndTriggerDeployment (QUEUED_WRITE) - Save roles to the layer and trigger deployment
  • Synchronizes role changes with system infrastructure
• setState (WRITE) - Set the class state from rio console
  • Administrative method for state management

Method Types:

• WRITE - Sync state mutation (1-30s)
• READ - Sync state access (1-30s)
• QUEUED_WRITE - Async state mutation (1-890s)
• STATIC - Stateless utility

Key Features

1. Architecture Pattern: Singleton instance with 'default' ID managing all role configurations
2. Integration Points: Integrates with ApprovalManager, Workflow system, and RDK Layer deployment
3. Workflow Support: Full workflow integration with approval processes for all major operations
4. Security Features: Multi-level role hierarchy with super and normal permission levels
5. Data Management: Extends WorkflowCompatibleStateManager with hash-based change tracking
6. External Integrations: Layer-based role deployment with RDK dependency system
7. Performance Features: Role hash validation, Layer-based caching, and efficient permission mapping
8. Audit/Logging: Complete activity tracking through workflow system and actor-based operations

Layer System Integration

The RoleManager implements a layer-based caching system that improves performance and reduces costs by minimizing state access during authorization checks.

How the Layer System Works

Layer Deployment Process:

1. Role Serialization: When roles are updated, RoleManager serializes all active roles into a JSON format
2. Dependency Creation: Creates a zip file containing nodejs/node_modules/roles/roles.json with current role data
3. RDK Layer Deployment: Uses rdk.upsertDependency() to create/update the 'roles' dependency layer
4. Project Deployment: Triggers rdk.deployProject() to make the layer available across all class instances
5. Hash Tracking: Updates role hash to track changes and prevent unnecessary deployments

Performance Optimization:

• Fast Import: Authorizers use import('roles/roles.json') for immediate role access without state queries
• Deployment Cooldown: 3-minute cooldown period prevents excessive deployments during frequent updates
• Fallback Mechanism: If layer import fails, automatically falls back to getRolesForAuthentication() method call
• Auto-Recovery: Failed imports trigger automatic layer regeneration and deployment

Layer Management Methods

// Deployment with cooldown protection
saveRolesToLayerAndTriggerDeployment(): Promise<{
  isUpdated: boolean
  deploymentScheduled?: boolean
  nextDeploymentAvailable?: number
  hash: string
}>

// Fallback role retrieval
getRolesForAuthentication(): Promise<{
  roles: Role[]
}>

// Utility for getting roles with layer fallback
getRolesFromLayer(): Promise<Role[]>

Layer File Structure

The deployed layer contains roles in the following structure:

{
  "roles": [
    {
      "id": "superadmin",
      "name": "Super Administrator",
      "level": 1,
      "status": "active",
      "permissions": {
        "RoleManager": ["createRole", "updateRole"],
        "ProgramManagementUser": ["createUser", "updateUser"]
      },
      "createdAt": "2025-09-09T04:33:14.939Z",
      "updatedAt": "2025-09-09T04:33:14.939Z"
    }
  ]
}

Class Relations

The following diagram illustrates how RoleManager integrates with other system components: