# UX Reference: Superset-Style Redesign

## Persona
**Alex, Data Engineer / Superset Admin**
Alex manages dozens of dashboards across Dev, Staging, and Prod. Alex needs to quickly move changes between environments, check if a dashboard is in sync with Git, and fix mapping issues without losing context.

## Context
The current UI is "Tool-Centric" (Go to Migration Tool -> Select Dashboard). The new UI is "Resource-Centric" (Go to Dashboards -> Find "Sales" -> Click Migrate).

## Happy Path: Migrating Dashboards (Bulk)

1.  **Discovery**: Alex opens the app and lands on the **Dashboard Hub**.
2.  **Selection**: Alex selects "Production" from the environment dropdown. The grid populates with production dashboards.
3.  **Bulk Selection**: Alex clicks "Select Visible" to select all 10 dashboards on the current page, then manually unchecks 2 dashboards.
4.  **Action**: A floating panel appears at the bottom: "[✓ 8 selected] [Migrate] [Backup]". Alex clicks **Migrate**.
5.  **Configuration**: A modal appears showing:
    - Source: Production (read-only)
    - Target Environment dropdown: Alex selects "Staging"
    - Database Mappings table showing existing mappings with match percentages
    - Selected dashboards list (8 items)
6.  **Mapping Review**: Alex sees one database has 85% match and clicks "Edit" to adjust the mapping.
7.  **Start**: Alex clicks "Start Migration". The modal closes.
8.  **Monitoring**: The **Task Drawer** slides out from the right automatically, showing 8 migration tasks starting.
9.  **Interaction**: One migration is paused because a database password is required. A password field appears *inside* the drawer.
10. **Completion**: Alex enters the password. All 8 migrations finish. The drawer shows green "Success" messages. Alex closes the drawer and is still looking at the Dashboard Hub list.

## Happy Path: Backing Up Dashboards (Scheduled)

1.  **Discovery**: Alex opens the app and lands on the **Dashboard Hub**.
2.  **Selection**: Alex selects "Production" from the environment dropdown.
3.  **Bulk Selection**: Alex manually checks 3 critical dashboards: "Sales Overview", "HR Analytics", "Finance Dashboard".
4.  **Action**: The floating panel appears: "[✓ 3 selected] [Migrate] [Backup]". Alex clicks **Backup**.
5.  **Configuration**: A modal appears showing:
    - Environment: Production (read-only)
    - Selected dashboards list (3 items)
    - Schedule options: "One-time backup" or "Schedule backup"
6.  **Schedule Setup**: Alex selects "Schedule backup" and enters cron expression "0 2 * * *" for daily 2 AM backups.
7.  **Start**: Alex clicks "Start Backup". The modal closes.
8.  **Monitoring**: The **Task Drawer** slides out showing the backup task running.
9.  **Completion**: The backup finishes successfully. The drawer confirms the schedule is set up. Alex closes the drawer.

## Happy Path: Mapping Dataset Columns

1.  **Discovery**: Alex navigates to **Datasets** in the sidebar.
2.  **Selection**: Alex selects "Production" environment. The grid shows all datasets.
3.  **Search**: Alex types "sales" in the search box to filter to sales-related datasets.
4.  **Selection**: Alex checks 2 datasets: "Sales Data" and "Sales Summary".
5.  **Action**: The floating panel appears: "[✓ 2 selected] [Map Columns] [Generate Docs]". Alex clicks **Map Columns**.
6.  **Configuration**: A modal appears:
    - Source selection: "PostgreSQL Comments" or "Upload XLSX"
    - Connection dropdown: Alex selects "Prod_PG_Readonly"
7.  **Preview**: The modal shows a preview of current vs new column names based on PostgreSQL comments.
8.  **Apply**: Alex clicks "Apply Mapping". The modal closes.
9.  **Monitoring**: The **Task Drawer** slides out showing the mapping progress.
10. **Completion**: Both datasets are updated with verbose names from PostgreSQL comments. Alex closes the drawer and sees the "Mapped" column updated to 100% for both datasets.

## Mockups

