ss-tools/specs/019-superset-ux-redesign/quickstart.md

Quickstart: Superset-Style UX Redesign

Feature: 019-superset-ux-redesign Date: 2026-02-09

Prerequisites

• Node.js 18+ (for frontend)
• Python 3.9+ (for backend)
• Existing backend running on http://localhost:8000
• Existing frontend running on http://localhost:5173

Implementation Order

Phase 1: Core Layout (P1)

1. Create Sidebar Component (frontend/src/lib/components/layout/Sidebar.svelte)

   • Categories: DASHBOARDS, DATASETS, STORAGE, ADMIN
   • Collapse/expand toggle
   • Active item highlighting
   • Mobile responsive (hamburger menu)

2. Create TopNavbar Component (frontend/src/lib/components/layout/TopNavbar.svelte)

   • Logo/brand
   • Search placeholder
   • Activity indicator (badge count)
   • User menu dropdown

3. Create SidebarStore (frontend/src/lib/stores/sidebar.js)

   • isExpanded state with localStorage persistence
   • activeCategory and activeItem tracking

4. Update Root Layout (frontend/src/routes/+layout.svelte)

   • Import Sidebar and TopNavbar
   • Create main content area with proper spacing

Phase 2: Task Drawer (P1)

5. Create TaskDrawerStore (frontend/src/lib/stores/taskDrawer.js)

   • isOpen state
   • activeTaskId
   • resourceTaskMap for resource-to-task mapping

6. Create TaskDrawer Component (frontend/src/lib/components/layout/TaskDrawer.svelte)

   • Slide-out panel from right
   • Log stream area (reuse TaskLogViewer)
   • Interactive area for inputs (PasswordPrompt, etc.)

7. Create ActivityStore (frontend/src/lib/stores/activity.js)

   • Derived store counting active tasks
   • Connect to WebSocket for real-time updates

Phase 3: Resource Hubs (P2)

8. Create Dashboard Hub (frontend/src/routes/dashboards/+page.svelte)

   • Environment selector
   • Dashboard grid with columns: Title, Slug, Git Status, Last Task, Actions
   • Actions menu: Migrate, Backup, Git Operations

9. Create Dataset Hub (frontend/src/routes/datasets/+page.svelte)

   • Environment selector
   • Dataset grid with columns: Table Name, Schema, Mapped Fields, Last Task, Actions

10. Create Backend APIs (backend/src/api/routes/)

    • GET /api/dashboards?env_id=X
    • GET /api/datasets?env_id=X
    • GET /api/activity

Phase 4: Settings Consolidation (P2)

11. Create Settings Page (frontend/src/routes/settings/+page.svelte)

    • Tabbed interface: Environments, Connections, LLM, Logging, System
    • Role-based visibility for admin tabs

12. Create Settings API (backend/src/api/routes/settings.py)

    • GET /api/settings (consolidated)

Testing

Manual Testing Checklist

• Sidebar collapses/expands with animation
• Sidebar state persists after page refresh
• Activity indicator shows correct count
• Task Drawer opens when clicking status badge
• Task Drawer shows real-time logs
• Dashboard Hub loads dashboards from selected environment
• Actions menu triggers correct operations
• Settings page shows all categories (admin) / limited (non-admin)

Automated Tests

# Frontend component tests
cd frontend && npm run test -- --grep "Sidebar|TaskDrawer|DashboardHub"

# Backend API tests
cd backend && pytest tests/test_dashboards_api.py tests/test_datasets_api.py

Key Files Reference

Component	Path
Sidebar	frontend/src/lib/components/layout/Sidebar.svelte
TopNavbar	frontend/src/lib/components/layout/TopNavbar.svelte
TaskDrawer	frontend/src/lib/components/layout/TaskDrawer.svelte
DashboardHub	frontend/src/routes/dashboards/+page.svelte
DatasetHub	frontend/src/routes/datasets/+page.svelte
SettingsPage	frontend/src/routes/settings/+page.svelte
sidebarStore	frontend/src/lib/stores/sidebar.js
taskDrawerStore	frontend/src/lib/stores/taskDrawer.js
activityStore	frontend/src/lib/stores/activity.js
dashboards API	backend/src/api/routes/dashboards.py
datasets API	backend/src/api/routes/datasets.py