@jmruthers/pace-core 0.5.180 → 0.5.182

package/docs/architecture/README.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T16:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # PACE Core Architecture
@@ -576,3 +576,49 @@ PACE Core supports tree shaking for optimal bundle sizes and provides multiple i
 - **Performance Profiling**: Built-in performance profiling tools
 
 This architecture provides a solid foundation for building scalable, secure, and maintainable applications with PACE Core. The modular design allows for easy extension and customization while maintaining consistency and reliability.
+
+## ♿ Accessibility
+
+The PACE Core architecture is designed with accessibility in mind:
+
+- **WCAG 2.1 AA compliance** - All components meet accessibility standards
+- **Screen Reader Support** - Proper ARIA labels and semantic HTML
+- **Keyboard Navigation** - Full keyboard support for all interactive elements
+- **Focus Management** - Proper focus handling throughout the application
+- **Color Contrast** - All colors meet WCAG contrast requirements
+
+### Accessibility Architecture
+
+1. **Component Level** - All UI components include accessibility features
+2. **Provider Level** - Context providers manage accessibility state
+3. **Hook Level** - Hooks provide accessibility utilities
+4. **Utility Level** - Accessibility helpers for common patterns
+
+## ⚠️ Edge Cases
+
+### Architecture Scalability
+
+When scaling the architecture:
+- Monitor provider performance with many components
+- Consider code splitting for large applications
+- Use lazy loading for heavy components
+- Optimize bundle sizes with tree-shaking
+- Profile performance regularly
+
+### Multi-Tenant Architecture
+
+When working with multiple tenants:
+- Ensure proper organisation context isolation
+- Verify RLS policies are correctly configured
+- Test cross-tenant data access prevention
+- Monitor resource usage per tenant
+- Implement proper caching strategies
+
+### Service Integration Issues
+
+When services fail to integrate:
+- Verify service initialization order
+- Check provider hierarchy is correct
+- Ensure all dependencies are available
+- Review service lifecycle management
+- Test error handling and recovery