### Top Navigation Bar
```text
+-----------------------------------------------------------------------+
| [≡]  Superset Tools     [🔍 Search...]        [Activity (3)]  [👤 ▼] |
+-----------------------------------------------------------------------+
```
- **[≡] Hamburger**: Mobile-only toggle for sidebar.
- **Logo**: Returns to Home/Dashboard Hub.
- **Search**: Placeholder for future global search.
- **Activity (3)**: Badge shows count of running tasks. Clicking opens Task Drawer.
- **User Menu**: Dropdown with Profile, Settings, Logout.

### Sidebar (Expanded)
```text
+------------------+
| ▽ DASHBOARDS     |
|   Overview       |
+------------------+
| ▽ DATASETS       |
|   All Datasets   |
+------------------+
| ▽ STORAGE        |
|   Backups        |
|   Repositories   |
+------------------+
| ▽ ADMIN          |
|   Users          |
|   Roles          |
|   Settings       |
+------------------+
| [◀ Collapse]     |
+------------------+
```

### Sidebar (Collapsed)
```text
+---+
| D | (Dashboards - Active)
| T | (Datasets)
| S | (Storage)
+---+
| A | (Admin)
+---+
| ▶ |
+---+
```

### Dataset Hub Grid
```text
+-----------------------------------------------------------------------+
| Env: [ Production (v) ]  [🔍 Search...]                [ Refresh ] |
+-----------------------------------------------------------------------+
| [☑] Select All  [☐] Select Visible (5)                       |
+-----------------------------------------------------------------------+
| ☐ | Name            | Database       | Schema | Tables | Columns | Mapped | Updated By | Actions |
|----|-----------------|---------------|--------|--------|---------|--------|------------|---------|
| ☑ | Sales Data      | Prod_CH       | sales  | 3      | 45/50   | 90%    | john.doe   | [...]   |
| ☐ | HR Analytics     | Prod_PG       | hr     | 5      | 32/40   | 80%    | jane.smith | [...]   |
| ☐ | Finance Metrics | Prod_CH       | fin    | 2      | 28/28   | 100%   | admin     | [...]   |
+-----------------------------------------------------------------------+
| Showing 1-10 of 120 | [<] 1 2 3 4 5 [>] | Rows per page: [10 (v)] |
+-----------------------------------------------------------------------+
| [✓ 1 selected]  [Map Columns] [Generate Docs] [Validate]              |
+-----------------------------------------------------------------------+
```

**Columns:**
- **Name**: Dataset name (clickable to view details)
- **Database**: Source database name (e.g., Prod_CH, Prod_PG)
- **Schema**: Database schema name
- **Tables**: Count of SQL tables extracted from dataset's SQL scripts
- **Columns**: Total column count (X/Y where Y = total, X = mapped)
- **Mapped**: Percentage of columns with verbose_name filled
- **Updated By**: User who last modified the dataset
- **Actions**: Dropdown with individual actions

**Bulk Actions Panel (appears when datasets are selected):**
- Shows count of selected datasets
- **Map Columns**: Opens modal to configure column mappings from external source (PostgreSQL comments or XLSX)
- **Generate Docs**: Uses LLM to generate documentation for selected datasets
- **Validate**: Validates dataset structure and data integrity

**Selection Controls:**
- **Select All**: Selects all datasets across all pages
- **Select Visible**: Selects only datasets on current page
- Individual checkboxes for granular selection

**Search:**
- Real-time search by dataset name, schema, or table names
- Filters the list immediately as user types

### Dataset Detail View
```text
+-----------------------------------------------------------------------+
| ← Back to Datasets    Sales Data                      [ Refresh ]    |
+-----------------------------------------------------------------------+
| Database: Prod_CH  |  Schema: sales  |  Updated: 2024-01-15 14:30   |
| Updated By: john.doe  |  Owner: john.doe                             |
+-----------------------------------------------------------------------+
| Tables (3):                                                         |
| +-----------------------------------------------------------------+ |
| | Table: sales_transactions                                      |     |
| | Columns: 25 (22 mapped - 88%)                            |     |
| | [View Columns] [Map Columns]                              |     |
| +-----------------------------------------------------------------+ |
| | Table: sales_summary                                         |     |
| | Columns: 15 (15 mapped - 100%)                           |     |
| | [View Columns] [Map Columns]                              |     |
| +-----------------------------------------------------------------+ |
| | Table: sales_by_region                                      |     |
| | Columns: 10 (10 mapped - 100%)                           |     |
| | [View Columns] [Map Columns]                              |     |
| +-----------------------------------------------------------------+ |
+-----------------------------------------------------------------------+
| Linked Dashboards (5):                                              |
| • Sales Overview • Sales Trends • Regional Sales • ... [+More]              |
+-----------------------------------------------------------------------+
| Actions:                                                            |
| [Generate Documentation] [Validate Structure] [Export Metadata]             |
+-----------------------------------------------------------------------+
```

