# uzdb User Flows

## 1. First-Time User Experience

```
┌─────────────────┐
│  Launch App     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Empty State:    │
│ "No Connections"│
└────────┬────────┘
         │
         │ Click "New Connection"
         ▼
┌─────────────────┐
│ Connection      │
│ Wizard          │
│ 1. Select Type  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 2. Configure    │
│ Connection      │
│ (Host, Port,    │
│  Credentials)   │
└────────┬────────┘
         │
         │ Click "Test Connection"
         ▼
┌─────────────────┐
│ Test Result     │
│ ✓ Success       │
│ ✕ Error + Help  │
└────────┬────────┘
         │
         │ Save & Connect
         ▼
┌─────────────────┐
│ Main Interface  │
│ with Schema     │
│ Explorer        │
└─────────────────┘
```

---

## 2. Query Execution Flow

```
┌─────────────────┐
│ Open Query Tab  │
│ (Ctrl+T)        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Write/Edit SQL  │
│ - Syntax        │
│   highlighting  │
│ - Autocomplete  │
│ - Snippets      │
└────────┬────────┘
         │
         │ Ctrl+Enter or Click Run
         ▼
┌─────────────────┐
│ Execute Query   │
│ Show loading    │
│ indicator       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Display Results │
│ - Data grid     │
│ - Row count     │
│ - Execution time│
│ - Status        │
└────────┬────────┘
         │
         ├──────────────┬──────────────┐
         ▼              ▼              ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Export Data │ │ Edit Cell   │ │ Save Query  │
│ (CSV, JSON) │ │ (Inline)    │ │ (.sql file) │
└─────────────┘ └─────────────┘ └─────────────┘
```

---

## 3. Table Browsing Flow

```
┌─────────────────┐
│ Expand Database │
│ in Sidebar      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Expand Schema   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Click Table     │
└────────┬────────┘
         │
         ├─────────────────┬────────────────┐
         ▼                 ▼                ▼
┌─────────────┐   ┌─────────────┐  ┌─────────────┐
│ Preview Top │   │ View        │  │ Open Table  │
│ 100 Rows    │   │ Structure   │  │ Details     │
│ (Double-click)│  │ (Right panel)│  │ Panel       │
└─────────────┘   └─────────────┘  └─────────────┘
                                              │
                                              ▼
                                     ┌─────────────────┐
                                     │ Columns, Indexes│
                                     │ Foreign Keys,   │
                                     │ Triggers        │
                                     └─────────────────┘
```

---

## 4. Connection Management Flow

### Add New Connection
```
┌─────────────────┐
│ Click "+"       │
│ or File > New   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Select DB Type  │
│ ○ MySQL         │
│ ○ PostgreSQL    │
│ ○ SQLite        │
│ ○ MariaDB       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Fill Form       │
│ - Name          │
│ - Host/Port     │
│ - Auth          │
│ - Advanced opts │
└────────┬────────┘
         │
         │ Test Connection
         ▼
┌─────────────────┐
│ Connection Test │
│ Result          │
└────────┬────────┘
         │
         │ Success → Save
         ▼
┌─────────────────┐
│ Added to        │
│ Connection List │
└─────────────────┘
```

### Edit/Delete Connection
```
┌─────────────────┐
│ Right-click     │
│ Connection      │
└────────┬────────┘
         │
         ├─────────────┬──────────────┐
         ▼             ▼              ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Edit        │ │ Duplicate   │ │ Delete      │
│ Connection  │ │ Connection  │ │ Connection  │
└─────────────┘ └─────────────┘ └──────┬──────┘
                                       │
                                       ▼
                              ┌─────────────────┐
                              │ Confirm Delete  │
                              │ "Are you sure?" │
                              └────────┬────────┘
                                       │
                                       ▼
                              ┌─────────────────┐
                              │ Connection      │
                              │ Removed         │
                              └─────────────────┘
```

---

## 5. Data Export Flow

