# Implementation Plan: Superset-Style UX Redesign

**Branch**: `019-superset-ux-redesign` | **Date**: 2026-02-09 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/019-superset-ux-redesign/spec.md`

## Summary

Redesign the application from a **Task-Centric** model (users navigate to tools) to a **Resource-Centric** model (users navigate to resources like Dashboards, Datasets). Key components include:
- Persistent left sidebar with resource categories
- Global Task Drawer for monitoring background operations
- Dashboard Hub and Dataset Hub as primary management interfaces
- Unified top navigation bar with activity indicator
- Consolidated Settings section

## Technical Context

**Language/Version**: Python 3.9+ (Backend), Node.js 18+ (Frontend)
**Primary Dependencies**: FastAPI, SvelteKit, Tailwind CSS, SQLAlchemy, WebSocket (existing)
**Storage**: SQLite (tasks.db, auth.db, migrations.db) - no new database tables required
**Testing**: pytest (backend), Vitest/Playwright (frontend)
**Target Platform**: Web (Desktop primary, responsive for mobile)
**Project Type**: Web application (frontend + backend)
**Performance Goals**: Task Drawer opens < 200ms, sidebar animation < 300ms
**Constraints**: No blocking modals for task inputs, real-time log streaming via WebSocket
**Scale/Scope**: ~20 new frontend components, 5 new API endpoints, 3 new stores

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

| Principle | Status | Notes |
|-----------|--------|-------|
| I. Semantic Protocol Compliance | ✅ PASS | All new components will use [DEF] anchors and @UX_STATE tags |
| II. Everything is a Plugin | ✅ PASS | No new plugins required; existing plugins (Migration, Backup, Git) will be triggered from Resource Hubs |
| III. Unified Frontend Experience | ✅ PASS | Using existing component library, i18n system, and requestApi wrapper |
| IV. Security & Access Control | ✅ PASS | ADMIN section visibility controlled by existing RBAC |
| V. Independent Testability | ✅ PASS | Each User Story has defined independent test scenarios |
| VI. Asynchronous Execution | ✅ PASS | Task Drawer integrates with existing TaskManager and WebSocket |

## Project Structure

### Documentation (this feature)

```text
specs/019-superset-ux-redesign/
├── plan.md              # This file
├── spec.md              # Feature specification
├── ux_reference.md      # UX mockups and flows
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output
│   ├── api.md           # API contracts
│   └── modules.md       # Module contracts (Semantic Protocol)
├── checklists/
│   └── requirements.md  # Spec quality checklist
└── tasks.md             # Phase 2 output
```

### Source Code (repository root)

```text
backend/
├── src/
│   ├── api/routes/
│   │   ├── dashboards.py    # NEW: Dashboard hub API
│   │   ├── datasets.py      # NEW: Dataset hub API
│   │   └── settings.py      # EXTEND: Consolidated settings
│   └── services/
│       └── resource_service.py  # NEW: Shared resource logic
└── tests/

frontend/
├── src/
│   ├── lib/
│   │   ├── components/
│   │   │   ├── layout/
│   │   │   │   ├── Sidebar.svelte          # NEW: Left sidebar
│   │   │   │   ├── TopNavbar.svelte        # NEW: Top navigation
│   │   │   │   ├── TaskDrawer.svelte       # NEW: Global task drawer
│   │   │   │   └── Breadcrumbs.svelte      # NEW: Breadcrumb nav
│   │   │   └── hubs/
│   │   │       ├── DashboardHub.svelte     # NEW: Dashboard management
│   │   │       ├── DatasetHub.svelte       # NEW: Dataset management
│   │   │       └── SettingsPage.svelte     # NEW: Consolidated settings
│   │   ├── stores/
│   │   │   ├── sidebar.js      # NEW: Sidebar state
│   │   │   ├── taskDrawer.js   # NEW: Drawer state + resource-task map
│   │   │   └── activity.js     # NEW: Activity indicator count
│   │   └── i18n/
│   │       └── en.json         # EXTEND: New navigation labels
│   └── routes/
│       ├── /dashboards/+page.svelte    # NEW
│       ├── /datasets/+page.svelte      # NEW
│       ├── /settings/+page.svelte      # NEW
│       └── /+layout.svelte             # EXTEND: Add sidebar + drawer
└── tests/
```

**Structure Decision**: Web application structure with new `layout/` and `hubs/` component directories. The Sidebar and TaskDrawer live in the root `+layout.svelte` for global availability.

## Contract References

All implementation MUST follow the Design-by-Contract specifications in [`contracts/modules.md`](./contracts/modules.md):

| Component/Module | Contract Location | TIER |
|------------------|-------------------|------|
| SidebarStore | [DEF:SidebarStore:Store](./contracts/modules.md#1-sidebarstore) | STANDARD |
| TaskDrawerStore | [DEF:TaskDrawerStore:Store](./contracts/modules.md#2-taskdrawerstore) | CRITICAL |
| ActivityStore | [DEF:ActivityStore:Store](./contracts/modules.md#3-activitystore) | STANDARD |
| Sidebar | [DEF:Sidebar:Component](./contracts/modules.md#4-sidebar-component) | CRITICAL |
| TopNavbar | [DEF:TopNavbar:Component](./contracts/modules.md#5-topnavbar-component) | CRITICAL |
| TaskDrawer | [DEF:TaskDrawer:Component](./contracts/modules.md#6-taskdrawer-component) | CRITICAL |
| DashboardHub | [DEF:DashboardHub:Component](./contracts/modules.md#7-dashboardhub-component) | CRITICAL |
| DatasetHub | [DEF:DatasetHub:Component](./contracts/modules.md#8-datasethub-component) | CRITICAL |
| DashboardsAPI | [DEF:DashboardsAPI:Module](./contracts/modules.md#10-dashboards-api) | CRITICAL |
| DatasetsAPI | [DEF:DatasetsAPI:Module](./contracts/modules.md#11-datasets-api) | CRITICAL |

### UX State Contract Mapping

All UI states defined in [`ux_reference.md`](./ux_reference.md) are mapped to `@UX_STATE` tags in module contracts. See [UX State Mapping table](./contracts/modules.md#ux-state-mapping-to-components) for complete mapping.

## Complexity Tracking

> No Constitution violations. All changes use existing patterns.

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| N/A | N/A | N/A |