flowchart TB
    subgraph "Identity"
        USER[User]
        SESSION[Session]
    end

    subgraph "Assignment"
        USER_ROLE[User-Role Assignment]
        TENANT_SCOPE[Tenant Scope]
    end

    subgraph "Roles"
        ROLE[Role]
        ROLE_PERMS[Role Permissions]
    end

    subgraph "Permissions"
        PERMISSION[Permission]
        RESOURCE[Resource]
        ACTION[Action]
    end

    subgraph "Enforcement"
        CHECK[Permission Check]
        ALLOW[Allow Access]
        DENY[Deny Access]
    end

    USER --> SESSION
    SESSION --> USER_ROLE
    USER_ROLE --> TENANT_SCOPE
    TENANT_SCOPE --> ROLE

    ROLE --> ROLE_PERMS
    ROLE_PERMS --> PERMISSION

    PERMISSION --> RESOURCE
    PERMISSION --> ACTION

    PERMISSION --> CHECK
    CHECK --> ALLOW
    CHECK --> DENY

    style CHECK fill:#e1f5fe
    style ALLOW fill:#e8f5e9
    style DENY fill:#ffebee

erDiagram
    USER ||--o{ USER_TENANT_ROLE : has
    TENANT ||--o{ USER_TENANT_ROLE : scopes
    ROLE ||--o{ USER_TENANT_ROLE : assigned
    ROLE ||--o{ ROLE_PERMISSION : has
    PERMISSION ||--o{ ROLE_PERMISSION : granted_to

    USER_TENANT_ROLE {
        string id PK
        string userId FK
        string tenantId FK
        string roleId FK
        timestamp assignedAt
        string assignedBy FK
    }

    ROLE {
        string id PK
        string tenantId FK
        string name
        string description
        boolean isSystem
        int priority
    }

    PERMISSION {
        string id PK
        string code
        string name
        string category
        string description
    }

    ROLE_PERMISSION {
        string id PK
        string roleId FK
        string permissionId FK
    }

flowchart TD
    subgraph "Permission Categories"
        ADMIN[Admin Permissions]
        MGMT[Management Permissions]
        OPS[Operations Permissions]
        VIEW[View Permissions]
    end

    subgraph "Resource Permissions"
        USERS_PERM[users:*]
        ORDERS_PERM[orders:*]
        PRODUCTS_PERM[products:*]
        SETTINGS_PERM[settings:*]
    end

    subgraph "Actions"
        READ[read]
        WRITE[write]
        DELETE[delete]
        ADMIN_ACT[admin]
    end

    ADMIN --> USERS_PERM
    ADMIN --> SETTINGS_PERM

    MGMT --> ORDERS_PERM
    MGMT --> PRODUCTS_PERM

    OPS --> ORDERS_PERM
    OPS --> PRODUCTS_PERM

    USERS_PERM --> READ
    USERS_PERM --> WRITE
    USERS_PERM --> DELETE
    USERS_PERM --> ADMIN_ACT

    ORDERS_PERM --> READ
    ORDERS_PERM --> WRITE

    style ADMIN fill:#ffebee
    style MGMT fill:#fff3e0
    style OPS fill:#e8f5e9

sequenceDiagram
    participant Client
    participant Router as TRPC Router
    participant Middleware as Auth Middleware
    participant Checker as Permission Checker
    participant Cache as Permission Cache
    participant DB as Database

    Client->>Router: Protected request
    Router->>Middleware: Check authorization

    Middleware->>Checker: hasPermission(userId, permission)
    Checker->>Cache: Get cached permissions

    alt Cache hit
        Cache-->>Checker: Permissions list
    else Cache miss
        Checker->>DB: Load user permissions
        DB-->>Checker: Permissions
        Checker->>Cache: Store in cache
    end

    Checker->>Checker: Check permission match

    alt Has permission
        Checker-->>Middleware: Authorized
        Middleware-->>Router: Proceed
        Router->>Router: Execute handler
        Router-->>Client: Response
    else No permission
        Checker-->>Middleware: Denied
        Middleware-->>Client: 403 Forbidden
    end

flowchart TD
    REQUEST[Protected Request] --> EXTRACT[Extract Required Permission]

    EXTRACT --> CHECK_TYPE{Check Type}

    CHECK_TYPE --> SINGLE[Single Permission]
    CHECK_TYPE --> ANY[Any of Permissions]
    CHECK_TYPE --> ALL[All Permissions]

    SINGLE --> HAS_SINGLE{Has Permission?}
    HAS_SINGLE -->|Yes| ALLOW
    HAS_SINGLE -->|No| DENY

    ANY --> HAS_ANY{Has Any?}
    HAS_ANY -->|Yes| ALLOW
    HAS_ANY -->|No| DENY

    ALL --> HAS_ALL{Has All?}
    HAS_ALL -->|Yes| ALLOW
    HAS_ALL -->|No| DENY

    ALLOW[Allow Access]
    DENY[Deny Access]

    subgraph "Code Examples"
        EX1["permissionProtectedProcedure(['orders:read'])"]
        EX2["permissionProtectedProcedure(['orders:read', 'products:read'])"]
        EX3["requireAllPermissions(['admin:users', 'admin:settings'])"]
    end

    style ALLOW fill:#e8f5e9
    style DENY fill:#ffebee

flowchart TD
    ADMIN[Admin User] --> SELECT_USER[Select User]
    SELECT_USER --> SELECT_ROLE[Select Role]

    SELECT_ROLE --> CHECK_SCOPE{Role Scope}
    CHECK_SCOPE --> TENANT_ROLE[Tenant Role]
    CHECK_SCOPE --> SITE_ROLE[Site Role]

    TENANT_ROLE --> VERIFY_T[Verify Admin's Tenant Access]
    SITE_ROLE --> VERIFY_S[Verify Admin's Site Access]

    VERIFY_T --> CAN_ASSIGN_T{Can Assign?}
    VERIFY_S --> CAN_ASSIGN_S{Can Assign?}

    CAN_ASSIGN_T -->|No| FORBIDDEN[Forbidden]
    CAN_ASSIGN_S -->|No| FORBIDDEN

    CAN_ASSIGN_T -->|Yes| CREATE_ASSIGN[Create Assignment]
    CAN_ASSIGN_S -->|Yes| CREATE_ASSIGN

    CREATE_ASSIGN --> AUDIT[Log Assignment]
    AUDIT --> NOTIFY[Notify User]

    NOTIFY --> CLEAR_CACHE[Clear Permission Cache]
    CLEAR_CACHE --> COMPLETE[Assignment Complete]

    style COMPLETE fill:#e8f5e9
    style FORBIDDEN fill:#ffebee

flowchart TD
    CHECK[Permission Check] --> CACHE{In Cache?}

    CACHE -->|Yes| HIT[Cache Hit]
    HIT --> USE[Use Cached Permissions]

    CACHE -->|No| MISS[Cache Miss]
    MISS --> LOAD[Load from Database]
    LOAD --> STORE[Store in Cache]
    STORE --> USE

    subgraph "Cache Strategy"
        KEY["Key: user:{userId}:tenant:{tenantId}:perms"]
        TTL[TTL: 15 minutes]
        INVALIDATE[Invalidate on Role Change]
    end

    subgraph "Invalidation Triggers"
        ROLE_CHANGE[Role Assignment Changed]
        PERM_CHANGE[Role Permissions Changed]
        LOGOUT[User Logout]
    end

    ROLE_CHANGE --> CLEAR[Clear User Cache]
    PERM_CHANGE --> CLEAR_ROLE[Clear All Users with Role]
    LOGOUT --> CLEAR

    style HIT fill:#e8f5e9

flowchart TD
    subgraph "Platform Roles"
        SUPER[super_admin]
        SUPPORT[support]
    end

    subgraph "Tenant Roles"
        OWNER[tenant_owner]
        ADMIN[tenant_admin]
        MANAGER[manager]
        STAFF[staff]
        VIEWER[viewer]
    end

    subgraph "Permissions"
        ALL["*"]
        TENANT_ALL["tenant:*"]
        SITE_ALL["site:*"]
        LIMITED[Specific permissions]
    end

    SUPER --> ALL
    SUPPORT --> LIMITED

    OWNER --> TENANT_ALL
    ADMIN --> SITE_ALL
    MANAGER --> LIMITED
    STAFF --> LIMITED
    VIEWER --> LIMITED

    style SUPER fill:#ffebee
    style OWNER fill:#fff3e0

flowchart TD
    REQUEST[Access Request] --> BASE_CHECK{Has Base Permission?}

    BASE_CHECK -->|No| DENY[Deny]
    BASE_CHECK -->|Yes| CONDITION{Has Conditions?}

    CONDITION -->|No| ALLOW[Allow]
    CONDITION -->|Yes| EVAL[Evaluate Conditions]

    EVAL --> OWNER_CHECK{Owner Check?}
    OWNER_CHECK -->|Yes| IS_OWNER{Is Owner?}
    IS_OWNER -->|Yes| ALLOW
    IS_OWNER -->|No| NEXT_COND

    EVAL --> SITE_CHECK{Site Check?}
    SITE_CHECK -->|Yes| SAME_SITE{Same Site?}
    SAME_SITE -->|Yes| ALLOW
    SAME_SITE -->|No| NEXT_COND

    NEXT_COND[Check Next Condition] --> MORE{More Conditions?}
    MORE -->|Yes| EVAL
    MORE -->|No| DENY

    subgraph "Condition Examples"
        OWN["orders:write + own records only"]
        SITE_COND["products:read + same site only"]
        TIME["reports:export + business hours only"]
    end

    style ALLOW fill:#e8f5e9
    style DENY fill:#ffebee

flowchart TD
    subgraph "Role Hierarchy"
        ADMIN_ROLE[Admin Role]
        MANAGER_ROLE[Manager Role]
        STAFF_ROLE[Staff Role]
    end

    subgraph "Inheritance Chain"
        ADMIN_PERMS[Admin Permissions]
        MANAGER_PERMS[Manager Permissions]
        STAFF_PERMS[Staff Permissions]
    end

    ADMIN_ROLE --> ADMIN_PERMS
    ADMIN_PERMS --> MANAGER_PERMS
    MANAGER_PERMS --> STAFF_PERMS

    ADMIN_ROLE --> MANAGER_ROLE
    MANAGER_ROLE --> STAFF_ROLE

    subgraph "Effective Permissions"
        ADMIN_EFF[Admin: All]
        MANAGER_EFF[Manager: Manager + Staff]
        STAFF_EFF[Staff: Staff only]
    end

    ADMIN_PERMS --> ADMIN_EFF
    MANAGER_PERMS --> MANAGER_EFF
    STAFF_PERMS --> STAFF_EFF

flowchart TD
    PROCEDURE[TRPC Procedure] --> TYPE{Procedure Type}

    TYPE --> PUBLIC[publicProcedure]
    TYPE --> PROTECTED[protectedProcedure]
    TYPE --> PERMISSION[permissionProtectedProcedure]

    PUBLIC --> NO_CHECK[No Auth Check]
    NO_CHECK --> EXECUTE[Execute Handler]

    PROTECTED --> AUTH_CHECK[Auth Check]
    AUTH_CHECK --> AUTH_OK{Authenticated?}
    AUTH_OK -->|No| UNAUTH[401 Unauthorized]
    AUTH_OK -->|Yes| EXECUTE

    PERMISSION --> AUTH_CHECK_P[Auth Check]
    AUTH_CHECK_P --> AUTH_OK_P{Authenticated?}
    AUTH_OK_P -->|No| UNAUTH
    AUTH_OK_P -->|Yes| PERM_CHECK[Permission Check]

    PERM_CHECK --> HAS_PERM{Has Permission?}
    HAS_PERM -->|No| FORBIDDEN[403 Forbidden]
    HAS_PERM -->|Yes| EXECUTE

    EXECUTE --> RESPONSE[Return Response]

    style EXECUTE fill:#e8f5e9
    style UNAUTH fill:#ffebee
    style FORBIDDEN fill:#ffebee

flowchart TD
    ACTION[Permission Action] --> CAPTURE[Capture Details]

    CAPTURE --> LOG_ENTRY[Audit Log Entry]

    LOG_ENTRY --> WHO[Who: adminUserId]
    LOG_ENTRY --> WHAT[What: action type]
    LOG_ENTRY --> TARGET[Target: userId, roleId]
    LOG_ENTRY --> WHEN[When: timestamp]
    LOG_ENTRY --> RESULT[Result: success/failure]

    WHO --> STORE[Store Audit Log]
    WHAT --> STORE
    TARGET --> STORE
    WHEN --> STORE
    RESULT --> STORE

    subgraph "Audited Actions"
        ROLE_ASSIGN[Role Assignment]
        ROLE_REVOKE[Role Revocation]
        PERM_CHANGE[Permission Change]
        ACCESS_DENIED[Access Denied Events]
    end