Implementation Plan: Superset-Style UX Redesign

Branch: 019-superset-ux-redesign | Date: 2026-02-09 | Spec: 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)

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)

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:

Component/Module	Contract Location	TIER
SidebarStore	DEF:SidebarStore:Store	STANDARD
TaskDrawerStore	DEF:TaskDrawerStore:Store	CRITICAL
ActivityStore	DEF:ActivityStore:Store	STANDARD
Sidebar	DEF:Sidebar:Component	CRITICAL
TopNavbar	DEF:TopNavbar:Component	CRITICAL
TaskDrawer	DEF:TaskDrawer:Component	CRITICAL
DashboardHub	DEF:DashboardHub:Component	CRITICAL
DatasetHub	DEF:DatasetHub:Component	CRITICAL
DashboardsAPI	DEF:DashboardsAPI:Module	CRITICAL
DatasetsAPI	DEF:DatasetsAPI:Module	CRITICAL

UX State Contract Mapping

All UI states defined in ux_reference.md are mapped to @UX_STATE tags in module contracts. See UX State Mapping table 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

6.5 KiB Raw Blame History