130 lines
6.5 KiB
Markdown
130 lines
6.5 KiB
Markdown
# 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 |
|