Skip to content

Assessment: Capability Governance & RBAC Strategy

Date: Jan 10, 2026 Subject: Transitioning from Hard-coded RBAC to Relationship-Driven Capability Infusion.

1. Executive Summary

The Community Directory is currently the authoritative source for Identity (Who) and Persona (Role). However, the link between Persona and Capability (What) is currently hard-coded in the system's capability-mapper.ts. To achieve the "Living Definition" objective and minimize administrative burden, we must transition to a Registry-Driven Model.

2. Assessment of Administrative Layers

Layer 1: Individual ↔ Persona (Assignment)

  • Constraint: Needs to be easy for Front Desk/Admin.
  • Current Status: SUCCESS. Managed via the Community Directory workbench.
  • Screen Requirement: NONE. The Directory is already the assignment tool. We should avoid creating a separate "RBAC Assignment" screen; instead, we treat access as a byproduct of relationship management.

Layer 2: Persona ↔ Capability (Policy Matrix)

  • Constraint: Code-dependency creates bottlenecks; manual DB entry for every user creates fragmentation.
  • Current Status: HARD-CODED. Defined in TypeScript if/else logic.
  • Screen Requirement: HIGH. We need a Capability Matrix Manager.
    • Purpose: Allows the General Manager or Board to define the "Global Template" for each Persona (e.g., "All Maintenance Staff can resolve Work Orders").
    • Benefit: Changing access for an entire department happens in one place, instantly affecting the AuthzSnapshot of all relevant users.

Layer 3: Capability ↔ System Rules (Aggregation)

  • Constraint: Low-level technical IDs (e.g., [FIN-GL-ENTRY]) are confusing for humans.
  • Current Status: FLAT. Capabilities are defined individually.
  • Screen Requirement: MEDIUM. We need a Capability Registry / Dictionary.
    • Purpose: Group low-level "Rights" into Logical Business Terms (e.g., "Full Financial Transparency").
    • Benefit: Admins assign "Bundles" rather than individual checkboxes.

3. Proposed "Living" Architecture

A. The Capability Matrix Registry

Move Persona definitions out of code and into the data layer: 

{
  "persona_id": "BOARD_TREASURER",
  "label": "Treasurer",
  "archetype": "FIDUCIARY_GOVERNANCE",
  "capabilities": [
    "FIN-AP-APPROVE",
    "FIN-BUDGET-EDIT",
    "FIN-AR-REPORT"
  ]
}

B. The Dependency Chain

  1. Directory: Admin adds STAFF + MAINTENANCE to a profile.
  2. Mapper: System looks up STAFF_MAINTENANCE in the Registry.
  3. Infusion: System merges "Registry Defaults" + "Individual Overrides" + "Delegation Grants".
  4. Snapshot: User receives a clean, context-aware AuthzSnapshot.

4. Immediate Next Steps

  1. PHASE A (Structure): Refactor capability-mapper.ts to use a Registry-backed lookup instead of hard-coded logic.
  2. PHASE B (Visibility): Create a "Capability Audit" screen in the Admin Directory to visualize the effective rights of a Persona.
  3. PHASE C (Control): Implement the "Matrix Manager" UI for defining global persona behaviors.

[!IMPORTANT] By making the Directory the Assignment Layer, we eliminate the need for a separate "User Permissions" screen. The system "lives" by the relationships recorded in the Directory.