**Features:**
- Shows dataset metadata at top
- Lists all SQL tables extracted from dataset
- For each table: column count, mapping percentage, quick actions
- Shows linked dashboards (requires dataset-to-dashboard relationship algorithm)
- Bulk actions for the entire dataset

### Column Mapping Modal
```text
+---------------------------------------------------------------+
| Map Columns: sales_transactions (Sales Data)            [X]     |
+---------------------------------------------------------------+
|                                                               |
| Source: [ PostgreSQL Comments (v) ]                                |
|         Connection: [ Prod_PG_Readonly (v) ]  [Test]               |
|                                                               |
| Or upload file: [ Choose XLSX file... ]                            |
|                                                               |
| Mapping Preview:                                              |
| +-----------------------------------------------------------+ |
| | Column Name        | Current Verbose  | New Verbose    |     |
| |-------------------|-----------------|----------------|     |
| | id                | ID              | Transaction ID  |     |
| | transaction_date  | Date            | Transaction Date|     |
| | amount            | Amount          | Amount ($)     |     |
| | customer_id       | Customer ID     | Customer ID    |     |
| +-----------------------------------------------------------+ |
|                                                               |
| [ Cancel ]              [ Apply Mapping ]                   |
+---------------------------------------------------------------+
```

**Features:**
- Choose between PostgreSQL comments or XLSX file as source
- Select connection for PostgreSQL
- Upload XLSX file with column mappings
- Preview of current vs new verbose names
- Applies mapping to Superset dataset via MapperPlugin

### Documentation Generation Modal
```text
+---------------------------------------------------------------+
| Generate Documentation: Sales Data                         [X]     |
+---------------------------------------------------------------+
|                                                               |
| Selected datasets (2):                                          |
|   ☑ Sales Data                                                  |
|   ☑ HR Analytics                                               |
|                                                               |
| LLM Provider: [ OpenAI GPT-4 (v) ]                             |
|                                                               |
| Options:                                                      |
|   ☐ Include column descriptions                                  |
|   ☑ Generate usage examples                                     |
|   ☐ Add business context                                       |
|                                                               |
| Language: [ English (v) ]                                       |
|                                                               |
| [ Cancel ]              [ Generate ]                         |
+---------------------------------------------------------------+
```

**Features:**
- Lists selected datasets
- Select LLM provider for generation
- Options for documentation scope
- Language selection
- Task Drawer opens to show generation progress

### Dashboard Hub Grid
```text
+-----------------------------------------------------------------------+
| Env: [ Production (v) ]  [🔍 Search...]                [ Refresh ] |
+-----------------------------------------------------------------------+
| [☑] Select All  [☐] Select Visible (5)                       |
+-----------------------------------------------------------------------+
| ☐ | Title           | Git Status    | Last Task | Actions               |
|----|-----------------|---------------|-----------|-----------------------|
| ☑ | Sales Report    | [v] main      | [v] Done  | [...]                 |
| ☐ | HR Analytics    | [!] Diff      | [@] Run.. | [...]                 |
| ☐ | Finance Overview| [v] main      | [v] Done  | [...]                 |
+-----------------------------------------------------------------------+
| Showing 1-10 of 45 | [<] 1 2 3 4 5 [>] | Rows per page: [10 (v)] |
+-----------------------------------------------------------------------+
| [✓ 1 selected]  [Migrate] [Backup]                                    |
+-----------------------------------------------------------------------+
```

**Bulk Actions Panel (appears when dashboards are selected):**
- Shows count of selected dashboards
- **Migrate** button: Opens modal for target environment selection and database mapping configuration
- **Backup** button: Opens modal for backup configuration (with optional cron schedule setup)
- Panel slides up from bottom or appears as floating bar at bottom

**Selection Controls:**
- **Select All**: Selects all dashboards across all pages (shows total count)
- **Select Visible**: Selects only dashboards on current page (shows visible count)
- Individual checkboxes in each row for granular selection

