inventory/docs/PERMISSIONS.md

Permission System Documentation

This document outlines the permission system implemented in the Inventory Manager application.

Permission Structure

Permissions follow this naming convention:

• Page access: access:{page_name}
• Actions: {action}:{resource}

Examples:

• access:products - Can access the Products page
• create:products - Can create new products
• edit:users - Can edit user accounts

Permission Components

PermissionGuard

The core component that conditionally renders content based on permissions.

<PermissionGuard 
  permission="create:products"
  fallback={<p>No permission</p>}
>
  <button>Create Product</button>
</PermissionGuard>

Options:

• permission: Single permission code
• anyPermissions: Array of permissions (ANY match grants access)
• allPermissions: Array of permissions (ALL required)
• adminOnly: For admin-only sections
• page: Page name (checks access:{page} permission)
• fallback: Content to show if permission check fails

PermissionProtectedRoute

Protects entire pages based on page access permissions.

<Route path="/products" element={
  <PermissionProtectedRoute page="products">
    <Products />
  </PermissionProtectedRoute>
} />

ProtectedSection

Protects sections within a page based on action permissions.

<ProtectedSection page="products" action="create">
  <button>Add Product</button>
</ProtectedSection>

PermissionButton

Button that automatically handles permissions.

<PermissionButton 
  page="products" 
  action="create"
  onClick={handleCreateProduct}
>
  Add Product
</PermissionButton>

SettingsSection

Specific component for settings with built-in permission checks.

<SettingsSection
  title="System Settings"
  description="Configure global settings"
  permission="edit:system_settings"
>
  {/* Settings content */}
</SettingsSection>

Permission Hooks

usePermissions

Core hook for checking any permission.

const { hasPermission, hasPageAccess, isAdmin } = usePermissions();
if (hasPermission('delete:products')) {
  // Can delete products
}

usePagePermission

Specialized hook for page-level permissions.

const { canView, canCreate, canEdit, canDelete } = usePagePermission('products');
if (canEdit()) {
  // Can edit products
}

Database Schema

Permissions are stored in the database:

• permissions table: Stores all available permissions
• user_permissions junction table: Maps permissions to users

Admin users automatically have all permissions.

Common Permission Codes

Code	Description
access:dashboard	Access to Dashboard page
access:products	Access to Products page
create:products	Create new products
edit:products	Edit existing products
delete:products	Delete products
view:users	View user accounts
edit:users	Edit user accounts
manage:permissions	Assign permissions to users

Implementation Examples

Page Protection

In App.tsx:

<Route path="/products" element={
  <PermissionProtectedRoute page="products">
    <Products />
  </PermissionProtectedRoute>
} />

Component Level Protection

const { canEdit } = usePagePermission('products');

function handleEdit() {
  if (!canEdit()) {
    toast.error("You don't have permission");
    return;
  }
  // Edit logic
}

UI Element Protection

<PermissionButton 
  page="products" 
  action="delete"
  onClick={handleDelete}
>
  Delete
</PermissionButton>