package/docs/architecture/database-schema-requirements.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T16:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Database Schema Requirements
@@ -176,3 +176,40 @@ AND tablename = 'rbac_organisation_roles';
 -- Test membership view
 SELECT * FROM user_organisation_memberships LIMIT 5;
 ```
+
+## ♿ Accessibility
+
+Database schema requirements don't directly impact accessibility, but ensure:
+
+- **Error messages are accessible** - Database errors should be clearly communicated
+- **Data validation** - Ensure data validation doesn't break accessibility features
+- **Performance** - Database performance impacts user experience and accessibility
+
+## ⚠️ Edge Cases
+
+### Schema Migration Issues
+
+When migrating database schema:
+- Test migrations on staging environment first
+- Ensure backward compatibility during migration
+- Have rollback plan ready
+- Verify all indexes are created correctly
+- Check RLS policies are applied correctly
+
+### Missing Required Tables
+
+When required tables are missing:
+- Verify all migrations have been applied
+- Check database connection is correct
+- Ensure user has proper permissions
+- Review migration logs for errors
+- Test with minimal schema setup
+
+### Schema Version Mismatches
+
+When schema versions don't match:
+- Verify pace-core version matches schema version
+- Check migration history for missing migrations
+- Ensure all consuming apps use compatible versions
+- Review breaking changes in migration guides
+- Test with compatible schema version

package/docs/architecture/rbac-security-architecture.md

@@ -1,12 +1,12 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T16:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # RBAC Security Architecture
 
-**Last Updated**: 2024
+**Last Updated**: 2025-01-28
 
 ## Overview
 
@@ -256,3 +256,40 @@ Caching improves performance but must be secure:
 - [RBAC Implementation](rbac-implementation.md)
 - [RLS Policies](../migration/rls-policies.md)
 - [Security Testing](../testing/security-testing.md)
+
+## ♿ Accessibility
+
+RBAC security architecture doesn't directly impact accessibility, but ensure:
+
+- **Permission errors are accessible** - Error messages should be clearly communicated
+- **Loading states are announced** - Screen readers should announce permission checks
+- **Focus management** - Ensure focus is properly managed during permission checks
+
+## ⚠️ Edge Cases
+
+### Permission Check Failures
+
+When permission checks fail:
+- Verify RLS policies are correctly configured
+- Check organisation context is properly set
+- Ensure user has required roles assigned
+- Review audit logs for permission denials
+- Test with different user roles
+
+### Super Admin Bypass Issues
+
+When super admin bypass doesn't work:
+- Verify super admin status is correctly detected
+- Check global roles table is accessible
+- Ensure JWT claims are properly set
+- Review audit logs for bypass attempts
+- Test with known super admin user
+
+### Cross-Organisation Data Leakage
+
+When data leaks between organisations:
+- Verify RLS policies are enforced
+- Check organisation context is required
+- Ensure all queries include organisation filter
+- Review database logs for unauthorized access
+- Test with users from different organisations

package/docs/architecture/services.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T16:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Service Architecture Documentation
@@ -12,8 +12,16 @@ The pace-core library now uses a service-based architecture that follows SOLID p
 
 ## Architecture Design
 
+The service architecture follows a **three-layer pattern** that separates concerns and provides clear boundaries:
+
+1. **Service Layer** (`src/services/`) - Pure TypeScript classes with business logic
+2. **Provider Layer** (`src/providers/services/`) - React context providers for dependency injection
+3. **Hook Layer** (`src/hooks/services/`) - React hooks for reactive component integration
+
 ### Service Layer (Pure TypeScript Classes)
 
+**Location**: `packages/core/src/services/`
+
 The service layer contains pure TypeScript classes that handle business logic without any React dependencies:
 
 - **AuthService**: Authentication operations (sign in, sign out, session management)
@@ -24,19 +32,36 @@ The service layer contains pure TypeScript classes that handle business logic wi
 
 > **⚠️ Note**: RBACService is deprecated in favor of the new RBAC system. Use `useRBAC()` from `@jmruthers/pace-core/rbac` instead.
 
+**Key Characteristics**:
+- No React dependencies
+- Pure TypeScript classes
+- Observable pattern for state changes
+- Easy to unit test
+- Reusable across different frameworks
+
 ### Provider Layer (React Context)
 
+**Location**: `packages/core/src/providers/services/`
+
 Each service has its own React provider that:
-- Creates and manages service instances
+- Creates and manages service instances (singleton pattern)
 - Provides services to React components via context
 - Handles service lifecycle (initialization, cleanup)
+- Updates service dependencies when props change
+
+**Important**: Providers do **not** export hooks. Hooks are exported from the hook layer.
 
 ### Hook Layer (React Integration)
 
+**Location**: `packages/core/src/hooks/services/`
+
 Each service has corresponding hooks that:
 - Access services from context
-- Subscribe to service state changes
+- Subscribe to service state changes using the observable pattern
 - Trigger React re-renders when state changes
+- Provide reactive access to service state
+
+**⚠️ Critical**: Always import service hooks from `hooks/services/`, **not** from `providers/services/`. The hooks in `hooks/services/` include state subscription logic that ensures components re-render when service state changes.
 
 ## Service Interfaces
 
@@ -128,28 +153,27 @@ function MyComponent() {
 
 ### Using Individual Service Hooks
 
+**✅ Correct**: Import hooks from the main package (which exports from `hooks/services/`):
+
 ```tsx
 import { 
   useAuthService,
   useOrganisationService,
   useEventService,
-  useRBACService 
+  useInactivityService
 } from '@jmruthers/pace-core';
 
 function MyComponent() {
   const authService = useAuthService();
   const orgService = useOrganisationService();
   const eventService = useEventService();
-  const rbacService = useRBACService();
   
   return (
     <div>
       {authService.isAuthenticated() && (
         <div>
           <h1>{orgService.getSelectedOrganisation()?.display_name}</h1>
-          {rbacService.hasPermission('events:read') && (
-            <EventList events={eventService.getEvents()} />
-          )}
+          <EventList events={eventService.getEvents()} />
         </div>
       )}
     </div>
@@ -157,6 +181,13 @@ function MyComponent() {
 }
 ```
 
+**❌ Incorrect**: Do not import hooks directly from provider files. Provider files only export the provider component and context, not hooks.
+
+```tsx
+// ❌ DON'T DO THIS
+import { useEventService } from '@jmruthers/pace-core/providers/services/EventServiceProvider';
+```
+
 ## Testing
 
 ### Unit Tests for Services
@@ -276,56 +307,73 @@ All providers use the service-based architecture:
 
 ## File Structure
 
+The service architecture is organized into three distinct layers:
+
 ```
 packages/core/src/
-├── services/
-│   ├── interfaces/
+├── services/                          # Layer 1: Service Classes
+│   ├── interfaces/                    # Service interfaces (contracts)
 │   │   ├── IAuthService.ts
-│   │   ├── IRBACService.ts
 │   │   ├── IOrganisationService.ts
 │   │   ├── IEventService.ts
 │   │   └── IInactivityService.ts
 │   ├── base/
-│   │   └── BaseService.ts
-│   ├── AuthService.ts
-│   ├── RBACService.ts
-│   ├── OrganisationService.ts
-│   ├── EventService.ts
-│   ├── InactivityService.ts
-│   └── __tests__/
-│       ├── AuthService.test.ts
-│       └── RBACService.test.ts
+│   │   └── BaseService.ts            # Base class with observable pattern
+│   ├── AuthService.ts                 # Pure TypeScript service class
+│   ├── OrganisationService.ts        # Pure TypeScript service class
+│   ├── EventService.ts                # Pure TypeScript service class
+│   ├── InactivityService.ts           # Pure TypeScript service class
+│   └── __tests__/                     # Service unit tests
+│
 ├── providers/
-│   └── services/
-│       ├── AuthServiceProvider.tsx
-│       ├── RBACServiceProvider.tsx
+│   └── services/                      # Layer 2: React Context Providers
+│       ├── AuthServiceProvider.tsx    # Creates AuthService, provides via context
 │       ├── OrganisationServiceProvider.tsx
 │       ├── EventServiceProvider.tsx
 │       ├── InactivityServiceProvider.tsx
-│       ├── NewUnifiedAuthProvider.tsx
-│       └── __tests__/
-│           ├── AuthServiceProvider.integration.test.tsx
-│           └── NewUnifiedAuthProvider.integration.test.tsx
+│       ├── UnifiedAuthProvider.tsx    # Composes multiple service providers
+│       └── __tests__/                 # Provider integration tests
+│
 └── hooks/
-    └── services/
-        ├── useAuthService.ts
-        ├── useRBACService.ts
-        ├── useOrganisationService.ts
-        ├── useEventService.ts
-        ├── useInactivityService.ts
-        ├── useAuth.ts
-        ├── usePermissions.ts
-        ├── useCurrentOrganisation.ts
-        └── useCurrentEvent.ts
+    └── services/                      # Layer 3: React Hooks (EXPORT THESE)
+        ├── useAuthService.ts          # ✅ Import hooks from here
+        ├── useOrganisationService.ts  # ✅ Subscribes to service state changes
+        ├── useEventService.ts         # ✅ Triggers re-renders on updates
+        ├── useInactivityService.ts    # ✅ Provides reactive access
+        ├── useAuth.ts                 # Convenience hook wrapper
+        ├── useCurrentOrganisation.ts  # Convenience hook wrapper
+        └── useCurrentEvent.ts        # Convenience hook wrapper
+```
+
+### Import Guidelines
+
+**✅ DO**: Import service hooks from the main package or hooks/services:
+```tsx
+import { useEventService } from '@jmruthers/pace-core';
+// or
+import { useEventService } from '@jmruthers/pace-core/hooks/services/useEventService';
+```
+
+**❌ DON'T**: Import hooks from provider files:
+```tsx
+// ❌ Provider files don't export hooks
+import { useEventService } from '@jmruthers/pace-core/providers/services/EventServiceProvider';
+```
+
+**✅ DO**: Import providers when setting up your app:
+```tsx
+import { EventServiceProvider } from '@jmruthers/pace-core';
 ```
 
 ## Best Practices
 
 ### 1. Service Usage
 
-- Use individual service hooks for better performance
-- Use convenience hooks for common patterns
-- Use the unified provider for backward compatibility
+- **Import hooks from `hooks/services/`** (or main package export) - these include state subscription logic
+- Use individual service hooks for better performance and granular control
+- Use convenience hooks (like `useEvents`, `useOrganisations`) for common patterns
+- Use the unified provider (`UnifiedAuthProvider`) for backward compatibility and simpler setup
+- **Never import hooks from provider files** - providers only export the provider component and context types
 
 ### 2. Testing
 
@@ -378,3 +426,40 @@ When contributing to the service architecture:
 2. **Write tests**: Include unit and integration tests
 3. **Document changes**: Update documentation for new features
 4. **Maintain compatibility**: Ensure backward compatibility when possible
+
+## ♿ Accessibility
+
+Service architecture doesn't directly impact accessibility, but ensure:
+
+- **Service errors are accessible** - Error messages should be clearly communicated
+- **Loading states are announced** - Screen readers should announce service operations
+- **Focus management** - Ensure focus is properly managed during service operations
+
+## ⚠️ Edge Cases
+
+### Service Initialization Failures
+
+When services fail to initialize:
+- Verify all dependencies are available
+- Check provider hierarchy is correct
+- Ensure Supabase client is properly configured
+- Review service lifecycle management
+- Test with minimal service setup
+
+### Service State Synchronization Issues
+
+When service state gets out of sync:
+- Verify state updates are properly propagated
+- Check for race conditions in async operations
+- Ensure cache invalidation is working correctly
+- Review service state management
+- Test with concurrent operations
+
+### Deprecated Service Usage
+
+When using deprecated services:
+- Review migration guides for replacement services
+- Update code to use new service APIs
+- Test thoroughly after migration
+- Remove deprecated service code
+- Update documentation references

package/docs/best-practices/README.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T17:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Best Practices
@@ -31,8 +31,7 @@ Comprehensive best practices for building secure, performant, and maintainable a
 - [**Accessibility Guide**](./accessibility.md) - WCAG compliance and inclusive design
 
 ### Performance
-- [**Performance Optimization**](./performance.md) - Basic optimization strategies
-- [**Advanced Performance**](./performance-expansion.md) - Advanced optimization techniques
+- [**Performance Optimization**](./performance.md) - Comprehensive performance optimization strategies
 
 ### Testing
 - [**Testing Best Practices**](./testing.md) - Testing strategies and patterns
@@ -424,3 +423,50 @@ import { z } from 'zod';
 - [Troubleshooting Guide](../troubleshooting/) - Common issues and solutions
 
 Remember: **Best practices are guidelines, not rules. Adapt them to your specific needs and constraints.**
+
+## ♿ Accessibility
+
+All best practices should consider accessibility:
+
+- **WCAG 2.1 AA compliance** - Ensure all practices maintain accessibility standards
+- **Screen Reader Support** - Verify practices don't break screen reader functionality
+- **Keyboard Navigation** - Ensure practices don't affect keyboard accessibility
+- **Error Announcements** - Ensure error messages are accessible
+- **Focus Management** - Verify focus handling remains correct
+
+### Accessibility Best Practices
+
+1. **Test with screen readers** - Verify practices work with assistive technologies
+2. **Check error announcements** - Ensure error messages are properly announced
+3. **Maintain keyboard access** - Verify all interactive elements remain keyboard accessible
+4. **Preserve semantic structure** - Don't break semantic HTML with optimizations
+5. **Test focus management** - Ensure focus handling remains correct
+
+## ⚠️ Edge Cases
+
+### Best Practices Conflicts
+
+When best practices conflict:
+- Prioritize security over performance when necessary
+- Balance accessibility with design requirements
+- Consider trade-offs between maintainability and optimization
+- Document decisions when deviating from best practices
+- Test thoroughly when combining multiple practices
+
+### Performance vs Accessibility
+
+When performance optimizations impact accessibility:
+- Ensure lazy loading doesn't break screen reader navigation
+- Verify code splitting maintains keyboard navigation
+- Check that memoization doesn't affect focus management
+- Test with assistive technologies after optimizations
+- Balance performance gains with accessibility requirements
+
+### Security vs Usability
+
+When security practices impact usability:
+- Find balance between security and user experience
+- Provide clear error messages without exposing vulnerabilities
+- Implement security measures transparently
+- Test with real users to ensure usability
+- Document security decisions for future reference

package/docs/best-practices/accessibility.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T17:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Best Practices: Accessibility
@@ -570,3 +570,32 @@ PACE Core components are designed to meet WCAG 2.1 Level AA standards:
 ---
 
 **Next Steps**: Review your application's accessibility, implement missing ARIA attributes, and test with screen readers.
+
+## ⚠️ Edge Cases
+
+### Accessibility vs Performance
+
+When accessibility features impact performance:
+- Optimize ARIA live regions to reduce re-renders
+- Use efficient focus management techniques
+- Balance screen reader announcements with performance
+- Test performance with assistive technologies enabled
+- Profile accessibility features for bottlenecks
+
+### Complex Accessibility Scenarios
+
+When dealing with complex accessibility requirements:
+- Test with multiple screen reader combinations
+- Verify keyboard navigation in complex UIs
+- Ensure focus management in dynamic content
+- Test with different assistive technology configurations
+- Document accessibility patterns for complex components
+
+### Third-Party Component Accessibility
+
+When using third-party components:
+- Verify third-party components meet accessibility standards
+- Add wrapper components for accessibility improvements
+- Test third-party integrations with assistive technologies
+- Document accessibility limitations
+- Provide alternatives when components aren't accessible

package/docs/best-practices/common-patterns.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T17:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Common Patterns & Best Practices
@@ -467,3 +467,50 @@ function DeleteConfirmation({ item, onConfirm }) {
 - **[Implementation Guides](./implementation-guides/)** - Explore specific features
 - **[API Reference](./api-reference/components.md)** - Component documentation
 
+## ♿ Accessibility
+
+Common patterns should maintain accessibility:
+
+- **Patterns include accessibility features** - All patterns should consider accessibility
+- **Keyboard navigation is supported** - Patterns should support keyboard navigation
+- **Screen reader compatibility** - Patterns should work with screen readers
+- **Focus management** - Patterns should handle focus correctly
+- **ARIA labels are included** - Patterns should include proper ARIA labels
+
+### Accessibility Best Practices
+
+1. **Test patterns with screen readers** - Verify patterns work with assistive technologies
+2. **Ensure keyboard access** - All patterns should be keyboard accessible
+3. **Include ARIA labels** - Patterns should have proper ARIA attributes
+4. **Test focus management** - Verify focus handling in patterns
+5. **Document accessibility requirements** - Include accessibility in pattern documentation
+
+## ⚠️ Edge Cases
+
+### Pattern Conflicts
+
+When patterns conflict:
+- Document pattern trade-offs
+- Provide guidance on pattern selection
+- Test pattern combinations
+- Verify patterns work together
+- Consider pattern alternatives
+
+### Pattern Scalability
+
+When patterns don't scale:
+- Test patterns with large datasets
+- Verify patterns work with many components
+- Monitor pattern performance
+- Optimize patterns for scale
+- Document scalability limitations
+
+### Pattern Maintenance
+
+When patterns need updates:
+- Version pattern documentation
+- Provide migration guides
+- Test pattern updates thoroughly
+- Document breaking changes
+- Maintain backward compatibility when possible
+

package/docs/best-practices/deployment.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T17:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Deployment Best Practices
@@ -1052,6 +1052,52 @@ else
     echo "Rollback failed"
     exit 1
 fi
-```
+
+## ♿ Accessibility
+
+Deployment should maintain accessibility:
+
+- **Production builds maintain accessibility** - Verify accessibility features work in production
+- **Environment variables don't break accessibility** - Ensure accessibility settings are correct
+- **CDN caching doesn't affect accessibility** - Verify cached assets maintain accessibility
+- **Error pages are accessible** - Ensure error pages meet accessibility standards
+- **Monitoring includes accessibility metrics** - Track accessibility in production
+
+### Accessibility Best Practices
+
+1. **Test production builds with screen readers** - Verify accessibility works in production
+2. **Monitor accessibility in production** - Track accessibility metrics
+3. **Ensure error pages are accessible** - Error pages should meet WCAG standards
+4. **Test with assistive technologies** - Verify production deployment works with screen readers
+5. **Document accessibility requirements** - Include accessibility in deployment checklists
+
+## ⚠️ Edge Cases
+
+### Deployment Failures
+
+When deployment fails:
+- Have rollback plan ready
+- Test deployment procedures in staging
+- Monitor deployment logs
+- Verify all dependencies are available
+- Test with minimal configuration
+
+### Environment-Specific Issues
+
+When issues occur in specific environments:
+- Verify environment variables are correct
+- Check build configuration matches environment
+- Ensure all services are available
+- Test with environment-specific data
+- Review environment differences
+
+### Rollback Scenarios
+
+When rollback is needed:
+- Have automated rollback procedures
+- Test rollback in staging environment
+- Verify data integrity after rollback
+- Document rollback steps clearly
+- Monitor system after rollback
 
 For more information about deploying your application, see the [Security Guide](./security.md) and [Performance Guide](./performance.md).