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}
• Settings sections: settings:{section_name}
• Admin features: admin:{feature}

Examples:

• access:products - Can access the Products page
• settings:user_management - Can access User Management settings
• admin:debug - Can see debug information

Permission Components

PermissionGuard

The core component that conditionally renders content based on permissions.

<PermissionGuard 
  permission="settings:user_management"
  fallback={<p>No permission</p>}
>
  <button>Manage Users</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="settings:global"
>
  {/* Settings content */}
</SettingsSection>

Permission Hooks

usePermissions

Core hook for checking any permission.

const { hasPermission, hasPageAccess, isAdmin } = usePermissions();
if (hasPermission('settings:user_management')) {
  // Can access user management
}

usePagePermission

Specialized hook for page-level permissions.

const { canView, canCreate, canEdit, canDelete } = usePagePermission('products');
if (canView()) {
  // Can view 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.

Implemented Permission Codes

Page Access Permissions

Code	Description
access:dashboard	Access to Dashboard page
access:overview	Access to Overview page
access:products	Access to Products page
access:categories	Access to Categories page
access:brands	Access to Brands page
access:vendors	Access to Vendors page
access:purchase_orders	Access to Purchase Orders page
access:analytics	Access to Analytics page
access:forecasting	Access to Forecasting page
access:import	Access to Import page
access:settings	Access to Settings page
access:chat	Access to Chat Archive page

Settings Permissions

Code	Description
settings:global	Access to Global Settings section
settings:products	Access to Product Settings section
settings:vendors	Access to Vendor Settings section
settings:data_management	Access to Data Management settings
settings:calculation_settings	Access to Calculation Settings
settings:library_management	Access to Image Library Management
settings:performance_metrics	Access to Performance Metrics
settings:prompt_management	Access to AI Prompt Management
settings:stock_management	Access to Stock Management
settings:templates	Access to Template Management
settings:user_management	Access to User Management

Admin Permissions

Code	Description
admin:debug	Can see debug information and features

Implementation Examples

Page Protection

In App.tsx:

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

Component Level Protection

const { hasPermission } = usePermissions();

function handleAction() {
  if (!hasPermission('settings:user_management')) {
    toast.error("You don't have permission");
    return;
  }
  // Action logic
}

UI Element Protection

<PermissionGuard permission="settings:user_management">
  <button onClick={handleManageUsers}>
    Manage Users
  </button>
</PermissionGuard>

Notes

• Page Access: These permissions control which pages a user can navigate to
• Settings Access: These permissions control access to different sections within the Settings page
• Admin Features: Special permissions for administrative functions
• CRUD Operations: The application currently focuses on viewing and managing data rather than creating/editing/deleting individual records
• User Management: User CRUD operations are handled through the settings interface rather than dedicated user management pages