```
┌─────────────────┐
│ Select Data     │
│ (table/query    │
│  results)       │
└────────┬────────┘
         │
         │ Click Export button
         ▼
┌─────────────────┐
│ Export Dialog   │
│ - Format:       │
│   CSV/JSON/SQL  │
│ - Options       │
│ - Destination   │
└────────┬────────┘
         │
         │ Configure options
         ▼
┌─────────────────┐
│ Review Settings │
│ - Preview       │
│ - Row count     │
│ - File size est.│
└────────┬────────┘
         │
         │ Click Export
         ▼
┌─────────────────┐
│ Export Progress │
│ [████████░░] 80%│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Export Complete │
│ ✓ 1,234 rows    │
│   exported to   │
│   /path/file.csv│
│                 │
│ [Open File]     │
└─────────────────┘
```

---

## 6. Error Handling Flow

### Connection Error
```
┌─────────────────┐
│ Attempt Connect │
└────────┬────────┘
         │
         │ Fails
         ▼
┌─────────────────┐
│ Error Dialog    │
│ ┌─────────────┐ │
│ │ ⚠ Connection│ │
│ │   Failed    │ │
│ │             │ │
│ │ ECONNREFUSED│ │
│ │ localhost:  │ │
│ │ 3306        │ │
│ └─────────────┘ │
│                 │
│ Common causes:  │
│ • Server not    │
│   running       │
│ • Wrong port    │
│ • Firewall      │
│                 │
│ [Retry] [Help]  │
└─────────────────┘
```

### Query Error
```
┌─────────────────┐
│ Execute Query   │
└────────┬────────┘
         │
         │ Syntax Error
         ▼
┌─────────────────┐
│ Results Panel   │
│ Shows error:    │
│ ┌─────────────┐ │
│ │ ❌ Error    │ │
│ │ Line 3:     │ │
│ │ Unknown col │ │
│ │ 'emai'      │ │
│ │             │ │
│ │ SELECT id,  │ │
│ │        emai │ │
│ │        ^^^^ │ │
│ └─────────────┘ │
└─────────────────┘
```

---

## 7. Keyboard Navigation Flow

```
Global Shortcuts:
- Ctrl+N: New connection
- Ctrl+T: New query tab
- Ctrl+S: Save
- Ctrl+W: Close tab
- Ctrl+Enter: Run query
- Ctrl+F: Find in editor
- Ctrl+,: Settings

Within Data Grid:
- Arrow keys: Navigate cells
- Enter: Edit cell
- Esc: Cancel edit
- Ctrl+C: Copy selection
- Ctrl+F: Filter column

Within Query Editor:
- Ctrl+Space: Autocomplete
- Tab: Insert snippet
- Ctrl+/: Toggle comment
- Ctrl+D: Duplicate line
```

---

## 8. Settings/Preferences Flow

```
┌─────────────────┐
│ Tools > Settings│
│ or Ctrl+,       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Settings Modal  │
│ ┌─────────────┐ │
│ │ General     │ │ ← Selected
│ │ Editor      │ │
│ │ Data Grid   │ │
│ │ Keybindings │ │
│ │ Themes      │ │
│ └─────────────┘ │
│                 │
│ ┌─────────────┐ │
│ │ Font size   │ │
│ │ [14    ▼]   │ │
│ │             │ │
│ │ Theme       │ │
│ │ [Light  ▼]  │ │
│ │             │ │
│ │ Auto-save   │ │
│ │ [✓]         │ │
│ └─────────────┘ │
│                 │
│   [Reset] [OK]  │
└─────────────────┘
```

---

## Edge Cases Handled

1. **Lost Connection During Query**
   - Show error message
   - Offer to reconnect
   - Preserve query text

2. **Large Result Sets (>10k rows)**
   - Warn user before loading all
   - Offer to limit results
   - Provide streaming option

3. **Unsaved Changes on Close**
   - Prompt to save
   - Auto-save to temp file
   - Restore on relaunch

4. **Multiple Tabs with Same Connection**
   - Share connection instance
   - Independent transactions
   - Clear tab indicators

5. **Long-running Queries**
   - Show progress if available
   - Provide cancel button
   - Timeout configuration