@jmruthers/pace-core 0.6.1 → 0.6.3

package/docs/migration/service-architecture.md

@@ -1,281 +0,0 @@
----
-lastUpdated: 2025-11-18T21:00:00+11:00
-version: 0.5.181
-reviewedBy: documentation-standards-audit
----
-
-# Provider Architecture: Service-Based Design
-
-## Overview
-
-pace-core now uses a **service-based architecture** for all providers. This provides better testability, maintainability, and follows SOLID principles by separating business logic (services) from React context (providers).
-
-## Architecture Benefits
-
-- **Separation of Concerns**: Business logic in pure TypeScript services
-- **Better Testability**: Services can be tested without React
-- **Improved Performance**: Services instantiated once and reused
-- **Type Safety**: Full TypeScript support with clear interfaces
-
-## Quick Start
-
-### Basic Usage
-
-```tsx
-import { UnifiedAuthProvider, useUnifiedAuth } from '@jmruthers/pace-core';
-
-function App() {
-  return (
-    <UnifiedAuthProvider
-      supabaseClient={supabase}
-      appName="MY_APP"
-      idleTimeoutMs={30 * 60 * 1000} // 30 minutes
-      warnBeforeMs={60 * 1000} // 60 seconds
-      onIdleLogout={() => {
-        // Handle idle logout - redirect to login
-        window.location.href = '/login';
-      }}
-    >
-      <YourAppContent />
-    </UnifiedAuthProvider>
-  );
-}
-```
-
-### Using Hooks
-
-```tsx
-import { useUnifiedAuth, useEvents, useOrganisations } from '@jmruthers/pace-core';
-
-function MyComponent() {
-  const { user, isAuthenticated, signOut } = useUnifiedAuth();
-  const { events, selectedEvent, setSelectedEvent } = useEvents();
-  const { selectedOrganisation, organisations } = useOrganisations();
-  
-  // Use the hooks as needed
-}
-```
-
-## Service Architecture Overview
-
-### Three-Layer Architecture
-
-The service architecture follows a clear three-layer pattern:
-
-1. **Service Layer** (`src/services/`) - Pure TypeScript classes containing business logic
-   - No React dependencies
-   - Observable pattern for state changes
-   - Easy to unit test
-
-2. **Provider Layer** (`src/providers/services/`) - React context providers that create service instances
-   - Creates and manages service instances (singleton pattern)
-   - Provides services via React context
-   - Handles service lifecycle
-   - **Note**: Providers do NOT export hooks
-
-3. **Hook Layer** (`src/hooks/services/`) - React hooks for reactive component integration
-   - Access services from context
-   - Subscribe to service state changes
-   - Trigger React re-renders when state changes
-   - **⚠️ Always import hooks from here, not from providers**
-
-### Service Layer
-
-Each service is a pure TypeScript class:
-
-```typescript
-class AuthService extends BaseService {
-  signIn(email: string, password: string): Promise<AuthResult> { /* ... */ }
-  signOut(): Promise<AuthResult> { /* ... */ }
-  // ... other methods
-}
-```
-
-### Provider Layer
-
-Service providers create and manage service instances:
-
-```tsx
-function AuthServiceProvider({ children, supabaseClient }) {
-  const authService = useMemo(() => new AuthService(supabaseClient), [supabaseClient]);
-  // Initialize and manage service lifecycle
-  return <AuthServiceContext.Provider value={{ authService }}>{children}</AuthServiceContext.Provider>;
-}
-```
-
-### Hook Layer
-
-Convenience hooks provide easy access to services:
-
-```tsx
-function useAuth() {
-  const context = useContext(AuthServiceContext);
-  return context.authService;
-}
-```
-
-## Available Hooks
-
-### Unified Hook (Recommended for Most Use Cases)
-
-```tsx
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-
-function MyComponent() {
-  const { 
-    user, 
-    isAuthenticated, 
-    signOut,
-    selectedOrganisation,
-    events,
-    selectedEvent,
-    permissions,
-    hasRole,
-    hasPermission
-  } = useUnifiedAuth();
-  
-  // Access all features from one hook
-}
-```
-
-### Individual Service Hooks (For Performance)
-
-For better performance, use individual service hooks:
-
-```tsx
-import { 
-  useEvents, 
-  useOrganisations, 
-  useAuthService,
-  useEventService,
-  useOrganisationService
-} from '@jmruthers/pace-core';
-
-function MyComponent() {
-  const events = useEvents();              // Convenience hook
-  const orgs = useOrganisations();         // Convenience hook
-  const authService = useAuthService();    // Direct service hook
-  const eventService = useEventService();   // Direct service hook
-  
-  // Only re-renders when relevant service state changes
-}
-```
-
-**Important**: Service hooks (like `useAuthService`, `useEventService`) are exported from `hooks/services/` and include state subscription logic. Always import them from the main package or `hooks/services/`, never from `providers/services/`.
-
-## Testing
-
-### Testing Services
-
-Services are pure TypeScript classes, making them easy to unit test:
-
-```typescript
-describe('AuthService', () => {
-  let authService: AuthService;
-  
-  beforeEach(() => {
-    authService = new AuthService(mockSupabase);
-  });
-  
-  it('should sign in user', async () => {
-    const result = await authService.signIn('test@example.com', 'password');
-    expect(result.user).toBeDefined();
-  });
-});
-```
-
-### Testing Providers
-
-Providers can be tested with React Testing Library:
-
-```typescript
-render(
-  <UnifiedAuthProvider
-    supabaseClient={mockSupabase}
-    appName="TEST_APP"
-    idleTimeoutMs={30000}
-    warnBeforeMs={5000}
-    onIdleLogout={() => {}}
-  >
-    <TestComponent />
-  </UnifiedAuthProvider>
-);
-```
-
-## Common Issues
-
-### Missing Required Props
-
-**Error**: `Missing required prop: idleTimeoutMs`
-
-Add the required inactivity management props:
-
-```tsx
-<UnifiedAuthProvider
-  supabaseClient={supabase}
-  appName="MY_APP"
-  idleTimeoutMs={30 * 60 * 1000}
-  warnBeforeMs={60 * 1000}
-  onIdleLogout={() => window.location.href = '/login'}
->
-  <YourAppContent />
-</UnifiedAuthProvider>
-```
-
-## Performance Tips
-
-1. **Use individual hooks** when you only need specific data
-2. **Avoid unnecessary re-renders** by selecting only what you need
-3. **Memoize expensive computations** in components
-4. **Test services in isolation** for better unit tests
-
-## Additional Resources
-
-- [API Reference](../../api-reference/providers.md)
-- [Architecture Documentation](../../architecture/services.md)
-- [Example Apps](../../getting-started/examples/)
-
-## ♿ Accessibility
-
-Service architecture migration should maintain accessibility:
-
-- **Accessibility testing after migration** - Verify all components remain accessible after migration
-- **Screen reader compatibility** - Test with assistive technologies after migration
-- **Keyboard navigation** - Ensure keyboard navigation still works after migration
-- **Focus management** - Verify focus management is correct after migration
-
-### Accessibility Best Practices
-
-1. **Test accessibility after migration** - Run accessibility tests after each migration step
-2. **Verify keyboard navigation** - Ensure all interactive elements remain keyboard accessible
-3. **Test with screen readers** - Verify components work with assistive technologies
-4. **Check focus indicators** - Ensure focus indicators are visible and correct
-
-## ⚠️ Edge Cases
-
-### Service Initialization Failures
-
-When services fail to initialize:
-- Verify all required props are provided
-- Check Supabase client is properly configured
-- Review service dependencies
-- Test with minimal configuration
-- Verify environment variables are set correctly
-
-### Service Context Not Available
-
-When service context is not available:
-- Verify service provider is properly mounted
-- Check provider order and hierarchy
-- Review service provider composition
-- Test with service provider examples
-- Verify hooks are called within provider context
-
-### Performance Issues After Migration
-
-When performance degrades after migration:
-- Check for unnecessary re-renders
-- Review service instance creation
-- Verify memoization is working correctly
-- Test with performance profiling tools
-- Consider using individual hooks instead of unified hook