@jmruthers/pace-core 0.5.186 → 0.5.188

package/docs/rbac/README.md

@@ -96,7 +96,7 @@ The RBAC system uses a **database-first architecture** where all permission logi
 ## 🎯 Key Features
 
 - **🔐 Secure by Default** - Organisation context enforced, RLS integrated, database-first API
-- **⚡ High Performance** - Intelligent caching with 60s TTL, optimized RPC calls
+- **⚡ High Performance** - Intelligent two-tier caching (60s + 5min), request deduplication, batched audit logging, optimized RPC calls
 - **🎨 React Integration** - Hooks and components for easy UI integration
 - **🔄 Real-time Updates** - Automatic cache invalidation on permission changes
 - **📊 Audit Logging** - Complete audit trail for all permission checks
@@ -422,6 +422,7 @@ When database connection is lost:
 - **[API Reference](./api-reference.md)** - Explore all available APIs
 - **[Examples](./examples.md)** - See real-world usage patterns
 - **[Advanced Patterns](./advanced-patterns.md)** - Learn optimization techniques
+- **[Performance Guide](./performance.md)** - Performance optimizations and configuration
 
 ## 🆘 Need Help?
 

package/docs/rbac/api-reference.md

@@ -331,6 +331,17 @@ function UsersPage() {
 
 4. **Error Handling**: If permission check fails, the component shows the `fallback`. Check browser console for `[PagePermissionGuard]` logs to debug issues.
 
+#### Performance Optimizations
+
+`PagePermissionGuard` includes built-in performance optimizations:
+
+- **Request Deduplication**: Multiple instances checking the same permission share network requests
+- **Enhanced Caching**: Two-tier caching (60s short-term + 5min session cache for page-level checks)
+- **Batched Audit Logging**: Audit events are automatically batched to reduce network requests
+- **Memoization**: Component is memoized with deep equality checks to prevent unnecessary re-renders
+
+These optimizations reduce network requests from 1,200+ to <50 per page load. See [RBAC Performance Guide](../rbac/performance.md) for details.
+
 ### NavigationGuard
 
 Conditionally render navigation items based on permissions.

package/docs/rbac/performance.md

@@ -0,0 +1,320 @@
+---
+lastUpdated: 2025-01-26T00:00:00+11:00
+version: 0.5.186
+reviewedBy: documentation-standards-audit
+---
+
+# RBAC Performance Optimizations
+
+> **📚 RBAC Performance Guide** | [← Back to RBAC Documentation](./README.md) | [API Reference](./api-reference.md)
+
+The RBAC system includes comprehensive performance optimizations to minimize network requests and improve page load times. This guide explains how these optimizations work and how to configure them.
+
+## Overview
+
+The RBAC performance optimizations address the common issue of excessive network requests when using `PagePermissionGuard` and other RBAC components. Without optimizations, a single page load could generate 1,200+ network requests. With optimizations enabled, this is reduced to <50 requests per page load.
+
+## Performance Features
+
+### 1. Request Deduplication
+
+**Problem**: Multiple components checking the same permission simultaneously make separate network requests.
+
+**Solution**: Request deduplication shares in-flight permission check requests across all components. When multiple `PagePermissionGuard` instances check the same permission at the same time, they share a single network request.
+
+**How it works**:
+- When a permission check is requested, the system checks if an identical request is already in-flight
+- If found, the existing promise is returned instead of making a new request
+- The deduplication map is automatically cleaned up when requests complete
+
+**Example**:
+```tsx
+// Three components checking the same permission
+<PagePermissionGuard pageName="dashboard" operation="read">
+  <Component1 />
+</PagePermissionGuard>
+<PagePermissionGuard pageName="dashboard" operation="read">
+  <Component2 />
+</PagePermissionGuard>
+<PagePermissionGuard pageName="dashboard" operation="read">
+  <Component3 />
+</PagePermissionGuard>
+// Result: Only 1 network request instead of 3
+```
+
+**Configuration**: Enabled by default. Can be disabled via configuration:
+```typescript
+setupRBAC(supabase, {
+  performance: {
+    enableRequestDeduplication: false, // Disable deduplication
+  },
+});
+```
+
+### 2. Enhanced Caching
+
+**Problem**: Short cache TTL (60 seconds) causes frequent re-checks, especially for stable page-level permissions.
+
+**Solution**: Two-tier caching strategy with session-level cache for page-level permissions.
+
+**Cache Tiers**:
+- **Short-term cache**: 60 seconds for frequently changing permissions
+- **Session cache**: 5 minutes for stable page-level permissions
+
+**How it works**:
+- Permission checks first look in the short-term cache
+- If not found, check the session cache (for page-level checks)
+- Page-level permission checks automatically use session cache
+- Cache is invalidated on user/org/event changes
+
+**Example**:
+```typescript
+// First check: Network request + cache result
+await isPermittedCached({ userId, scope, permission: 'read:page.dashboard' });
+
+// Subsequent checks within 5 minutes: Cache hit (no network request)
+await isPermittedCached({ userId, scope, permission: 'read:page.dashboard' });
+```
+
+**Configuration**:
+```typescript
+setupRBAC(supabase, {
+  cache: {
+    ttl: 60000, // Short-term cache TTL (default: 60s)
+    sessionTtl: 300000, // Session cache TTL (default: 5min)
+  },
+});
+```
+
+### 3. Batched Audit Logging
+
+**Problem**: Every permission check generates a separate audit log request, even for cached checks.
+
+**Solution**: Batched audit logging queues events and sends them in batches, and skips logging for cached checks.
+
+**How it works**:
+- Audit events are queued instead of being sent immediately
+- Events are batched by time window (default: 100ms) or batch size (default: 10 events)
+- Cached permission checks skip audit logging entirely (only cache misses are logged)
+- Batches are automatically flushed when the window expires or batch size is reached
+
+**Example**:
+```typescript
+// 10 permission checks in quick succession
+// Without batching: 10 separate audit log requests
+// With batching: 1 batched request with 10 events
+```
+
+**Configuration**:
+```typescript
+setupRBAC(supabase, {
+  audit: {
+    batched: true, // Enable batched logging (default: true)
+    batchWindow: 100, // Time window in ms (default: 100ms)
+    batchSize: 10, // Maximum batch size (default: 10)
+  },
+  performance: {
+    enableBatchedAuditLogging: true, // Enable/disable (default: true)
+  },
+});
+```
+
+### 4. Improved Memoization
+
+**Problem**: Scope objects are recreated on every render, causing unnecessary permission re-checks.
+
+**Solution**: Deep equality checks for scope objects and React.memo for components.
+
+**How it works**:
+- `PagePermissionGuard` uses `React.memo` to prevent unnecessary re-renders
+- Scope objects are compared using deep equality instead of reference equality
+- Permission strings are memoized to prevent recreation
+- Only re-check permissions when dependencies actually change
+
+**Example**:
+```tsx
+// Component re-renders with same scope object
+// Without memoization: Permission re-checked
+// With memoization: Cached result used, no re-check
+```
+
+**Configuration**: Automatic, no configuration needed.
+
+### 5. Performance Monitoring
+
+**Problem**: No visibility into performance metrics and optimization effectiveness.
+
+**Solution**: Built-in performance monitoring tracks key metrics.
+
+**Metrics Tracked**:
+- Total permission checks
+- Cache hit rate
+- Request deduplication rate
+- Network request count
+- Average response time
+- Batched vs individual audit events
+
+**Usage**:
+```typescript
+import { 
+  enablePerformanceMonitoring,
+  getPerformanceMetrics,
+  getPerformanceSummary 
+} from '@jmruthers/pace-core/rbac';
+
+// Enable monitoring
+enablePerformanceMonitoring();
+
+// Get metrics
+const metrics = getPerformanceMetrics();
+console.log('Cache hit rate:', metrics.cacheHitRate);
+console.log('Network requests:', metrics.networkRequests);
+
+// Get formatted summary
+console.log(getPerformanceSummary());
+```
+
+**Configuration**:
+```typescript
+setupRBAC(supabase, {
+  performance: {
+    enablePerformanceTracking: true, // Enable in development
+  },
+});
+```
+
+## Configuration
+
+All performance optimizations can be configured when setting up RBAC:
+
+```typescript
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+
+setupRBAC(supabase, {
+  // Cache configuration
+  cache: {
+    ttl: 60000, // Short-term cache TTL (default: 60s)
+    sessionTtl: 300000, // Session cache TTL (default: 5min)
+    enabled: true, // Enable caching (default: true)
+  },
+  
+  // Audit configuration
+  audit: {
+    enabled: true, // Enable audit logging (default: true)
+    batched: true, // Enable batched logging (default: true)
+    batchWindow: 100, // Batch time window in ms (default: 100ms)
+    batchSize: 10, // Maximum batch size (default: 10)
+  },
+  
+  // Performance configuration
+  performance: {
+    enableRequestDeduplication: true, // Enable deduplication (default: true)
+    enableBatchedAuditLogging: true, // Enable batched audit (default: true)
+    enablePerformanceTracking: false, // Enable monitoring (default: false in production)
+  },
+});
+```
+
+## Expected Performance Improvements
+
+With all optimizations enabled:
+
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| Network Requests | 1,200+ | <50 | 96% reduction |
+| Page Load Time | 1+ minute | <5 seconds | 92% reduction |
+| Bandwidth | 13+ MB | <1 MB | 92% reduction |
+| Cache Hit Rate | N/A | >90% | - |
+| Audit Log Requests | 1,200+ | <50 | 96% reduction |
+
+## Best Practices
+
+### 1. Enable All Optimizations
+
+All optimizations are enabled by default. Only disable them if you have a specific reason:
+
+```typescript
+// ✅ Good: Use defaults
+setupRBAC(supabase);
+
+// ❌ Avoid: Disabling optimizations without reason
+setupRBAC(supabase, {
+  performance: {
+    enableRequestDeduplication: false, // Only if you have a specific need
+  },
+});
+```
+
+### 2. Monitor Performance in Development
+
+Enable performance tracking during development to identify bottlenecks:
+
+```typescript
+setupRBAC(supabase, {
+  performance: {
+    enablePerformanceTracking: import.meta.env.MODE === 'development',
+  },
+});
+```
+
+### 3. Adjust Cache TTL Based on Use Case
+
+For applications with frequently changing permissions, reduce cache TTL:
+
+```typescript
+setupRBAC(supabase, {
+  cache: {
+    ttl: 30000, // 30 seconds for frequently changing permissions
+    sessionTtl: 180000, // 3 minutes for page-level checks
+  },
+});
+```
+
+### 4. Tune Batch Settings for High-Volume Apps
+
+For applications with many permission checks, adjust batch settings:
+
+```typescript
+setupRBAC(supabase, {
+  audit: {
+    batchWindow: 50, // Shorter window for faster batching
+    batchSize: 20, // Larger batches for high volume
+  },
+});
+```
+
+## Troubleshooting
+
+### High Network Request Count
+
+If you're still seeing high request counts:
+
+1. **Check cache hit rate**: Use performance monitoring to verify cache is working
+2. **Verify deduplication**: Ensure multiple components aren't bypassing deduplication
+3. **Check audit batching**: Verify batched audit logging is enabled
+4. **Review scope changes**: Ensure scope objects aren't being recreated unnecessarily
+
+### Low Cache Hit Rate
+
+If cache hit rate is low:
+
+1. **Check cache TTL**: Verify cache TTL settings are appropriate
+2. **Review cache invalidation**: Ensure cache isn't being invalidated too frequently
+3. **Verify session cache**: Check that page-level checks are using session cache
+4. **Monitor scope changes**: Frequent scope changes will reduce cache effectiveness
+
+### Performance Monitoring Not Working
+
+If performance monitoring isn't showing data:
+
+1. **Verify it's enabled**: Check `enablePerformanceTracking` is set to `true`
+2. **Check timing**: Metrics accumulate over time, check after multiple permission checks
+3. **Review console**: Check for any errors in the console
+
+## Related Documentation
+
+- [PagePermissionGuard API Reference](./api-reference.md#pagepermissionguard) - Component API
+- [RBAC Configuration](./api-reference.md#configuration) - Configuration options
+- [Performance Best Practices](../best-practices/performance.md) - General performance guide
+- [RBAC Getting Started](./getting-started.md) - Getting started guide
+

package/docs/standards/01-architecture-standard.md

@@ -11,6 +11,11 @@ Define the core architectural principles for pace-core so that components, APIs,
 - Secure by default
 - Performance-conscious
 
+## Performance Requirements
+- **RLS policies must use helper functions** - Never use subqueries in RLS policies as they cause N+1 query patterns
+- **Database migrations must be tested** - Verify migrations don't cause query timeouts or performance degradation
+- **Monitor query performance** - Use EXPLAIN ANALYZE to verify RLS policies don't create expensive execution plans
+
 ## Boundaries
 ### In scope
 - UI primitives

package/docs/standards/05-security-standard.md

@@ -13,6 +13,18 @@
 - Never store secrets in code
 - Use safe error messaging
 
+## RLS Policy Performance Rules
+- **NEVER use subqueries in RLS policies** - They execute for every row check and cause severe performance degradation
+- **ALWAYS use helper functions** - Create STABLE SECURITY DEFINER functions for lookups (e.g., `get_app_id()`, `get_form_event_id()`)
+- **Helper functions must be**:
+  - `STABLE` - Results are consistent within a transaction
+  - `SECURITY DEFINER` - Bypass RLS to avoid recursion
+  - `SET search_path TO 'public'` - Prevent search path injection
+- **Test RLS policies** - Verify they don't cause query timeouts or N+1 query patterns
+- **Monitor performance** - Watch for slow queries after RLS policy changes
+
+**See [RBAC and RLS Standard](./07-rbac-and-rls-standard.md) for detailed RLS policy patterns and helper function documentation.**
+
 ## Logging Rules
 Allowed:
 - IDs
@@ -28,3 +40,5 @@ Forbidden:
 - Ensure no sensitive logs
 - Replace raw errors with ApiError
 - Validate input shapes
+- **RLS policies use helper functions, not subqueries**
+- **Helper functions are STABLE and SECURITY DEFINER**