create-lego-one 2.0.10 → 2.0.13

package/template/docs/framework/setup/09-data-integration.md

@@ -0,0 +1,609 @@
+# Data Integration
+
+**PocketBase, Multi-Tenancy, and Data Fetching Patterns**
+
+---
+
+## Overview
+
+Lego-One uses **PocketBase** as the backend, providing an embedded database with auto-generated APIs. All data is scoped to organizations for multi-tenancy, and accessed through TanStack Query for optimal caching.
+
+---
+
+## PocketBase Setup
+
+### Collections
+
+**Standard Collections:**
+
+| Collection | Purpose | Multi-Tenancy |
+|-----------|---------|---------------|
+| `users` | User accounts | Via memberships |
+| `organizations` | Tenant organizations | N/A |
+| `roles` | System and custom roles | Per org |
+| `permissions` | Permission definitions | N/A |
+| `user_roles` | User-role assignments | Required |
+| `audit_logs` | Activity tracking | Required |
+
+**Plugin Collections:**
+Plugins create their own collections, e.g.:
+- `todos` - Todo plugin
+- `dashboard_widgets` - Dashboard plugin
+
+---
+
+### Collection Schema Pattern
+
+All plugin collections MUST follow this pattern:
+
+```javascript
+{
+  name: 'my_plugin_items',
+  type: 'base',
+
+  // Multi-tenancy required fields
+  fields: [
+    {
+      name: 'organizationId',
+      type: 'relation',
+      required: true,
+      options: {
+        collectionId: 'organizations',
+        displayFields: ['name']
+      }
+    },
+    {
+      name: 'ownerId',
+      type: 'relation',
+      required: true,
+      options: {
+        collectionId: 'users',
+        displayFields: ['name', 'email']
+      }
+    },
+
+    // Your plugin-specific fields
+    { name: 'title', type: 'text', required: true },
+    { name: 'description', type: 'text' },
+    { name: 'status', type: 'select', options: { values: ['active', 'inactive'] } },
+    { name: 'priority', type: 'select', options: { values: ['low', 'medium', 'high'] } },
+  ],
+
+  // Multi-tenancy API rules
+  listRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations',
+  viewRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations',
+  createRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations',
+  updateRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations && ownerId = @request.auth.id',
+  deleteRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations && ownerId = @request.auth.id',
+}
+```
+
+---
+
+## PocketBase Client
+
+### Accessing PocketBase
+
+**In Host Components:**
+```typescript
+import { usePocketBase } from '@lego/kernel/providers';
+
+function MyComponent() {
+  const pb = usePocketBase();
+
+  useEffect(() => {
+    if (!pb) return;
+
+    async function fetchData() {
+      const result = await pb.collection('todos').getList(1, 20);
+      console.log(result.items);
+    }
+
+    fetchData();
+  }, [pb]);
+
+  return <div>...</div>;
+}
+```
+
+**In Plugins:**
+```typescript
+// Create usePocketBase hook for plugin
+import { useEffect, useState } from 'react';
+
+export function usePocketBase() {
+  const [pb, setPb] = useState(null);
+
+  useEffect(() => {
+    // Get kernel state from window bridge
+    const kernelState = window.__LEGO_KERNEL_STATE__;
+
+    // Get PocketBase URL from environment
+    const pbUrl = import.meta.env.VITE_POCKETBASE_URL || 'http://127.0.0.1:8090';
+
+    // Create PocketBase client
+    const PocketBase = require('pocketbase').default;
+    const client = new PocketBase(pbUrl);
+
+    // Restore auth token from kernel state
+    const state = kernelState?.useGlobalKernelState?.getState();
+    if (state?.token) {
+      client.authStore.save(state.token);
+    }
+
+    setPb(client);
+  }, []);
+
+  return pb;
+}
+```
+
+---
+
+## TanStack Query Integration
+
+### Creating Data Hooks
+
+**Use TanStack Query for all server state:**
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+import { usePocketBase } from './usePocketBase';
+
+export function useTodos() {
+  const pb = usePocketBase();
+
+  return useQuery({
+    queryKey: ['todos'],
+    queryFn: async () => {
+      if (!pb) throw new Error('PB not initialized');
+
+      const kernelState = window.__LEGO_KERNEL_STATE__;
+      const state = kernelState?.useGlobalKernelState?.getState();
+      const orgId = state?.organization?.id;
+
+      const result = await pb.collection('todos').getList(1, 50, {
+        filter: `organizationId = "${orgId}"`,
+        sort: '-created',
+      });
+
+      return result.items;
+    },
+    enabled: !!pb && !!orgId,
+  });
+}
+```
+
+### Creating Mutation Hooks
+
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { usePocketBase } from './usePocketBase';
+import { useToastChannel } from './useToastChannel';
+
+export function useCreateTodo() {
+  const pb = usePocketBase();
+  const queryClient = useQueryClient();
+  const showToast = useToastChannel();
+
+  return useMutation({
+    mutationFn: async (data: { title: string; description?: string }) => {
+      if (!pb) throw new Error('PB not initialized');
+
+      const kernelState = window.__LEGO_KERNEL_STATE__;
+      const state = kernelState?.useGlobalKernelState?.getState();
+
+      return await pb.collection('todos').create({
+        ...data,
+        organizationId: state?.organization?.id,
+        ownerId: state?.user?.id,
+      });
+    },
+    onSuccess: () => {
+      // Invalidate and refetch
+      queryClient.invalidateQueries({ queryKey: ['todos'] });
+
+      // Show success toast
+      showToast({
+        type: 'success',
+        title: 'Todo Created',
+        description: 'Your todo was created successfully',
+      });
+    },
+    onError: (error) => {
+      showToast({
+        type: 'error',
+        title: 'Error',
+        description: error.message,
+      });
+    },
+  });
+}
+```
+
+---
+
+## Multi-Tenancy Patterns
+
+### Data Isolation
+
+**CRITICAL:** All data queries MUST be scoped to organization:
+
+```typescript
+// ✅ CORRECT - Filter by organization
+const result = await pb.collection('items').getList(1, 50, {
+  filter: `organizationId = "${orgId}"`,
+});
+
+// ❌ WRONG - No organization filter
+const result = await pb.collection('items').getList(1, 50);
+```
+
+### Getting Current Organization
+
+```typescript
+import { useEffect, useState } from 'react';
+
+export function useCurrentOrganization() {
+  const [org, setOrg] = useState(null);
+
+  useEffect(() => {
+    // Get from kernel state
+    const kernelState = window.__LEGO_KERNEL_STATE__;
+    const state = kernelState?.useGlobalKernelState?.getState();
+
+    setOrg(state?.organization || null);
+
+    // Subscribe to organization changes
+    const channelBus = window.__LEGO_CHANNEL_BUS__;
+    if (!channelBus) return;
+
+    const unsubscribe = channelBus.subscribe('lego:organization:change', () => {
+      const newState = kernelState?.useGlobalKernelState?.getState();
+      setOrg(newState?.organization || null);
+    });
+
+    return unsubscribe;
+  }, []);
+
+  return org;
+}
+```
+
+---
+
+## CRUD Patterns
+
+### Create
+
+```typescript
+export function useCreateItem() {
+  const pb = usePocketBase();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (data: CreateItemData) => {
+      if (!pb) throw new Error('PB not initialized');
+
+      const state = window.__LEGO_KERNEL_STATE__?.useGlobalKernelState?.getState();
+
+      return await pb.collection('items').create({
+        ...data,
+        organizationId: state?.organization?.id,
+        ownerId: state?.user?.id,
+      });
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['items'] });
+    },
+  });
+}
+```
+
+### Read
+
+```typescript
+export function useItems() {
+  const pb = usePocketBase();
+
+  return useQuery({
+    queryKey: ['items'],
+    queryFn: async () => {
+      if (!pb) throw new Error('PB not initialized');
+
+      const state = window.__LEGO_KERNEL_STATE__?.useGlobalKernelState?.getState();
+      const orgId = state?.organization?.id;
+
+      const result = await pb.collection('items').getList(1, 50, {
+        filter: `organizationId = "${orgId}"`,
+        sort: '-created',
+      });
+
+      return result.items;
+    },
+    enabled: !!pb && !!orgId,
+  });
+}
+```
+
+### Update
+
+```typescript
+export function useUpdateItem() {
+  const pb = usePocketBase();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({ id, data }: { id: string; data: UpdateItemData }) => {
+      if (!pb) throw new Error('PB not initialized');
+
+      return await pb.collection('items').update(id, data);
+    },
+    onSuccess: (_, { id }) => {
+      queryClient.invalidateQueries({ queryKey: ['items'] });
+      queryClient.invalidateQueries({ queryKey: ['item', id] });
+    },
+  });
+}
+```
+
+### Delete
+
+```typescript
+export function useDeleteItem() {
+  const pb = usePocketBase();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (id: string) => {
+      if (!pb) throw new Error('PB not initialized');
+
+      return await pb.collection('items').delete(id);
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['items'] });
+    },
+  });
+}
+```
+
+---
+
+## Advanced Queries
+
+### Filtering
+
+```typescript
+export function useTodos(filter: 'all' | 'active' | 'completed') {
+  const pb = usePocketBase();
+
+  return useQuery({
+    queryKey: ['todos', filter],
+    queryFn: async () => {
+      if (!pb) throw new Error('PB not initialized');
+
+      const state = window.__LEGO_KERNEL_STATE__?.useGlobalKernelState?.getState();
+      const orgId = state?.organization?.id;
+
+      let filterStr = `organizationId = "${orgId}"`;
+
+      if (filter === 'active') {
+        filterStr += ' && status = "active"';
+      } else if (filter === 'completed') {
+        filterStr += ' && status = "completed"';
+      }
+
+      const result = await pb.collection('todos').getList(1, 50, {
+        filter: filterStr,
+        sort: '-created',
+      });
+
+      return result.items;
+    },
+    enabled: !!pb && !!orgId,
+  });
+}
+```
+
+### Searching
+
+```typescript
+export function useSearchTodos(search: string) {
+  const pb = usePocketBase();
+
+  return useQuery({
+    queryKey: ['todos', 'search', search],
+    queryFn: async () => {
+      if (!pb || !search) return [];
+
+      const state = window.__LEGO_KERNEL_STATE__?.useGlobalKernelState?.getState();
+      const orgId = state?.organization?.id;
+
+      const result = await pb.collection('todos').getList(1, 50, {
+        filter: `organizationId = "${orgId}" && title ~ "${search}"`,
+        sort: '-created',
+      });
+
+      return result.items;
+    },
+    enabled: !!pb && !!orgId && search.length > 0,
+  });
+}
+```
+
+### Pagination
+
+```typescript
+export function useTodosPaginated(page: number, perPage: number = 20) {
+  const pb = usePocketBase();
+
+  return useQuery({
+    queryKey: ['todos', 'paginated', page, perPage],
+    queryFn: async () => {
+      if (!pb) throw new Error('PB not initialized');
+
+      const state = window.__LEGO_KERNEL_STATE__?.useGlobalKernelState?.getState();
+      const orgId = state?.organization?.id;
+
+      const result = await pb.collection('todos').getList(page, perPage, {
+        filter: `organizationId = "${orgId}"`,
+        sort: '-created',
+      });
+
+      return {
+        items: result.items,
+        totalPages: result.totalPages,
+        totalItems: result.totalItems,
+      };
+    },
+    enabled: !!pb && !!orgId,
+  });
+}
+```
+
+---
+
+## Real-time Subscriptions
+
+PocketBase supports real-time subscriptions:
+
+```typescript
+useEffect(() => {
+  const pb = usePocketBase();
+  if (!pb) return;
+
+  // Subscribe to todo changes
+  const unsubscribe = pb.collection('todos').subscribe('*', (e) => {
+    console.log('Todo changed:', e);
+
+    // Refresh data on changes
+    queryClient.invalidateQueries({ queryKey: ['todos'] });
+  });
+
+  return () => {
+    unsubscribe(); // Cleanup
+  };
+}, [pb]);
+```
+
+---
+
+## Validation with Zod
+
+### Define Schema
+
+```typescript
+import { z } from 'zod';
+
+export const todoFormSchema = z.object({
+  title: z.string().min(1, 'Title is required').max(200, 'Title too long'),
+  description: z.string().max(1000).optional(),
+  priority: z.enum(['low', 'medium', 'high']).default('medium'),
+  dueDate: z.string().optional(),
+});
+
+export type TodoFormData = z.infer<typeof todoFormSchema>;
+```
+
+### Use with Form Library
+
+```typescript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { todoFormSchema } from './schemas';
+
+function TodoForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm({
+    resolver: zodResolver(todoFormSchema),
+  });
+
+  const { mutate: createTodo } = useCreateTodo();
+
+  const onSubmit = (data: TodoFormData) => {
+    createTodo(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('title')} />
+      {errors.title && <span>{errors.title.message}</span>}
+
+      <textarea {...register('description')} />
+
+      <select {...register('priority')}>
+        <option value="low">Low</option>
+        <option value="medium">Medium</option>
+        <option value="high">High</option>
+      </select>
+
+      <button type="submit">Create</button>
+    </form>
+  );
+}
+```
+
+---
+
+## Error Handling
+
+### Handling PocketBase Errors
+
+```typescript
+try {
+  const result = await pb.collection('todos').create(data);
+} catch (error) {
+  // PocketBase errors
+  if (error?.data) {
+    // Validation error
+    console.error('Validation failed:', error.data);
+  } else if (error?.status === 404) {
+    console.error('Collection not found');
+  } else if (error?.status === 403) {
+    console.error('Permission denied');
+  } else {
+    console.error('Unknown error:', error);
+  }
+}
+```
+
+### User-Friendly Error Messages
+
+```typescript
+function getErrorMessage(error: any): string {
+  if (error?.data?.title) {
+    return error.data.title; // PocketBase validation error
+  }
+
+  if (error?.message) {
+    return error.message;
+  }
+
+  return 'An unexpected error occurred';
+}
+```
+
+---
+
+## Best Practices
+
+### DO ✅
+
+1. **Scope all queries to organization** - Always filter by `organizationId`
+2. **Use TanStack Query** - Automatic caching, refetching, loading states
+3. **Show loading states** - Use Skeleton, Spinners during fetch
+4. **Handle errors gracefully** - Show user-friendly error messages
+5. **Invalidate queries** - After mutations, invalidate related queries
+6. **Use toast notifications** - For user feedback on actions
+7. **Validate with Zod** - Type-safe validation
+
+### DON'T ❌
+
+1. **Don't skip organization filtering** - Data isolation is critical
+2. **Don't fetch directly in components** - Use custom hooks
+3. **Don't ignore loading/error states** - Always handle these
+4. **Don't forget cleanup** - Unsubscribe from events
+5. **Don't hardcode org IDs** - Always get from kernel state
+
+---
+
+**Next:** Read [`10-auth-rbac.md`](./10-auth-rbac.md) for authentication and authorization patterns.