From dae687292bf8cd4afeb114a8210493292814482d Mon Sep 17 00:00:00 2001
From: "gpt-engineer-app[bot]"
 <159125892+gpt-engineer-app[bot]@users.noreply.github.com>
Date: Sun, 2 Nov 2025 19:09:45 +0000
Subject: [PATCH] Add documentation for hooks

---
 docs/DATABASE_DIRECT_EDIT.md | 1524 ++++++++++++++++++++++++++++++++++
 1 file changed, 1524 insertions(+)
 create mode 100644 docs/DATABASE_DIRECT_EDIT.md

diff --git a/docs/DATABASE_DIRECT_EDIT.md b/docs/DATABASE_DIRECT_EDIT.md
new file mode 100644
index 00000000..18331336
--- /dev/null
+++ b/docs/DATABASE_DIRECT_EDIT.md
@@ -0,0 +1,1524 @@
+# Database Direct Edit System
+
+## Overview
+A full-featured database management interface for administrators (admin/superuser roles only) that allows direct CRUD operations on all database tables with advanced spreadsheet-like functionality, comprehensive filtering, sorting, and inline editing capabilities.
+
+**Status**: 📋 Planned (Not Yet Implemented)
+
+**Target Users**: Administrators and Superusers only
+
+**Security Level**: Requires AAL2 (MFA verification)
+
+---
+
+## Table of Contents
+1. [Architecture & Security](#architecture--security)
+2. [Core Components](#core-components)
+3. [Feature Specifications](#feature-specifications)
+4. [Database Requirements](#database-requirements)
+5. [Implementation Roadmap](#implementation-roadmap)
+6. [Dependencies](#dependencies)
+7. [Safety & UX Guidelines](#safety--ux-guidelines)
+
+---
+
+## Architecture & Security
+
+### Access Control
+- **Role Restriction**: Only `admin` and `superuser` roles can access
+- **AAL2 Enforcement**: All database operations require MFA verification via `useSuperuserGuard()`
+- **Audit Logging**: Every modification logged to `admin_audit_log`
+- **Warning Banner**: Display risk disclaimer about direct database access
+- **Read-Only Mode**: Toggle to prevent accidental edits
+
+### Route Structure
+```
+/admin/database              # Main database browser (table list)
+/admin/database/:tableName   # Spreadsheet editor for specific table
+```
+
+### Navigation
+- Add "Database Editor" link to AdminSidebar
+- Icon: `Database` from lucide-react
+- Position: Below "User Management"
+- Visibility: Superuser only (`isSuperuser()`)
+
+---
+
+## Core Components
+
+### File Structure
+```
+src/
+├── pages/admin/
+│   └── AdminDatabase.tsx                    # Main page with routing
+│
+├── components/admin/database/
+│   ├── index.ts                             # Barrel exports
+│   ├── DatabaseTableBrowser.tsx             # Table selector & overview
+│   ├── DatabaseTableEditor.tsx              # Main spreadsheet editor (TanStack Table)
+│   ├── DatabaseTableFilters.tsx             # Advanced filtering UI
+│   ├── DatabaseColumnConfig.tsx             # Column visibility/order management
+│   ├── DatabaseRowEditor.tsx                # Detailed row editor dialog
+│   ├── DatabaseBulkActions.tsx              # Bulk edit/delete operations
+│   ├── DatabaseExportImport.tsx             # CSV/JSON export/import
+│   ├── DatabaseSchemaViewer.tsx             # Table schema & ERD viewer
+│   ├── DatabaseCellEditors.tsx              # Type-specific cell editors
+│   └── types.ts                             # TypeScript definitions
+│
+├── hooks/
+│   ├── useTableSchema.ts                    # Fetch table schema from Supabase
+│   ├── useTableData.ts                      # Fetch/edit table data with optimistic updates
+│   ├── useDatabaseAudit.ts                  # Audit logging utilities
+│   └── useDatabaseValidation.ts             # Validation functions
+│
+└── lib/
+    ├── database/
+    │   ├── cellEditors.tsx                  # Cell editor component factory
+    │   ├── filterFunctions.ts               # Custom filter functions per data type
+    │   ├── validationRules.ts               # Validation rules per column type
+    │   └── schemaParser.ts                  # Parse Supabase schema to table config
+    └── utils/
+        ├── csvExport.ts                     # CSV export utilities
+        └── jsonImport.ts                    # JSON import/validation
+```
+
+---
+
+## Feature Specifications
+
+### Phase 1: Table Browser & Navigation
+
+#### DatabaseTableBrowser Component
+**Purpose**: Display all database tables with metadata and quick navigation
+
+**Features**:
+- **Table List Display**:
+  - Grid or list view toggle
+  - Show table name, row count, size, last modified
+  - Search/filter tables by name
+  - Sort by name, row count, or date
+  
+- **Table Categorization**:
+```typescript
+const tableCategories = {
+  auth: {
+    color: 'red',
+    tables: ['profiles', 'user_roles', 'user_preferences', 'user_sessions'],
+    icon: 'Shield'
+  },
+  content: {
+    color: 'yellow',
+    tables: ['parks', 'rides', 'companies', 'ride_models', 'locations'],
+    icon: 'MapPin'
+  },
+  submissions: {
+    color: 'green',
+    tables: ['content_submissions', 'submission_items', 'photo_submissions'],
+    icon: 'FileText'
+  },
+  moderation: {
+    color: 'blue',
+    tables: ['reports', 'admin_audit_log', 'review_reports'],
+    icon: 'Flag'
+  },
+  versioning: {
+    color: 'purple',
+    tables: ['park_versions', 'ride_versions', 'company_versions'],
+    icon: 'History'
+  },
+  system: {
+    color: 'gray',
+    tables: ['admin_settings', 'notification_logs', 'rate_limits'],
+    icon: 'Settings'
+  }
+}
+```
+
+- **Quick Stats Cards**:
+  - Total tables count
+  - Total rows across all tables
+  - Database size
+  - Last modified timestamp
+
+- **Table Actions**:
+  - Click table to open editor
+  - Quick view schema (hover tooltip)
+  - Export table data
+  - View recent changes (from versions tables)
+
+**Data Fetching**:
+```typescript
+// Use Supabase RPC to get table metadata
+const { data: tables } = await supabase.rpc('get_table_metadata')
+
+interface TableMetadata {
+  table_name: string;
+  row_count: bigint;
+  total_size: string;
+  last_modified: string;
+  category?: string;
+}
+```
+
+---
+
+### Phase 2: Spreadsheet-Style Table Editor
+
+#### DatabaseTableEditor Component
+**Core Technology**: TanStack Table v8 with advanced features
+
+#### 2.1 Data Grid Display
+
+**Features**:
+- **Virtual Scrolling**: Handle 10,000+ rows efficiently using `@tanstack/react-virtual`
+- **Sticky Headers**: Column headers remain visible on scroll
+- **Row Numbers**: Display row index in first column
+- **Column Resizing**: Drag column borders to resize
+- **Column Reordering**: Drag-drop column headers to reorder
+- **Row Selection**: 
+  - Single click to select row
+  - Shift+Click for range selection
+  - Ctrl+Click for multi-selection
+  - Checkbox column for bulk selection
+- **Zebra Striping**: Alternate row colors for readability
+- **Cell Highlighting**: Hover effect on cells
+- **Responsive Design**: Horizontal scroll on smaller screens
+
+**Implementation**:
+```tsx
+const table = useReactTable({
+  data: tableData,
+  columns: dynamicColumns,
+  getCoreRowModel: getCoreRowModel(),
+  getFilteredRowModel: getFilteredRowModel(),
+  getSortedRowModel: getSortedRowModel(),
+  getPaginationRowModel: getPaginationRowModel(),
+  enableRowSelection: true,
+  enableMultiSort: true,
+  enableColumnResizing: true,
+  columnResizeMode: 'onChange',
+  state: {
+    sorting,
+    columnFilters,
+    columnVisibility,
+    rowSelection,
+    pagination
+  }
+})
+```
+
+#### 2.2 Inline Editing
+
+**Cell Editor Types** (auto-detected from column type):
+
+| Data Type | Editor Component | Features |
+|-----------|------------------|----------|
+| `text`, `varchar` | `<Input>` | Text input with validation |
+| `integer`, `bigint`, `numeric` | `<Input type="number">` | Number input with min/max |
+| `boolean` | `<Switch>` | Toggle switch |
+| `timestamp`, `date` | `<DatePicker>` | Calendar popup with time |
+| `uuid` | `<Select>` or `<Input>` | FK lookup or manual entry |
+| `jsonb`, `json` | `<Textarea>` + JSON validator | Syntax highlighting |
+| `enum` | `<Select>` | Dropdown with allowed values |
+| `text[]` | `<TagInput>` | Multi-value chips |
+
+**Edit Flow**:
+1. Click cell → Enter edit mode
+2. Show appropriate editor component
+3. Type/select new value
+4. Press Enter to save OR Escape to cancel
+5. Optimistic update → DB save → Rollback on error
+6. Visual feedback: Yellow (editing) → Green (saved) → Red (error)
+
+**Validation**:
+- Check NOT NULL constraints
+- Validate data type compatibility
+- Verify foreign key references exist
+- Check max length for strings
+- Validate JSON syntax
+- Custom validation rules per table
+
+**Implementation**:
+```tsx
+const EditableCell = ({ getValue, row, column, table }) => {
+  const initialValue = getValue()
+  const [value, setValue] = useState(initialValue)
+  const [isEditing, setIsEditing] = useState(false)
+  
+  const handleSave = async () => {
+    const meta = table.options.meta
+    await meta?.updateData(row.index, column.id, value)
+    setIsEditing(false)
+  }
+  
+  return (
+    <div onClick={() => setIsEditing(true)}>
+      {isEditing ? (
+        <Input 
+          value={value} 
+          onChange={(e) => setValue(e.target.value)}
+          onBlur={handleSave}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') handleSave()
+            if (e.key === 'Escape') setIsEditing(false)
+          }}
+        />
+      ) : (
+        <span>{value}</span>
+      )}
+    </div>
+  )
+}
+```
+
+#### 2.3 Advanced Filtering
+
+**Filter Panel** (collapsible left sidebar):
+
+**Filter Builder UI**:
+- Add filter button
+- Each filter row contains:
+  - Column selector dropdown
+  - Operator selector (based on column type)
+  - Value input (type-appropriate)
+  - Remove filter button
+- AND/OR logic toggle between filters
+- Clear all filters button
+- Save filter preset (with name)
+- Load saved preset
+
+**Filter Types by Data Type**
+
+**Text Columns**:
+- Contains
+- Equals
+- Starts with
+- Ends with
+- Regex match
+- Is empty / Is not empty
+
+**Number Columns**:
+- Equals
+- Greater than (>)
+- Less than (<)
+- Greater than or equal (>=)
+- Less than or equal (<=)
+- Between (min, max)
+- Is null / Is not null
+
+**Date Columns**:
+- Before
+- After
+- Between (start, end)
+- Is null
+- Last N days
+- Next N days
+
+**Boolean Columns**:
+- Is true
+- Is false
+- Is null
+
+**UUID Columns**:
+- Equals
+- In list (comma-separated)
+- Is null
+
+**JSON Columns**:
+- Path exists
+- Path equals value
+- Contains key
+
+**Quick Filters Bar** (above table):
+- Chips showing active filters
+- Click chip to edit filter
+- X to remove filter
+- "5 filters active" counter
+
+**Implementation**:
+```tsx
+interface ColumnFilter {
+  id: string;          // column name
+  operator: FilterOperator;
+  value: any;
+  logicGate?: 'AND' | 'OR';
+}
+
+const filterFunctions = {
+  text: {
+    contains: (row, id, filterValue) => 
+      row.getValue(id)?.toLowerCase().includes(filterValue.toLowerCase()),
+    equals: (row, id, filterValue) => 
+      row.getValue(id) === filterValue,
+    startsWith: (row, id, filterValue) => 
+      row.getValue(id)?.startsWith(filterValue),
+    // ... more
+  },
+  number: {
+    equals: (row, id, filterValue) => row.getValue(id) === filterValue,
+    gt: (row, id, filterValue) => row.getValue(id) > filterValue,
+    // ... more
+  }
+}
+```
+
+#### 2.4 Sorting & Pagination
+
+**Sorting**:
+- Click column header to sort ascending
+- Click again to sort descending
+- Click third time to remove sort
+- Shift+Click to add multi-column sort
+- Sort indicators: ↑ (asc), ↓ (desc)
+- Multi-sort shows order numbers (1, 2, 3)
+- Custom sort functions for complex types (JSON, arrays)
+
+**Pagination**:
+- Rows per page selector: 25, 50, 100, 500, 1000
+- Page navigation: First, Prev, Next, Last
+- Page input: "Jump to page X"
+- Display: "Showing 1-25 of 1,234 rows"
+- "Load all" button (with warning for tables > 1000 rows)
+- Virtual scrolling for large datasets
+
+**Implementation**:
+```tsx
+const [pagination, setPagination] = useState({
+  pageIndex: 0,
+  pageSize: 50
+})
+
+const table = useReactTable({
+  // ...
+  getPaginationRowModel: getPaginationRowModel(),
+  onPaginationChange: setPagination,
+  state: { pagination }
+})
+
+// Pagination controls
+<div className="flex items-center gap-2">
+  <Button onClick={() => table.setPageIndex(0)}>First</Button>
+  <Button onClick={() => table.previousPage()}>Prev</Button>
+  <Input 
+    type="number" 
+    value={table.getState().pagination.pageIndex + 1}
+    onChange={(e) => table.setPageIndex(Number(e.target.value) - 1)}
+  />
+  <span>of {table.getPageCount()}</span>
+  <Button onClick={() => table.nextPage()}>Next</Button>
+  <Button onClick={() => table.setPageIndex(table.getPageCount() - 1)}>Last</Button>
+</div>
+```
+
+#### 2.5 Column Management
+
+**Column Config Panel** (collapsible right sidebar):
+
+**Features**:
+- **Column Visibility**:
+  - Checkbox list of all columns
+  - Toggle individual columns on/off
+  - "Show all" / "Hide all" buttons
+  - Search column names
+  
+- **Column Reordering**:
+  - Drag-drop list to reorder columns
+  - Visual drag handle icon
+  - Smooth reorder animation
+
+- **Column Pinning**:
+  - Pin columns to left (e.g., ID, name)
+  - Pin columns to right (e.g., actions)
+  - Unpin button
+
+- **Column Presets**:
+  - Save current column layout with name
+  - Load saved layouts
+  - Default layouts per table:
+    - "Essential" (ID, name, status, dates)
+    - "All" (show everything)
+    - "Metadata" (created_at, updated_at, created_by)
+
+- **Reset to Default**:
+  - Restore original column order/visibility
+
+**Implementation**:
+```tsx
+const [columnVisibility, setColumnVisibility] = useState({})
+const [columnOrder, setColumnOrder] = useState([])
+const [columnPinning, setColumnPinning] = useState({ left: ['id'], right: [] })
+
+const table = useReactTable({
+  // ...
+  state: {
+    columnVisibility,
+    columnOrder,
+    columnPinning
+  },
+  onColumnVisibilityChange: setColumnVisibility,
+  onColumnOrderChange: setColumnOrder,
+  onColumnPinningChange: setColumnPinning
+})
+```
+
+#### 2.6 Search & Navigation
+
+**Global Search**:
+- Search input above table
+- Searches all visible columns
+- Highlight matching text in cells
+- "X matches found" counter
+- Next/Prev navigation between matches
+- Clear search button
+
+**Quick Jump**:
+- "Jump to row by ID" input
+- Autofocus and scroll to row
+- Highlight target row
+
+**Keyboard Navigation**:
+- Arrow keys: Navigate cells
+- Tab: Move to next editable cell
+- Enter: Edit current cell / Save edit
+- Escape: Cancel edit
+- Page Up/Down: Scroll page
+- Home/End: Jump to first/last row
+- Ctrl+F: Focus search
+- Ctrl+C: Copy cell value
+- Del: Delete selected rows (with confirmation)
+
+---
+
+### Phase 3: Advanced Features
+
+#### 3.1 Bulk Operations (DatabaseBulkActions)
+
+**Features**:
+- **Row Selection**: Checkboxes in first column
+- **Selection Actions**:
+  - Select all on page
+  - Select all matching filter
+  - Deselect all
+  - Invert selection
+  
+- **Bulk Edit**:
+  - Select column to edit
+  - Set value for all selected rows
+  - Preview changes before applying
+  - Apply button with confirmation
+
+- **Bulk Delete**:
+  - Delete all selected rows
+  - Show count: "Delete 23 rows?"
+  - Confirmation dialog with row preview
+  - Cannot be undone warning
+
+- **Batch Update**:
+  - Apply formula/function to column
+  - Examples:
+    - Set status to 'approved' for all pending
+    - Increment version number by 1
+    - Update timestamps to NOW()
+
+- **Action History**:
+  - Show last 10 bulk operations
+  - Display: operation, row count, timestamp, user
+  - Undo last operation (if safe and within 5 minutes)
+
+**UI**:
+```tsx
+<div className="bulk-actions-toolbar">
+  <span>{selectedRows.length} rows selected</span>
+  <Button onClick={handleBulkEdit}>Edit Selected</Button>
+  <Button onClick={handleBulkDelete} variant="destructive">Delete Selected</Button>
+  <Button onClick={handleDeselectAll} variant="ghost">Deselect All</Button>
+</div>
+```
+
+#### 3.2 Export/Import (DatabaseExportImport)
+
+**Export Features**:
+- **Export Formats**:
+  - CSV (with headers)
+  - JSON (array of objects)
+  - SQL INSERT statements
+  
+- **Export Scope**:
+  - All rows
+  - Filtered rows only
+  - Selected rows only
+  - Visible columns only
+  
+- **Export Options**:
+  - Include/exclude NULL values
+  - Date format selection
+  - JSON pretty print
+  - SQL: Include CREATE TABLE statement
+  
+- **Batch Export**:
+  - Export all tables as ZIP file
+  - Progress indicator for large exports
+
+**Import Features**:
+- **Import Formats**:
+  - CSV (with column mapping UI)
+  - JSON (validate schema first)
+  
+- **Import Modes**:
+  - Insert (add new rows)
+  - Update (match by ID)
+  - Upsert (insert or update)
+  
+- **Import Validation**:
+  - Dry-run preview
+  - Show errors before import
+  - Skip invalid rows option
+  
+- **Import Progress**:
+  - Progress bar for large files
+  - Success/error counts
+  - Download error log
+
+**Implementation**:
+```tsx
+const exportToCSV = (data: any[], columns: Column[]) => {
+  const headers = columns.map(col => col.header).join(',')
+  const rows = data.map(row => 
+    columns.map(col => JSON.stringify(row[col.id] ?? '')).join(',')
+  ).join('\n')
+  
+  const csv = `${headers}\n${rows}`
+  downloadFile(csv, 'table_export.csv', 'text/csv')
+}
+
+const importFromCSV = async (file: File) => {
+  const parsed = Papa.parse(file, { header: true })
+  
+  // Validate schema
+  const validationErrors = validateImportData(parsed.data, tableSchema)
+  if (validationErrors.length > 0) {
+    showErrorDialog(validationErrors)
+    return
+  }
+  
+  // Insert rows
+  for (const row of parsed.data) {
+    await supabase.from(tableName).insert(row)
+  }
+}
+```
+
+#### 3.3 Schema Viewer (DatabaseSchemaViewer)
+
+**Features**:
+- **Table Structure Display**:
+  - Column list with details:
+    - Name
+    - Data type
+    - Nullable (✓/✗)
+    - Default value
+    - Max length (for text)
+  - Primary key indicator (🔑)
+  - Foreign key indicators (→ target_table)
+  - Unique constraint indicators
+  - Index indicators (📊)
+  
+- **Relationships View**:
+  - Visual diagram (ERD style)
+  - Show foreign key relationships
+  - Click table to navigate
+  - Zoom/pan controls
+  
+- **Constraints**:
+  - Primary keys
+  - Foreign keys (with ON DELETE/UPDATE actions)
+  - Unique constraints
+  - Check constraints
+  - Indexes (btree, gin, gist)
+  
+- **RLS Policies** (read-only):
+  - List all policies for table
+  - Show policy name, operation, USING clause
+  - Syntax highlighting for SQL
+  
+- **SQL DDL View**:
+  - Show CREATE TABLE statement
+  - Show CREATE INDEX statements
+  - Show RLS policies
+  - Copy to clipboard button
+  - Syntax highlighting
+
+**Implementation**:
+```tsx
+const SchemaViewer = ({ tableName }: { tableName: string }) => {
+  const { data: schema } = useTableSchema(tableName)
+  
+  return (
+    <Tabs>
+      <TabsList>
+        <TabsTrigger value="columns">Columns</TabsTrigger>
+        <TabsTrigger value="relationships">Relationships</TabsTrigger>
+        <TabsTrigger value="constraints">Constraints</TabsTrigger>
+        <TabsTrigger value="rls">RLS Policies</TabsTrigger>
+        <TabsTrigger value="sql">SQL DDL</TabsTrigger>
+      </TabsList>
+      
+      <TabsContent value="columns">
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Name</TableHead>
+              <TableHead>Type</TableHead>
+              <TableHead>Nullable</TableHead>
+              <TableHead>Default</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {schema.columns.map(col => (
+              <TableRow key={col.name}>
+                <TableCell>
+                  {col.isPrimaryKey && '🔑 '}
+                  {col.name}
+                </TableCell>
+                <TableCell>{col.type}</TableCell>
+                <TableCell>{col.isNullable ? '✓' : '✗'}</TableCell>
+                <TableCell><code>{col.default}</code></TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </TabsContent>
+      
+      {/* Other tabs */}
+    </Tabs>
+  )
+}
+```
+
+#### 3.4 Row Editor Dialog (DatabaseRowEditor)
+
+**Purpose**: Detailed form-based editor for complex edits
+
+**Features**:
+- **Trigger**: Double-click row to open
+- **Layout**: Vertical form with all columns
+- **Field Types**:
+  - Text: `<Textarea>` for long text
+  - JSON: Syntax-highlighted editor with validation
+  - Foreign Keys: Searchable `<Combobox>` with preview
+  - Images: Preview thumbnail + URL input
+  - Markdown: Split view (editor + preview)
+  - Arrays: Chip input for multi-value
+  - Timestamps: Calendar + time picker
+  
+- **Actions**:
+  - Save: Update row
+  - Save & Close: Update and return to table
+  - Clone Row: Duplicate with new ID
+  - Delete Row: With confirmation
+  - Cancel: Discard changes
+  
+- **Validation**:
+  - Real-time field validation
+  - Show error messages inline
+  - Disable save until valid
+  
+- **Metadata Section**:
+  - Show created_at, updated_at, created_by
+  - Show version history (if versioned table)
+  - Link to audit log entries
+
+**Implementation**:
+```tsx
+<Dialog open={isOpen} onOpenChange={setIsOpen}>
+  <DialogContent className="max-w-2xl max-h-[80vh] overflow-y-auto">
+    <DialogHeader>
+      <DialogTitle>Edit Row: {rowId}</DialogTitle>
+    </DialogHeader>
+    
+    <form onSubmit={handleSave}>
+      {columns.map(col => (
+        <div key={col.name} className="space-y-2">
+          <Label>{col.name}</Label>
+          {renderFieldEditor(col, formData[col.name], handleChange)}
+          {errors[col.name] && (
+            <p className="text-sm text-destructive">{errors[col.name]}</p>
+          )}
+        </div>
+      ))}
+      
+      <DialogFooter>
+        <Button variant="ghost" onClick={() => setIsOpen(false)}>Cancel</Button>
+        <Button variant="outline" onClick={handleClone}>Clone Row</Button>
+        <Button variant="destructive" onClick={handleDelete}>Delete</Button>
+        <Button type="submit">Save</Button>
+      </DialogFooter>
+    </form>
+  </DialogContent>
+</Dialog>
+```
+
+#### 3.5 Real-time Updates
+
+**Features**:
+- **Realtime Subscriptions**:
+  - Subscribe to table changes via Supabase Realtime
+  - Listen for INSERT, UPDATE, DELETE events
+  - Show notification when another admin edits
+  
+- **Conflict Detection**:
+  - Detect concurrent edits on same row
+  - Show warning: "User X is editing this row"
+  - Lock row to prevent conflicts (optional)
+  
+- **Auto-refresh**:
+  - Toggle auto-refresh on/off
+  - Refresh interval: 10s, 30s, 60s
+  - Manual refresh button
+  
+- **Change Notifications**:
+  - Toast notification: "Table updated by Admin (3 rows changed)"
+  - Click to refresh table
+  - Dismiss notification
+
+**Implementation**:
+```tsx
+useEffect(() => {
+  const channel = supabase
+    .channel(`table:${tableName}`)
+    .on('postgres_changes', 
+      { 
+        event: '*', 
+        schema: 'public', 
+        table: tableName 
+      },
+      (payload) => {
+        toast.info(`Table updated: ${payload.eventType}`)
+        refetch() // Refetch table data
+      }
+    )
+    .subscribe()
+  
+  return () => {
+    supabase.removeChannel(channel)
+  }
+}, [tableName])
+```
+
+#### 3.6 Audit Trail Integration
+
+**Features**:
+- **Automatic Logging**:
+  - Every edit logged to `admin_audit_log`
+  - Log: admin_user_id, table, row_id, action, old_values, new_values, timestamp
+  
+- **Recent Changes Panel** (sidebar):
+  - Show last 20 changes on current table
+  - Display: timestamp, user, action, affected columns
+  - Click to view full details
+  
+- **Change Details Dialog**:
+  - Show before/after diff
+  - Highlight changed fields
+  - Show user who made change
+  - Link to row in table
+  
+- **Revert Functionality**:
+  - Revert single change (if safe)
+  - Check for dependent changes
+  - Confirmation dialog
+  - Cannot revert if related data deleted
+
+**Implementation**:
+```tsx
+const logDatabaseEdit = async (
+  tableName: string,
+  rowId: string,
+  operation: 'INSERT' | 'UPDATE' | 'DELETE',
+  oldValues: any,
+  newValues: any
+) => {
+  await supabase.rpc('log_database_direct_edit', {
+    _table_name: tableName,
+    _row_id: rowId,
+    _operation: operation,
+    _old_values: oldValues,
+    _new_values: newValues
+  })
+}
+
+// In updateData function:
+const handleUpdate = async (rowIndex, columnId, value) => {
+  const row = tableData[rowIndex]
+  const oldValue = row[columnId]
+  
+  // Update database
+  await supabase.from(tableName).update({ [columnId]: value }).eq('id', row.id)
+  
+  // Log audit trail
+  await logDatabaseEdit(
+    tableName,
+    row.id,
+    'UPDATE',
+    { [columnId]: oldValue },
+    { [columnId]: value }
+  )
+}
+```
+
+---
+
+## Database Requirements
+
+### Supabase RPC Functions
+
+#### 1. get_table_metadata()
+Returns metadata for all tables in public schema.
+
+```sql
+CREATE OR REPLACE FUNCTION get_table_metadata()
+RETURNS TABLE (
+  table_name text,
+  row_count bigint,
+  total_size text,
+  last_modified timestamp with time zone
+) 
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = 'public'
+AS $$
+BEGIN
+  RETURN QUERY
+  SELECT 
+    t.tablename::text as table_name,
+    COALESCE(c.reltuples::bigint, 0) as row_count,
+    pg_size_pretty(pg_total_relation_size(t.schemaname||'.'||t.tablename)) as total_size,
+    COALESCE(
+      (SELECT MAX(created_at) FROM information_schema.tables WHERE table_name = t.tablename),
+      NOW()
+    ) as last_modified
+  FROM pg_tables t
+  LEFT JOIN pg_class c ON c.relname = t.tablename
+  WHERE t.schemaname = 'public'
+  ORDER BY t.tablename;
+END;
+$$;
+
+-- Grant execute to admins only
+REVOKE EXECUTE ON FUNCTION get_table_metadata() FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION get_table_metadata() TO authenticated;
+
+-- RLS policy: only admins/superusers can execute
+CREATE POLICY "admin_only_table_metadata" ON ... -- (handled in calling code)
+```
+
+#### 2. get_table_schema(table_name text)
+Returns detailed schema information for a specific table.
+
+```sql
+CREATE OR REPLACE FUNCTION get_table_schema(_table_name text)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = 'public'
+AS $$
+DECLARE
+  schema_info jsonb;
+BEGIN
+  -- Get column information
+  SELECT jsonb_agg(
+    jsonb_build_object(
+      'name', column_name,
+      'type', data_type,
+      'isNullable', is_nullable = 'YES',
+      'maxLength', character_maximum_length,
+      'numericPrecision', numeric_precision,
+      'defaultValue', column_default,
+      'isPrimaryKey', EXISTS (
+        SELECT 1 FROM information_schema.table_constraints tc
+        JOIN information_schema.key_column_usage kcu
+          ON tc.constraint_name = kcu.constraint_name
+        WHERE tc.table_name = _table_name
+          AND tc.constraint_type = 'PRIMARY KEY'
+          AND kcu.column_name = c.column_name
+      ),
+      'foreignKey', (
+        SELECT jsonb_build_object(
+          'table', ccu.table_name,
+          'column', ccu.column_name
+        )
+        FROM information_schema.table_constraints tc
+        JOIN information_schema.key_column_usage kcu
+          ON tc.constraint_name = kcu.constraint_name
+        JOIN information_schema.constraint_column_usage ccu
+          ON ccu.constraint_name = tc.constraint_name
+        WHERE tc.table_name = _table_name
+          AND tc.constraint_type = 'FOREIGN KEY'
+          AND kcu.column_name = c.column_name
+        LIMIT 1
+      ),
+      'enumValues', (
+        SELECT array_agg(enumlabel)
+        FROM pg_enum e
+        JOIN pg_type t ON t.oid = e.enumtypid
+        WHERE t.typname = c.udt_name
+      )
+    )
+  )
+  INTO schema_info
+  FROM information_schema.columns c
+  WHERE table_name = _table_name
+    AND table_schema = 'public';
+  
+  RETURN schema_info;
+END;
+$$;
+```
+
+#### 3. log_database_direct_edit(...)
+Logs all direct database edits to audit trail.
+
+```sql
+CREATE OR REPLACE FUNCTION log_database_direct_edit(
+  _table_name text,
+  _row_id uuid,
+  _operation text,
+  _old_values jsonb,
+  _new_values jsonb
+)
+RETURNS void
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = 'public'
+AS $$
+BEGIN
+  INSERT INTO admin_audit_log (
+    admin_user_id,
+    target_user_id,
+    action,
+    details
+  ) VALUES (
+    auth.uid(),
+    NULL, -- No specific target user for direct DB edits
+    'direct_database_edit',
+    jsonb_build_object(
+      'table', _table_name,
+      'row_id', _row_id,
+      'operation', _operation,
+      'old_values', _old_values,
+      'new_values', _new_values,
+      'timestamp', NOW()
+    )
+  );
+END;
+$$;
+```
+
+### RLS Policies
+
+All tables must enforce AAL2 for admin/superuser direct edits:
+
+```sql
+-- Example policy for parks table
+CREATE POLICY "admin_direct_edit_requires_aal2"
+ON parks
+FOR ALL
+USING (
+  (
+    EXISTS (
+      SELECT 1 FROM user_roles
+      WHERE user_id = auth.uid()
+      AND role IN ('admin', 'superuser')
+    )
+  )
+  AND (
+    (auth.jwt() ->> 'aal') = 'aal2'
+    OR NOT EXISTS (
+      SELECT 1 FROM auth.mfa_factors
+      WHERE user_id = auth.uid()
+      AND status = 'verified'
+    )
+  )
+);
+
+-- Apply to all tables:
+-- parks, rides, companies, ride_models, locations, profiles, etc.
+```
+
+---
+
+## Implementation Roadmap
+
+### Sprint 1: Foundation (Days 1-3)
+**Goal**: Set up routes, navigation, and basic table browser
+
+**Tasks**:
+1. ✅ Create `/admin/database` route in router
+2. ✅ Create `AdminDatabase.tsx` page component
+3. ✅ Add "Database Editor" link to AdminSidebar (superuser only)
+4. ✅ Implement access control:
+   - Check `isAdmin()` or `isSuperuser()`
+   - Enforce AAL2 with `useSuperuserGuard()`
+   - Redirect if unauthorized
+5. ✅ Create `DatabaseTableBrowser.tsx` component
+6. ✅ Implement `get_table_metadata()` RPC function
+7. ✅ Fetch and display table list with metadata
+8. ✅ Add table categorization and color coding
+9. ✅ Implement table search/filter
+10. ✅ Add warning banner about direct DB access
+
+**Deliverables**:
+- Working `/admin/database` page
+- Table list with categories
+- Navigation from sidebar
+- AAL2 enforcement
+
+---
+
+### Sprint 2: Core Editor (Days 4-7)
+**Goal**: Build main spreadsheet editor with basic editing
+
+**Tasks**:
+1. ✅ Install dependencies: `@tanstack/react-virtual`
+2. ✅ Create `/admin/database/:tableName` route
+3. ✅ Create `DatabaseTableEditor.tsx` component
+4. ✅ Implement `get_table_schema()` RPC function
+5. ✅ Fetch table schema and generate dynamic columns
+6. ✅ Set up TanStack Table with:
+   - Core row model
+   - Pagination
+   - Row selection
+7. ✅ Implement basic inline editing:
+   - Text fields
+   - Number fields
+   - Boolean switches
+8. ✅ Add optimistic updates with rollback
+9. ✅ Implement save/error handling
+10. ✅ Add visual feedback (yellow → green → red)
+11. ✅ Create `log_database_direct_edit()` RPC function
+12. ✅ Integrate audit logging on all edits
+
+**Deliverables**:
+- Working table editor page
+- Inline editing for basic types
+- Audit logging functional
+
+---
+
+### Sprint 3: Advanced Editing (Days 8-10)
+**Goal**: Complete all cell editors, filtering, sorting, column config
+
+**Tasks**:
+1. ✅ Implement all cell editor types:
+   - Date/Timestamp picker
+   - UUID foreign key selector
+   - JSON editor with validation
+   - Enum dropdown
+   - Array/tag input
+2. ✅ Create `DatabaseTableFilters.tsx` component
+3. ✅ Implement filter builder UI
+4. ✅ Add filter functions for all data types
+5. ✅ Integrate TanStack Table filtering
+6. ✅ Add quick filters bar
+7. ✅ Implement saved filter presets
+8. ✅ Add multi-column sorting (Shift+Click)
+9. ✅ Create `DatabaseColumnConfig.tsx` component
+10. ✅ Implement column visibility toggle
+11. ✅ Add column reordering (drag-drop)
+12. ✅ Implement column pinning
+13. ✅ Add column layout presets
+14. ✅ Implement keyboard navigation
+15. ✅ Add global search
+
+**Deliverables**:
+- All cell editors working
+- Advanced filtering UI
+- Multi-column sorting
+- Column management panel
+- Keyboard shortcuts
+
+---
+
+### Sprint 4: Bulk & Export (Days 11-12)
+**Goal**: Add bulk operations and import/export functionality
+
+**Tasks**:
+1. ✅ Install dependencies: `papaparse`
+2. ✅ Create `DatabaseBulkActions.tsx` component
+3. ✅ Implement bulk edit functionality
+4. ✅ Implement bulk delete with confirmation
+5. ✅ Add batch update feature
+6. ✅ Create action history with undo
+7. ✅ Create `DatabaseExportImport.tsx` component
+8. ✅ Implement CSV export
+9. ✅ Implement JSON export
+10. ✅ Implement SQL export
+11. ✅ Add export options (scope, format)
+12. ✅ Implement CSV import with validation
+13. ✅ Implement JSON import
+14. ✅ Add import preview/dry-run
+15. ✅ Create batch export (all tables as ZIP)
+
+**Deliverables**:
+- Bulk operations working
+- Export in multiple formats
+- Import with validation
+- Action history with undo
+
+---
+
+### Sprint 5: Polish & Safety (Days 13-14)
+**Goal**: Add schema viewer, safety features, and final polish
+
+**Tasks**:
+1. ✅ Create `DatabaseSchemaViewer.tsx` component
+2. ✅ Implement columns view
+3. ✅ Add relationships/ERD view
+4. ✅ Display constraints and indexes
+5. ✅ Show RLS policies (read-only)
+6. ✅ Add SQL DDL view with syntax highlighting
+7. ✅ Implement read-only mode toggle
+8. ✅ Add confirmation dialogs for all destructive actions
+9. ✅ Implement real-time updates (Supabase Realtime)
+10. ✅ Create recent changes panel
+11. ✅ Add change details dialog with diff view
+12. ✅ Implement revert functionality (if safe)
+13. ✅ Add all safety warnings and checks
+14. ✅ Full testing (manual + automated if time)
+15. ✅ Write documentation (this file)
+
+**Deliverables**:
+- Complete schema viewer
+- All safety features
+- Real-time updates
+- Full testing
+- Documentation
+
+---
+
+## Dependencies
+
+### Required npm Packages
+
+```bash
+# Virtual scrolling for large tables
+npm install @tanstack/react-virtual
+
+# JSON viewer/editor
+npm install react-json-view-lite
+
+# Syntax highlighting
+npm install prismjs
+npm install @types/prismjs --save-dev
+
+# CSV parsing/generation
+npm install papaparse
+npm install @types/papaparse --save-dev
+```
+
+### Already Installed (✅)
+- `@tanstack/react-table` - Table management
+- `lucide-react` - Icons
+- `react-hook-form` - Form handling
+- `zod` - Validation
+- `date-fns` - Date utilities
+- `sonner` - Toast notifications
+
+---
+
+## Safety & UX Guidelines
+
+### Safety Features Checklist
+
+#### Confirmation Dialogs
+- [ ] Delete single row → "Delete this row?"
+- [ ] Delete multiple rows → "Delete X rows? This cannot be undone."
+- [ ] Bulk edit → "Update X rows?"
+- [ ] Drop table → "⚠️ DANGER: Delete entire table?"
+- [ ] Import data → "Import X rows? Existing data may be overwritten."
+
+#### Validation
+- [ ] Enforce NOT NULL constraints
+- [ ] Check data type compatibility
+- [ ] Validate foreign key references exist
+- [ ] Check max length for strings
+- [ ] Validate JSON syntax
+- [ ] Prevent orphan records (check dependencies)
+
+#### Access Control
+- [ ] AAL2 enforcement on page load
+- [ ] Re-check AAL2 before each destructive operation
+- [ ] Show MFA prompt if session drops to AAL1
+- [ ] Log all operations to audit trail
+
+#### Error Handling
+- [ ] Rollback optimistic updates on error
+- [ ] Show clear error messages
+- [ ] Prevent partial updates (use transactions)
+- [ ] Handle foreign key constraint violations gracefully
+
+#### Data Integrity
+- [ ] Warn before editing critical tables (auth, profiles)
+- [ ] Prevent editing system columns (id, created_at, etc.)
+- [ ] Check for circular foreign key dependencies
+- [ ] Validate enum values against allowed list
+
+---
+
+### UX Best Practices
+
+#### Loading States
+```tsx
+// Skeleton loader for table
+{isLoading && <TableSkeleton rows={10} cols={8} />}
+
+// Cell-level loading (during save)
+{isSaving && <Spinner className="w-4 h-4" />}
+
+// Progress bar for bulk operations
+<Progress value={progress} max={total} />
+```
+
+#### Error Feedback
+```tsx
+// Toast notifications
+toast.error('Failed to save: Foreign key violation')
+toast.success('Successfully updated 5 rows')
+toast.warning('Table has unsaved changes')
+
+// Inline validation
+<Input 
+  error={errors.email?.message}
+  className={errors.email && 'border-destructive'}
+/>
+```
+
+#### Keyboard Shortcuts
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+F` | Focus search |
+| `Ctrl+S` | Save current row |
+| `Ctrl+Z` | Undo last change |
+| `Del` | Delete selected rows |
+| `Ctrl+E` | Toggle edit mode |
+| `Escape` | Cancel edit / Close dialog |
+| `Enter` | Save edit / Submit form |
+| `Arrow keys` | Navigate cells |
+| `Tab` | Move to next cell |
+| `Shift+Tab` | Move to previous cell |
+| `Page Up/Down` | Scroll page |
+| `Home/End` | Jump to first/last row |
+| `?` | Show keyboard shortcuts help |
+
+#### Responsive Design
+- Horizontal scroll for tables on mobile
+- Collapsible filter/column panels
+- Touch-friendly cell editors (larger tap targets)
+- Stack filters vertically on small screens
+- Hide less important columns by default on mobile
+
+#### Dark Mode Support
+```css
+/* Table grid */
+.table-cell {
+  @apply border-border/40;
+  @apply hover:bg-accent/50;
+}
+
+/* Cell states */
+.cell-editing { @apply bg-yellow-500/20 dark:bg-yellow-500/10; }
+.cell-saved { @apply bg-green-500/20 dark:bg-green-500/10; }
+.cell-error { @apply bg-red-500/20 dark:bg-red-500/10; }
+
+/* Syntax highlighting */
+.json-editor {
+  @apply bg-background text-foreground;
+}
+```
+
+---
+
+## Security Considerations
+
+### Authentication & Authorization
+1. **AAL2 Enforcement**: All database operations require MFA verification
+2. **Role-Based Access**: Only admin/superuser roles can access
+3. **Session Monitoring**: Detect if session drops to AAL1 during use
+4. **Token Refresh**: Handle token expiration gracefully
+
+### Data Protection
+1. **Audit Logging**: Every edit logged with user, timestamp, before/after values
+2. **RLS Policies**: Enforce row-level security even in admin UI
+3. **Input Sanitization**: Validate all user input before DB writes
+4. **SQL Injection Prevention**: Use parameterized queries (Supabase handles this)
+
+### Rate Limiting
+```sql
+-- Prevent abuse: max 1000 edits per admin per hour
+CREATE POLICY "rate_limit_admin_edits"
+ON admin_audit_log
+FOR INSERT
+WITH CHECK (
+  (SELECT COUNT(*) FROM admin_audit_log 
+   WHERE admin_user_id = auth.uid() 
+   AND created_at > NOW() - INTERVAL '1 hour'
+   AND action = 'direct_database_edit') < 1000
+);
+```
+
+### Dangerous Operations Warning
+Display prominent warnings for:
+- Editing auth-related tables (profiles, user_roles)
+- Deleting > 100 rows at once
+- Importing > 1000 rows
+- Editing production environment (if detected)
+
+---
+
+## Testing Strategy
+
+### Manual Testing Checklist
+- [ ] AAL2 enforcement blocks AAL1 users
+- [ ] Non-admin users cannot access page
+- [ ] All table categories display correctly
+- [ ] Table search/filter works
+- [ ] Table editor loads data correctly
+- [ ] Inline editing saves successfully
+- [ ] Optimistic updates rollback on error
+- [ ] All cell editor types work
+- [ ] Filtering works for all data types
+- [ ] Multi-column sorting works
+- [ ] Column visibility toggle works
+- [ ] Column reordering works
+- [ ] Pagination works correctly
+- [ ] Global search highlights matches
+- [ ] Keyboard navigation works
+- [ ] Bulk edit updates multiple rows
+- [ ] Bulk delete confirms and deletes
+- [ ] Export CSV/JSON/SQL works
+- [ ] Import validates and inserts data
+- [ ] Schema viewer displays correctly
+- [ ] Real-time updates show notifications
+- [ ] Audit trail logs all edits
+- [ ] Recent changes panel displays edits
+- [ ] Revert functionality works
+- [ ] Confirmation dialogs show for destructive actions
+- [ ] Read-only mode prevents edits
+- [ ] Dark mode styling looks good
+
+### Automated Testing (Future)
+```typescript
+// Example Playwright test
+test('admin can edit table cell', async ({ page }) => {
+  await loginAsAdmin(page)
+  await page.goto('/admin/database/parks')
+  
+  // Click cell to edit
+  await page.click('[data-cell="name-0"]')
+  await page.fill('input', 'New Park Name')
+  await page.press('input', 'Enter')
+  
+  // Wait for save
+  await page.waitForSelector('.cell-saved')
+  
+  // Verify in database
+  const park = await getParkByName('New Park Name')
+  expect(park).toBeTruthy()
+})
+```
+
+---
+
+## Future Enhancements
+
+### Phase 2 Features (Post-MVP)
+1. **SQL Query Console**:
+   - Raw SQL query interface
+   - Query history
+   - Result set export
+   - Query templates/snippets
+   
+2. **Visual Query Builder**:
+   - Drag-drop JOIN builder
+   - Visual WHERE clause builder
+   - Preview results
+   
+3. **Scheduled Jobs**:
+   - Schedule bulk updates
+   - Automated cleanup scripts
+   - Email reports
+   
+4. **Advanced Analytics**:
+   - Table usage statistics
+   - Most edited tables
+   - Edit frequency heatmap
+   - Admin activity dashboard
+   
+5. **Version Control Integration**:
+   - Git-like diff view
+   - Branch/merge for schema changes
+   - Rollback to previous states
+   
+6. **Collaboration Features**:
+   - Live presence indicators (who's viewing)
+   - Comments on rows
+   - Change proposals (before applying)
+   - Team chat in context
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: "AAL2 required" error blocks access
+- **Solution**: Ensure user has MFA enrolled and verified. Prompt to verify MFA if session is at AAL1.
+
+**Issue**: Table loads slowly (> 5s)
+- **Solution**: Add pagination, reduce pageSize, add indexes to frequently filtered columns.
+
+**Issue**: Foreign key dropdown shows too many options
+- **Solution**: Add search/autocomplete to dropdown, paginate results, show only recent 100.
+
+**Issue**: JSON editor loses formatting on save
+- **Solution**: Ensure JSON is pretty-printed before display, preserve whitespace.
+
+**Issue**: Real-time updates cause table to jump
+- **Solution**: Use optimistic updates, throttle refresh notifications, show "refresh available" button instead of auto-refresh.
+
+**Issue**: Export fails for large tables (> 10k rows)
+- **Solution**: Stream export instead of loading all in memory, show progress bar, split into chunks.
+
+---
+
+## Related Documentation
+- [DATABASE_ARCHITECTURE.md](./DATABASE_ARCHITECTURE.md) - Database schema and RLS policies
+- [ARCHITECTURE_OVERVIEW.md](./ARCHITECTURE_OVERVIEW.md) - System architecture
+- [ADMIN_FEATURES.md](./ADMIN_FEATURES.md) - Other admin features (if exists)
+
+---
+
+## Change Log
+
+| Date | Version | Changes | Author |
+|------|---------|---------|--------|
+| 2025-01-XX | 1.0.0 | Initial documentation | System |
+
+---
+
+## Approval & Sign-off
+
+**Status**: 📋 Planned (awaiting approval)
+
+**Reviewed By**: _Pending_
+
+**Approved By**: _Pending_
+
+**Implementation Start Date**: _TBD_
+
+**Expected Completion**: _TBD_ (14 days after start)
+
+---
+
+*End of Document*