**Pagination:**
- Classic pagination with page numbers
- "Rows per page" dropdown (10, 25, 50, 100)
- Shows "Showing X-Y of Z total"

**Search:**
- Real-time search by dashboard title/slug
- Filters the list immediately as user types

### Bulk Migration Modal
```text
+---------------------------------------------------------------+
| Migrate 3 Dashboards                                   [X]     |
+---------------------------------------------------------------+
|                                                               |
| Source Environment: Production (read-only)                         |
|                                                               |
| Target Environment: [ Staging (v) ]                              |
|                                                               |
| Database Mappings:                                            |
| +-----------------------------------------------------------+ |
| | Source Database           | Target Database   | Match % |     |
| |------------------------|-----------------|----------|     |
| | Prod_Clickhouse_10      | Staging_CH_10    | 95%      | [Edit]|
| | Prod_Postgres_5        | Staging_PG_5     | 100%     | [Edit]|
| +-----------------------------------------------------------+ |
|                                                               |
| Selected dashboards:                                          |
|   ☑ Sales Report                                              |
|   ☑ HR Analytics                                              |
|   ☑ Finance Overview                                          |
|                                                               |
| [ Cancel ]              [ Start Migration ]                   |
+---------------------------------------------------------------+
```

**Features:**
- Shows source environment (read-only, from current hub view)
- Dropdown to select target environment
- Displays database mappings between source and target
- Shows match confidence percentage (from fuzzy matching)
- "Edit" button to modify mappings if needed
- Lists all selected dashboards
- Task Drawer opens automatically after starting migration

### Bulk Backup Modal
```text
+---------------------------------------------------------------+
| Backup 3 Dashboards                                    [X]     |
+---------------------------------------------------------------+
|                                                               |
| Environment: Production (read-only)                              |
|                                                               |
| Selected dashboards:                                          |
|   ☑ Sales Report                                              |
|   ☑ HR Analytics                                              |
|   ☑ Finance Overview                                          |
|                                                               |
| Schedule:                                                     |
|   ○ One-time backup                                           |
|   ○ Schedule backup:                                           |
|     Cron expression: [ 0 2 * * * ] (daily at 2 AM)           |
|     [ Help with cron syntax ]                                      |
|                                                               |
| [ Cancel ]              [ Start Backup ]                      |
+---------------------------------------------------------------+
```

**Features:**
- Shows environment (read-only, from current hub view)
- Lists all selected dashboards
- Option for one-time backup or scheduled backup
- Cron expression input for scheduling
- Link to cron syntax help
- Task Drawer opens automatically after starting backup

### Settings Page (Consolidated)
```text
+-----------------------------------------------------------------------+
| Settings                                                              |
+-----------------------------------------------------------------------+
| [Environments]  [Connections]  [LLM Providers]  [Logging]  [System]   |
+-----------------------------------------------------------------------+
|                                                                       |
|  Environments                                                         |
|  +-------------------------------------------------------------+     |
|  | Name         | URL                    | Status   | Actions |     |
|  |--------------|------------------------|----------|---------|     |
|  | Development  | http://dev.superset... | [v] OK   | [Edit]  |     |
|  | Production   | http://prod.superset...| [!] Error| [Edit]  |     |
|  +-------------------------------------------------------------+     |
|                                                                       |
+-----------------------------------------------------------------------+
```

### Task Drawer (Active)
```text
          +---------------------------------------+
          | Task: Migration (Sales)           [X] |
          +---------------------------------------+
          | [INFO] Exporting...                   |
          | [INFO] Validating...                  |
          | [WARN] Password required              |
          |                                       |
          | Password: [**********]                |
          | [ Resume ] [ Cancel ]                 |
          +---------------------------------------+
```

## Error Experience

### Scenario: Migration Fails
- **Visual Cue**: The "Last Task" badge in the grid turns **Red (X)**.
- **Notification**: A toast message appears: "Migration Failed: Database Connection Error".
- **Resolution**: Alex clicks the Red (X). The Task Drawer opens, scrolled to the bottom, highlighting the error in red. Alex can see the full stack trace or error message to debug.

### Scenario: Environment Offline
- **Visual Cue**: When selecting an environment, a "Connection Error" banner appears at the top of the grid.
- **Action**: The "Refresh" button turns into a "Retry" button.