@jmruthers/pace-core 0.5.141 → 0.5.143

package/docs/rbac/event-based-apps.md

@@ -0,0 +1,872 @@
+---
+lastUpdated: 2025-01-27T00:00:00+00:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
+# Event-Based Apps with RBAC
+
+> **📚 RBAC System** | [← Back to Documentation](../../README.md) | [RBAC Overview](./README.md) | [Organisation-Based Quick Start](./quick-start.md)
+
+> **⚠️ CRITICAL**: This guide is designed to be impossible to get wrong. Follow every step exactly as written, and your event-based RBAC system will work perfectly.
+
+Build your first event-based RBAC-enabled application in under 10 minutes.
+
+## 🎯 What We'll Build
+
+A simple event management app that demonstrates:
+- Event-based permission checking
+- Automatic organisation resolution from event context
+- Page-level access control for event-based apps
+- Proper provider setup for event context
+- Event selection and context management
+
+## 🚨 Critical Rules (Follow These or It Won't Work)
+
+1. **ALWAYS call `setupRBAC()` first** - This is MANDATORY and must be called before any RBAC features
+2. **Never make direct database queries** to `rbac_apps`, `rbac_global_roles`, or other RBAC tables
+3. **ALWAYS use `PagePermissionGuard`** for page-level permissions - This is the ONLY way to properly protect pages
+4. **ALWAYS set up providers correctly** in the exact order shown below
+5. **Use the exact app name** from your environment variable (must match database exactly, case-sensitive)
+6. **Ensure database setup is complete** before starting the app - App must be registered with `requires_event = true`
+7. **User must have organisation role** - Users need roles assigned in `rbac_organisation_roles` table
+8. **Event must be selected** - `selectedEventId` must be set in UnifiedAuth context before permission checks
+9. **Event must belong to organisation** - The event's `organisation_id` must match the user's organisation
+
+## 🚀 Step-by-Step Implementation
+
+### 1. Project Setup
+
+If you don't have a project yet:
+
+```bash
+npx create-react-app event-manager --template typescript
+cd event-manager
+```
+
+### 2. Install Dependencies
+
+**CRITICAL**: Use the exact versions specified to avoid compatibility issues.
+
+```bash
+npm install @jmruthers/pace-core@^0.4.1 @supabase/supabase-js@^2.38.0
+npm install -D tailwindcss @types/react @types/react-dom
+```
+
+### 3. Configure Tailwind CSS v4
+
+Install Tailwind CSS v4:
+```bash
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+```
+
+Update `vite.config.ts`:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      // CRITICAL: Include pace-core components for scanning
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+### 4. Set Up Environment Variables
+
+Create `.env.local`:
+
+```bash
+# .env.local
+VITE_SUPABASE_URL=https://your-project.supabase.co
+VITE_SUPABASE_ANON_KEY=your-anon-key-here
+VITE_APP_NAME=pace-trac
+```
+
+**CRITICAL**: 
+- Use `VITE_` prefix for Vite projects
+- Use `NEXT_PUBLIC_` prefix for Next.js projects
+- The `VITE_APP_NAME` must match exactly what you have in the `rbac_apps` table
+
+### 5. Database Setup (CRITICAL)
+
+**CRITICAL**: Your app must be registered in the database as an event-based app before you can use RBAC.
+
+#### 5.1 Register Your App as Event-Based
+
+Run this SQL in your Supabase SQL editor:
+
+```sql
+-- Replace 'pace-trac' with your actual app name (must match VITE_APP_NAME)
+-- CRITICAL: requires_event = true makes this an event-based app
+INSERT INTO rbac_apps (name, display_name, requires_event, is_active) 
+VALUES ('pace-trac', 'PACE Trac', true, true)
+ON CONFLICT (name) DO UPDATE SET
+  display_name = EXCLUDED.display_name,
+  requires_event = EXCLUDED.requires_event,  -- CRITICAL: Must be true for event-based apps
+  is_active = EXCLUDED.is_active;
+
+-- Verify the app is registered correctly
+SELECT id, name, display_name, requires_event, is_active 
+FROM rbac_apps 
+WHERE name = 'pace-trac';
+-- Should return: requires_event = true, is_active = true
+```
+
+#### 5.2 Create App Pages
+
+```sql
+-- Create pages for your event-based app (replace 'pace-trac' with your actual app name)
+INSERT INTO rbac_app_pages (app_id, page_name, page_description)
+SELECT 
+  a.id,
+  unnest(ARRAY['dashboard', 'participants', 'settings', 'reports']),
+  unnest(ARRAY['Event Dashboard', 'Participant Management', 'Event Settings', 'Event Reports'])
+FROM rbac_apps a 
+WHERE a.name = 'pace-trac';
+```
+
+#### 5.3 Set Up Page Permissions
+
+**CRITICAL**: Page permissions use the format `{operation}:page.{pageName}` (e.g., `read:page.dashboard`). For event-based apps, permissions are checked against the organisation resolved from the event.
+
+```sql
+-- Set up basic permissions for each page (replace 'pace-trac' with your actual app name)
+-- IMPORTANT: Replace the organisation_id UUID with your actual organisation ID
+WITH app_pages AS (
+  SELECT ap.id as page_id, ap.page_name, a.id as app_id
+  FROM rbac_app_pages ap
+  JOIN rbac_apps a ON ap.app_id = a.id
+  WHERE a.name = 'pace-trac'
+)
+INSERT INTO rbac_page_permissions (app_page_id, operation, role_name, allowed, organisation_id)
+SELECT 
+  ap.page_id,
+  op.operation,
+  role.role_name,
+  CASE 
+    WHEN role.role_name = 'org_admin' THEN true
+    WHEN role.role_name = 'leader' AND ap.page_name != 'reports' THEN true
+    WHEN role.role_name = 'member' AND ap.page_name IN ('dashboard', 'participants') THEN true
+    ELSE false
+  END,
+  '00000000-0000-0000-0000-000000000000'::uuid -- ⚠️ REPLACE THIS with your actual organisation ID
+FROM app_pages ap
+CROSS JOIN (SELECT unnest(ARRAY['read', 'create', 'update', 'delete']) as operation) op
+CROSS JOIN (SELECT unnest(ARRAY['org_admin', 'leader', 'member']) as role_name) role;
+
+-- Verify permissions were created correctly
+SELECT 
+  a.name as app_name,
+  ap.page_name,
+  pp.operation,
+  pp.role_name,
+  pp.allowed,
+  pp.organisation_id
+FROM rbac_page_permissions pp
+JOIN rbac_app_pages ap ON pp.app_page_id = ap.id
+JOIN rbac_apps a ON ap.app_id = a.id
+WHERE a.name = 'pace-trac'
+ORDER BY ap.page_name, pp.operation, pp.role_name;
+```
+
+#### 5.4 Create a Test Event
+
+**CRITICAL**: For event-based apps, you need at least one event that belongs to your organisation.
+
+```sql
+-- Create a test event (replace with your actual organisation_id)
+INSERT INTO event (event_name, event_code, organisation_id, event_date, is_active)
+VALUES (
+  'Test Event 2025',
+  'TEST2025',
+  '00000000-0000-0000-0000-000000000000'::uuid, -- ⚠️ REPLACE THIS with your actual organisation ID
+  CURRENT_DATE + INTERVAL '30 days',
+  true
+)
+RETURNING event_id, event_name, event_code, organisation_id;
+-- Save the event_id - you'll need it for testing
+```
+
+#### 5.5 Assign User Roles
+
+```sql
+-- Grant a user the org_admin role (replace with actual user and organisation IDs)
+INSERT INTO rbac_organisation_roles (user_id, organisation_id, role, status, granted_at)
+VALUES (
+  'your-user-id'::uuid,
+  'your-organisation-id'::uuid,
+  'org_admin',
+  'active',
+  NOW()
+)
+ON CONFLICT (user_id, organisation_id) DO UPDATE SET
+  role = EXCLUDED.role,
+  status = EXCLUDED.status,
+  updated_at = NOW();
+```
+
+### 6. Create Supabase Client
+
+Create `src/lib/supabase.ts`:
+
+```typescript
+// src/lib/supabase.ts
+import { createClient } from '@supabase/supabase-js'
+
+const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
+const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY
+
+if (!supabaseUrl || !supabaseAnonKey) {
+  throw new Error('Missing Supabase environment variables')
+}
+
+export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+```
+
+### 7. Initialize RBAC (MANDATORY!)
+
+**CRITICAL**: You MUST call `setupRBAC()` before using any RBAC features. This configures rate limiting (default: 1000 requests/minute) and enables security validation.
+
+**Option 1: Setup in main entry point (Recommended)**
+
+```typescript
+// src/main.tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { setupRBAC } from '@jmruthers/pace-core/rbac'
+import { supabase } from './lib/supabase'
+import App from './App'
+
+// ⚠️ CRITICAL: Call setupRBAC BEFORE rendering App
+setupRBAC(supabase)
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+)
+```
+
+**Option 2: Setup in separate file (Alternative)**
+
+```typescript
+// src/lib/rbac-setup.ts
+import { setupRBAC } from '@jmruthers/pace-core/rbac'
+import { supabase } from './supabase'
+
+// ⚠️ REQUIRED: Initialize RBAC before using any RBAC features
+setupRBAC(supabase, {
+  // Optional: Configure rate limiting for high-traffic apps
+  security: {
+    maxPermissionChecksPerMinute: 2000 // Increase from default 1000 if needed
+  }
+})
+
+// src/main.tsx
+import './lib/rbac-setup' // Import BEFORE App
+import App from './App'
+```
+
+### 8. App Setup (CRITICAL - Event-Based Specific!)
+
+Create `src/App.tsx` with this EXACT structure for event-based apps:
+
+```typescript
+// src/App.tsx
+import React from 'react'
+import { BrowserRouter as Router, Routes, Route } from 'react-router-dom'
+import { 
+  UnifiedAuthProvider, 
+  OrganisationProvider,
+  EventProvider 
+} from '@jmruthers/pace-core/providers'
+import { supabase } from './lib/supabase'
+import { Dashboard } from './pages/Dashboard'
+import { Participants } from './pages/Participants'
+import { Login } from './pages/Login'
+
+// CRITICAL: App name for RBAC resolution
+const APP_NAME = import.meta.env.VITE_APP_NAME
+
+if (!APP_NAME) {
+  throw new Error('VITE_APP_NAME environment variable is required')
+}
+
+function App() {
+  return (
+    <UnifiedAuthProvider 
+      supabaseClient={supabase}
+      appName={APP_NAME}
+    >
+      <OrganisationProvider>
+        {/* CRITICAL: EventProvider is REQUIRED for event-based apps */}
+        <EventProvider
+          autoSelectNextEvent={true} // Automatically select next upcoming event
+          onEventChange={(event) => {
+            console.log('Event changed:', event?.event_name)
+          }}
+        >
+          <Router>
+            <Routes>
+              <Route path="/login" element={<Login />} />
+              <Route path="/" element={<Dashboard />} />
+              <Route path="/participants" element={<Participants />} />
+            </Routes>
+          </Router>
+        </EventProvider>
+      </OrganisationProvider>
+    </UnifiedAuthProvider>
+  )
+}
+
+export default App
+```
+
+**CRITICAL Differences for Event-Based Apps:**
+- ✅ **EventProvider is REQUIRED** - Wraps your app content
+- ✅ **OrganisationProvider still required** - Needed for organisation context
+- ✅ **autoSelectNextEvent** - Automatically selects the next upcoming event
+- ✅ **Event context is automatically available** - `PagePermissionGuard` will resolve organisation from event
+
+### 9. Create Login Page
+
+Create `src/pages/Login.tsx`:
+
+```typescript
+// src/pages/Login.tsx
+import React, { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { supabase } from '../lib/supabase'
+
+export function Login() {
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [loading, setLoading] = useState(false)
+  const navigate = useNavigate()
+
+  const handleLogin = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setLoading(true)
+
+    try {
+      const { data, error } = await supabase.auth.signInWithPassword({
+        email,
+        password
+      })
+
+      if (error) {
+        alert('Login failed: ' + error.message)
+        return
+      }
+
+      if (data.user) {
+        navigate('/')
+      }
+    } catch (error) {
+      alert('Login failed: ' + (error as Error).message)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-sec-50">
+      <div className="max-w-md w-full space-y-8">
+        <div>
+          <h2 className="mt-6 text-center text-3xl font-extrabold text-sec-900">
+            Sign in to your account
+          </h2>
+        </div>
+        <form className="mt-8 space-y-6" onSubmit={handleLogin}>
+          <div>
+            <label htmlFor="email" className="sr-only">
+              Email address
+            </label>
+            <input
+              id="email"
+              name="email"
+              type="email"
+              required
+              className="appearance-none rounded-md relative block w-full px-3 py-2 border border-sec-300 placeholder-sec-500 text-sec-900 focus:outline-none focus:ring-sec-500 focus:border-sec-500 focus:z-10 sm:text-sm"
+              placeholder="Email address"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+            />
+          </div>
+          <div>
+            <label htmlFor="password" className="sr-only">
+              Password
+            </label>
+            <input
+              id="password"
+              name="password"
+              type="password"
+              required
+              className="appearance-none rounded-md relative block w-full px-3 py-2 border border-sec-300 placeholder-sec-500 text-sec-900 focus:outline-none focus:ring-sec-500 focus:border-sec-500 focus:z-10 sm:text-sm"
+              placeholder="Password"
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+            />
+          </div>
+          <div>
+            <button
+              type="submit"
+              disabled={loading}
+              className="group relative w-full flex justify-center py-2 px-4 border border-transparent text-sm font-medium rounded-md text-main-50 bg-sec-600 hover:bg-sec-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-sec-500 disabled:opacity-50"
+            >
+              {loading ? 'Signing in...' : 'Sign in'}
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  )
+}
+```
+
+### 10. Create Dashboard Page (Event-Based)
+
+Create `src/pages/Dashboard.tsx`:
+
+```typescript
+// src/pages/Dashboard.tsx
+import React from 'react'
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers'
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac'
+import { Link } from 'react-router-dom'
+import { supabase } from '../lib/supabase'
+
+export function Dashboard() {
+  const { user, selectedEventId, selectedOrganisationId } = useUnifiedAuth()
+
+  if (!user) {
+    return <div>Please log in</div>
+  }
+
+  return (
+    <div className="min-h-screen bg-sec-50">
+      <nav className="bg-white shadow">
+        <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+          <div className="flex justify-between h-16">
+            <div className="flex items-center">
+              <h1 className="text-xl font-semibold">Event Dashboard</h1>
+            </div>
+            <div className="flex items-center space-x-4">
+              <span className="text-sm text-sec-700">
+                {user.email} | Event: {selectedEventId || 'None selected'} | Org: {selectedOrganisationId}
+              </span>
+              <button
+                onClick={() => supabase.auth.signOut()}
+                className="text-sm text-sec-500 hover:text-sec-700"
+              >
+                Sign out
+              </button>
+            </div>
+          </div>
+        </div>
+      </nav>
+
+      <main className="max-w-7xl mx-auto py-6 sm:px-6 lg:px-8">
+        <div className="px-4 py-6 sm:px-0">
+          <div className="border-4 border-dashed border-sec-200 rounded-lg h-96 p-8">
+            <h2 className="text-2xl font-bold mb-4">Welcome to your Event Dashboard</h2>
+            
+            {/* CRITICAL: PagePermissionGuard automatically resolves organisation from event */}
+            {/* For event-based apps, you only need eventId - organisationId is resolved automatically */}
+            <PagePermissionGuard
+              pageName="dashboard"
+              operation="read"
+              fallback={
+                <div>
+                  <p>You don't have permission to view the dashboard</p>
+                  <p className="text-sm text-sec-600 mt-2">
+                    {!selectedEventId && 'Please select an event first'}
+                    {selectedEventId && 'Your role does not have access to this page'}
+                  </p>
+                </div>
+              }
+            >
+              <div className="space-y-4">
+                <p>You have access to the dashboard!</p>
+                <p className="text-sm text-sec-600">
+                  Current Event ID: {selectedEventId || 'No event selected'}
+                </p>
+                <p className="text-sm text-sec-600">
+                  Organisation ID (resolved from event): {selectedOrganisationId || 'Resolving...'}
+                </p>
+                
+                <div className="space-x-4">
+                  <Link 
+                    to="/participants" 
+                    className="bg-main-500 text-main-50 px-4 py-2 rounded hover:bg-main-600"
+                  >
+                    View Participants
+                  </Link>
+                </div>
+              </div>
+            </PagePermissionGuard>
+          </div>
+        </div>
+      </main>
+    </div>
+  )
+}
+```
+
+### 11. Create Participants Page (Event-Based)
+
+Create `src/pages/Participants.tsx`:
+
+```typescript
+// src/pages/Participants.tsx
+import React from 'react'
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers'
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac'
+import { Link } from 'react-router-dom'
+import { supabase } from '../lib/supabase'
+
+export function Participants() {
+  const { user, selectedEventId, selectedOrganisationId } = useUnifiedAuth()
+
+  if (!user) {
+    return <div>Please log in</div>
+  }
+
+  return (
+    <div className="min-h-screen bg-sec-50">
+      <nav className="bg-white shadow">
+        <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+          <div className="flex justify-between h-16">
+            <div className="flex items-center">
+              <Link to="/" className="text-main-600 hover:text-main-800 mr-4">
+                ← Back to Dashboard
+              </Link>
+              <h1 className="text-xl font-semibold">Participants</h1>
+            </div>
+            <div className="flex items-center space-x-4">
+              <span className="text-sm text-sec-700">
+                {user.email} | Event: {selectedEventId || 'None'} | Org: {selectedOrganisationId}
+              </span>
+              <button
+                onClick={() => supabase.auth.signOut()}
+                className="text-sm text-sec-500 hover:text-sec-700"
+              >
+                Sign out
+              </button>
+            </div>
+          </div>
+        </div>
+      </nav>
+
+      <main className="max-w-7xl mx-auto py-6 sm:px-6 lg:px-8">
+        <div className="px-4 py-6 sm:px-0">
+          <div className="border-4 border-dashed border-sec-200 rounded-lg h-96 p-8">
+            <h2 className="text-2xl font-bold mb-4">Participant Management</h2>
+            
+            {/* CRITICAL: PagePermissionGuard automatically resolves organisation from event */}
+            <PagePermissionGuard
+              pageName="participants"
+              operation="read"
+              fallback={
+                <div>
+                  <p>You don't have permission to view participants</p>
+                  <p className="text-sm text-sec-600 mt-2">
+                    {!selectedEventId && 'Please select an event first'}
+                    {selectedEventId && 'Your role does not have access to this page'}
+                  </p>
+                </div>
+              }
+            >
+              <div className="space-y-4">
+                <p>You have access to the participants page!</p>
+                <p>This means your event-based RBAC system is working correctly.</p>
+                
+                <div className="bg-main-100 border border-main-400 text-main-700 px-4 py-3 rounded">
+                  <strong>Success!</strong> Your event-based RBAC setup is working correctly.
+                  <p className="text-sm mt-2">
+                    Event ID: {selectedEventId || 'Not set'}
+                    <br />
+                    Organisation ID (auto-resolved): {selectedOrganisationId || 'Resolving...'}
+                  </p>
+                </div>
+              </div>
+            </PagePermissionGuard>
+          </div>
+        </div>
+      </main>
+    </div>
+  )
+}
+```
+
+## 🧪 Test Your Setup
+
+1. **Start your development server**:
+   ```bash
+   npm run dev
+   ```
+
+2. **Navigate to your app** (usually `http://localhost:3000` or `http://localhost:5173`)
+
+3. **You should see the login page**
+
+4. **Log in with a user that has the `org_admin` role**
+
+5. **You should be redirected to the dashboard**
+   - If you see "No event selected", the EventProvider should auto-select the next event
+   - If no events exist, create one in the database (see step 5.4)
+
+6. **Click "View Participants" - you should see the participants page**
+
+7. **If you see "You don't have permission" messages, check the troubleshooting section below**
+
+## 🎉 Success Checklist
+
+Your event-based RBAC setup is working correctly if:
+
+**Setup Checklist:**
+- [ ] `setupRBAC(supabase)` is called before rendering App
+- [ ] App is registered in `rbac_apps` table with `requires_event = true` and `is_active = true`
+- [ ] Pages exist in `rbac_app_pages` for your app
+- [ ] Page permissions exist in `rbac_page_permissions` for your pages, roles, and organisation
+- [ ] User has an active role in `rbac_organisation_roles` for the organisation
+- [ ] At least one event exists in the `event` table for your organisation
+- [ ] `VITE_APP_NAME` environment variable matches database `rbac_apps.name` exactly
+- [ ] `EventProvider` wraps your app content
+- [ ] `OrganisationProvider` is present (required even for event-based apps)
+
+**Runtime Checklist:**
+- [ ] You can log in successfully
+- [ ] Browser console shows "RBAC system initialized successfully"
+- [ ] An event is automatically selected (or you can select one manually)
+- [ ] You see the dashboard without "Access Denied" messages
+- [ ] `PagePermissionGuard` shows loading state, then renders content (not fallback)
+- [ ] You can navigate to the participants page
+- [ ] You see "Success! Your event-based RBAC setup is working correctly" on the participants page
+- [ ] No 400/406 errors in the browser console
+- [ ] No "App not found" errors in the console
+- [ ] No "STRICT MODE VIOLATION" errors in the console
+- [ ] No "Event context is required" errors
+- [ ] Organisation ID is automatically resolved from event (visible in dashboard)
+
+## 🚨 Troubleshooting
+
+### Issue: "RBACNotInitializedError"
+
+**Cause**: Forgot to call `setupRBAC()`.
+
+**Solution**:
+```typescript
+import { setupRBAC } from '@jmruthers/pace-core/rbac'
+setupRBAC(supabase) // Must be called BEFORE rendering app
+```
+
+### Issue: "Event context is required" or "No event selected"
+
+**Cause**: Event is not selected in UnifiedAuth context.
+
+**Solutions**:
+
+1. **Check EventProvider is present**:
+   ```tsx
+   <EventProvider autoSelectNextEvent={true}>
+     <YourApp />
+   </EventProvider>
+   ```
+
+2. **Verify events exist for your organisation**:
+   ```sql
+   SELECT event_id, event_name, event_code, organisation_id, event_date
+   FROM event
+   WHERE organisation_id = 'your-organisation-id'::uuid
+     AND is_active = true
+   ORDER BY event_date ASC;
+   ```
+
+3. **Manually select an event** (for testing):
+   ```tsx
+   import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+   
+   function TestComponent() {
+     const { setSelectedEventId } = useUnifiedAuth();
+     
+     useEffect(() => {
+       // Set a test event ID
+       setSelectedEventId('your-event-id');
+     }, []);
+     
+     return <div>...</div>;
+   }
+   ```
+
+### Issue: "Could not resolve organization from event context"
+
+**Cause**: Event doesn't have a valid `organisation_id` or event doesn't exist.
+
+**Solution**:
+```sql
+-- Verify event has organisation_id
+SELECT event_id, event_name, organisation_id
+FROM event
+WHERE event_id = 'your-event-id'::uuid;
+
+-- If organisation_id is NULL, update it:
+UPDATE event
+SET organisation_id = 'your-organisation-id'::uuid
+WHERE event_id = 'your-event-id'::uuid;
+```
+
+### Issue: "Access Denied" or "STRICT MODE VIOLATION" on all pages
+
+**This is the most common issue. Check these in EXACT ORDER:**
+
+1. **Verify setupRBAC was called**:
+   - Check browser console for "RBAC system initialized successfully"
+   - If missing, add `setupRBAC(supabase)` in your main.tsx before rendering
+
+2. **Verify your app is registered as event-based**:
+   ```sql
+   SELECT id, name, display_name, requires_event, is_active 
+   FROM rbac_apps 
+   WHERE name = 'pace-trac';
+   ```
+   - Must return exactly 1 row
+   - `requires_event` must be `true` (not `false`)
+   - `is_active` must be `true`
+   - `name` must match your `VITE_APP_NAME` exactly (case-sensitive)
+
+3. **Check your environment variable matches database**:
+   ```typescript
+   console.log('App name from env:', import.meta.env.VITE_APP_NAME);
+   ```
+   - Must match database `rbac_apps.name` exactly
+
+4. **Verify pages exist for your app**:
+   ```sql
+   SELECT ap.id, ap.page_name, ap.page_description
+   FROM rbac_app_pages ap
+   JOIN rbac_apps a ON ap.app_id = a.id
+   WHERE a.name = 'pace-trac'
+   ORDER BY ap.page_name;
+   ```
+   - Must have pages for `dashboard`, `participants`, etc.
+
+5. **Verify user has organisation role**:
+   ```sql
+   SELECT ror.*, u.email
+   FROM rbac_organisation_roles ror
+   JOIN auth.users u ON ror.user_id = u.id
+   WHERE ror.user_id = 'your-user-id'::uuid 
+     AND ror.status = 'active';
+   ```
+   - User must have at least one active role
+   - Must be for the organisation that owns the event
+
+6. **Verify event belongs to user's organisation**:
+   ```sql
+   SELECT e.event_id, e.event_name, e.organisation_id, ror.organisation_id as user_org_id
+   FROM event e
+   JOIN rbac_organisation_roles ror ON e.organisation_id = ror.organisation_id
+   WHERE e.event_id = 'your-event-id'::uuid
+     AND ror.user_id = 'your-user-id'::uuid
+     AND ror.status = 'active';
+   ```
+   - Event's `organisation_id` must match user's organisation role
+
+7. **Check page permissions exist for user's role**:
+   ```sql
+   SELECT 
+     ap.page_name,
+     pp.operation,
+     pp.role_name,
+     pp.allowed,
+     pp.organisation_id
+   FROM rbac_page_permissions pp
+   JOIN rbac_app_pages ap ON pp.app_page_id = ap.id
+   JOIN rbac_apps a ON ap.app_id = a.id
+   WHERE a.name = 'pace-trac'
+     AND pp.role_name = 'org_admin'  -- Replace with your user's role
+     AND pp.organisation_id = 'your-org-id'::uuid  -- Replace with your org ID
+     AND pp.allowed = true;
+   ```
+   - Must have permissions for the pages you're trying to access
+   - Must have `allowed = true` for the operation (read, create, etc.)
+   - `organisation_id` must match the organisation that owns the event
+
+8. **Check browser console for specific errors**:
+   - Look for `[PagePermissionGuard]` error messages
+   - Look for `[useCan]` permission check logs
+   - Look for "Event context is required" errors
+   - Look for rate limit errors (if you see these, you may need to increase the limit)
+
+### Issue: 400/406 Database Errors
+
+**This means your app is making incorrect database queries. Check:**
+
+1. **You're using the providers correctly** (Step 8)
+2. **You're not making direct database queries to RBAC tables**
+3. **You're using the PagePermissionGuard component** (not manual permission checks)
+4. **EventProvider is wrapping your app content**
+
+### Issue: "App not found or inactive"
+
+**Check:**
+
+1. **Your app name in the database matches your environment variable exactly**
+2. **Your app is marked as active** (`is_active = true`)
+3. **Your app is marked as event-based** (`requires_event = true`)
+4. **You're using the correct app name in the UnifiedAuthProvider**
+
+### Issue: Components not rendering
+
+**Check:**
+
+1. **You're using PagePermissionGuard (not manual permission checks)**
+2. **You're providing the correct pageName and operation**
+3. **The page exists in rbac_app_pages table**
+4. **An event is selected** (`selectedEventId` is not null)
+5. **EventProvider is wrapping your components**
+
+## 🔑 Key Differences: Event-Based vs Organisation-Based Apps
+
+| Aspect | Organisation-Based | Event-Based |
+|--------|-------------------|-------------|
+| **Database Config** | `requires_event = false` | `requires_event = true` |
+| **Required Provider** | `OrganisationProvider` | `OrganisationProvider` + `EventProvider` |
+| **Context Required** | `organisationId` | `eventId` (org auto-resolved) |
+| **PagePermissionGuard** | Needs `organisationId` | Needs `eventId` (org auto-resolved) |
+| **Scope Resolution** | Direct from context | Organisation resolved from event |
+| **Use Case** | User management, org settings | Event registration, event management |
+
+## 🚀 Next Steps
+
+- **[RBAC Overview](./README.md)** - Complete RBAC system documentation
+- **[API Reference](./api-reference.md)** - Complete API documentation
+- **[Examples](./examples.md)** - More complex usage patterns
+- **[Troubleshooting](./troubleshooting.md)** - Advanced troubleshooting
+- **[Migration Guide](../migration/rbac-migration.md)** - If migrating from legacy RBAC
+
+## 🆘 Still Having Issues?
+
+If you're still having problems after following this guide exactly:
+
+1. **Check the browser console** for specific error messages
+2. **Verify your database setup** matches the SQL commands exactly
+3. **Make sure your environment variables** are set correctly
+4. **Check that your user has the correct roles** in the database
+5. **Verify an event exists** and belongs to your organisation
+6. **Ensure EventProvider is wrapping your app** content
+
+This guide is designed to be foolproof - if you follow it exactly, your event-based RBAC system will work correctly.
+