RBAC System: Key Concepts and Relationships

🔑 Core Concepts

1. User

Individual person who needs access to the system

• Has basic profile information (name, email, etc.)
• Can have multiple role assignments
• Example: Sarah (Facility Manager), Mike (Building Supervisor), Jessica (Maintenance Technician)

2. Role

A role that is associated with a predefined set of permissions that define what actions can be performed

• Contains a list of module-action permissions
• System-defined (same across all clients)
• Example: Building Admin, Building Manager, Building User

3. Permission

Specific action allowed on a module

• Format: {module: "operations", action: "edit"}
• Only two actions: read or edit
• Example: Can read monitoring data, Can edit operations tasks

4. Scope

The boundary/context where permissions apply

• Hierarchical: Client → Project → Building
• Defines "where" the role's permissions are active
• Example: Building A, Project Downtown, Client TechCorp

5. Role Assignment

The bridge that connects User + Role + Scope

• Says: "This User has this Role within this Scope"
• Can have multiple assignments per user
• Example: Jessica has Building User role in both Building A and Building C

---

🔗 How They Work Together

USER + ROLE + SCOPE = ROLE ASSIGNMENT
   ↓
ROLE ASSIGNMENT = EFFECTIVE PERMISSIONS

Example Authorization Flow:

1. Jessica logs in (User)
2. System finds her role assignments:
   • Building User role in Building A
   • Building User role in Building C
3. System gets Building User role permissions:
   • monitoring: read
   • operations: read
   • sustainability: read
   • etc.
4. Jessica can now: View all modules in Buildings A & C, but cannot edit anything

---

📊 Permission Resolution Logic

When Jessica tries to access "Operations" in Building A:

1. Find Role Assignments for Jessica in Building A
   → Result: Building User role

2. Get permissions for Building User role
   → Result: operations: read

3. Check if requested action (read/edit) is allowed
   → Jessica can READ operations in Building A ✅
   → Jessica cannot EDIT operations in Building A ❌

When Mike tries to edit "Operations" in Warehouse:

1. Find Role Assignments for Mike in Warehouse
   → Result: Building Manager role

2. Get permissions for Building Manager role
   → Result: operations: read, edit

3. Check if requested action is allowed
   → Mike can EDIT operations in Warehouse ✅

---

🏗️ Database Storage Pattern

Role (System-wide)

PK: "SYSTEM"
SK: "ROLE#building_admin"
{
  "role_id": "building_admin",
  "name": "Building Administrator",
  "permissions": [
    {"module": "monitoring", "action": "read"},
    {"module": "monitoring", "action": "edit"},
    // ... more permissions
  ]
}

Role Assignment (Per User)

PK: "USER#jessica_id"
SK: "ROLE#building#building_a_id#building_user"
{
  "user_id": "jessica_id",
  "role_id": "building_user_role_id",
  "scope_type": "building",
  "scope_id": "building_a_id",
  "status": "active"
}

Role 1: Building Admin

Scope: Building Level Target Users: Senior facility managers, building owners, or designated building administrators

Use Case

Sarah is a Senior Facility Manager at a corporate office building. She needs complete control over all building operations, from managing staff access to configuring building systems and overseeing all maintenance activities. She's responsible for the building's overall performance and needs comprehensive access to make strategic decisions.

Core Permissions

{
  "role_id": "building_admin",
  "name": "Building Administrator",
  "description": "Complete administrative access to all building systems and data",
  "scope_type": "building",
  "is_system": true,
  "permissions": [
    // Account Management Module
    { "module": "account management", "action": "read" },
    { "module": "account management", "action": "edit" },

    // Monitoring Module
    { "module": "monitoring", "action": "read" },
    { "module": "monitoring", "action": "edit" },

    // Operations Module
    { "module": "operations", "action": "read" },
    { "module": "operations", "action": "edit" },

    // Sustainability Module
    { "module": "sustainability", "action": "read" },
    { "module": "sustainability", "action": "edit" },

    // Spatial Intelligence Module
    { "module": "spatial_intelligence", "action": "read" },
    { "module": "spatial_intelligence", "action": "edit" },

    // Building Management
    { "module": "building_management", "action": "read" },
    { "module": "building_management", "action": "edit" },

    // User Management (Building Scope)
    { "module": "user_management", "action": "read" },
    { "module": "user_management", "action": "edit" },

    // Reporting
    { "module": "reporting", "action": "read" },
    { "module": "reporting", "action": "edit" }
  ]
}

---

Role 2: Building Manager

Scope: Building Level Target Users: Day-to-day facility managers, operations supervisors

Use Case

Mike is a Building Manager for a mixed-use commercial building. His daily responsibilities include overseeing maintenance operations, managing cleaning schedules, responding to tenant requests, and ensuring the building operates efficiently. He needs operational control but doesn't require administrative functions like user management or system configurations.

Core Permissions

{
  "role_id": "building_manager",
  "name": "Building Manager",
  "description": "Operational management access with limited administrative functions",
  "scope_type": "building",
  "is_system": true,
  "permissions": [
    // Monitoring Module
    { "module": "monitoring", "action": "read" },

    // Operations Module
    { "module": "operations", "action": "read" },
    { "module": "operations", "action": "edit" },

    // Sustainability Module
    { "module": "sustainability", "action": "read" },

    // Spatial Intelligence Module
    { "module": "spatial_intelligence", "action": "read" },

    // Building Management
    { "module": "building_management", "action": "read" },

    // Reporting
    { "module": "reporting", "action": "read" }
  ]
}

---

Role 3: Building User

Scope: Building Level Target Users: Maintenance technicians, cleaning staff, security personnel, tenant representatives

Use Case

Jessica is a Maintenance Technician working in a hospital building. She needs to view her assigned work orders, update maintenance request statuses, check sensor readings related to her work areas, and log completion of tasks. She requires read access to building information relevant to her work but doesn't need management capabilities.

Core Permissions

{
  "role_id": "building_user",
  "name": "Building User",
  "description": "Basic operational access for building staff and technicians",
  "scope_type": "building",
  "is_system": true,
  "permissions": [
    // Monitoring Module
    { "module": "monitoring", "action": "read" },

    // Operations Module
    { "module": "operations", "action": "read" },

    // Sustainability Module
    { "module": "sustainability", "action": "read" },

    // Spatial Intelligence Module
    { "module": "spatial_intelligence", "action": "read" },

    // Building Management
    { "module": "building_management", "action": "read" },

    // Reporting
    { "module": "reporting", "action": "read" }
  ]
}

---

Permission Action Types Reference

Simple Actions

• read: View/access all data and functionality within the module
• edit: Create, modify, delete, configure, and perform all administrative actions within the module

---

Implementation Notes

Database Storage

These roles will be stored as system roles in your DynamoDB table with:

• PK: SYSTEM
• SK: ROLE#{role_id}
• is_system: true
• client_id: null (system-wide roles)

Role Assignment

Users are assigned these roles at the building level using the UserRoleAssignment pattern:

• PK: USER#{user_id}
• SK: ROLE#building#{building_id}#{role_id}
• scope_type: "building"
• scope_id: {building_id}