feat: integrate SvelteKit for seamless navigation and improved data loading

2025-12-20 22:41:23 +03:00
parent 58831c536a
commit 9b7b743319
106 changed files with 16217 additions and 123 deletions
--- a/specs/004-integrate-svelte-kit/checklists/requirements.md
+++ b/specs/004-integrate-svelte-kit/checklists/requirements.md
@@ -0,0 +1,34 @@
+# Specification Quality Checklist: Integrate SvelteKit
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2025-12-20
+**Feature**: [Link to spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Spec updated to assume SPA mode and standard fetch, removing clarification needs.
--- a/specs/004-integrate-svelte-kit/contracts/api.md
+++ b/specs/004-integrate-svelte-kit/contracts/api.md
@@ -0,0 +1,61 @@
+# API Contracts: SvelteKit Frontend
+
+The SvelteKit frontend will interact with the following existing backend API endpoints.
+
+## Settings API (`/api/settings`)
+
+### Get All Settings
+- **Endpoint**: `GET /api/settings/`
+- **Response**: `AppConfig` (JSON)
+- **Usage**: Load initial configuration for the application.
+
+### Update Global Settings
+- **Endpoint**: `PATCH /api/settings/global`
+- **Request Body**: `GlobalSettings` (JSON)
+- **Response**: `GlobalSettings` (JSON)
+- **Usage**: Save changes to global settings.
+
+### List Environments
+- **Endpoint**: `GET /api/settings/environments`
+- **Response**: `List[Environment]` (JSON)
+- **Usage**: Display configured Superset environments.
+
+### Add Environment
+- **Endpoint**: `POST /api/settings/environments`
+- **Request Body**: `Environment` (JSON)
+- **Response**: `Environment` (JSON)
+- **Usage**: Create a new environment configuration.
+
+### Update Environment
+- **Endpoint**: `PUT /api/settings/environments/{id}`
+- **Request Body**: `Environment` (JSON)
+- **Response**: `Environment` (JSON)
+- **Usage**: Modify an existing environment.
+
+### Delete Environment
+- **Endpoint**: `DELETE /api/settings/environments/{id}`
+- **Response**: `{"message": "..."}`
+- **Usage**: Remove an environment.
+
+### Test Connection
+- **Endpoint**: `POST /api/settings/environments/{id}/test`
+- **Response**: `{"status": "success/error", "message": "..."}`
+- **Usage**: Verify connectivity to a Superset instance.
+
+## Plugins API (`/api/plugins`)
+
+### List Plugins
+- **Endpoint**: `GET /api/plugins/`
+- **Response**: `List[PluginConfig]` (JSON)
+- **Usage**: Display available plugins on the Dashboard.
+
+## Tasks API (`/api/tasks`)
+*(Inferred from file list, used for running plugin tasks)*
+
+### List Tasks
+- **Endpoint**: `GET /api/tasks/`
+- **Usage**: Show active or historical tasks.
+
+### Run Task
+- **Endpoint**: `POST /api/tasks/{plugin_id}`
+- **Usage**: Execute a plugin-specific task.
--- a/specs/004-integrate-svelte-kit/data-model.md
+++ b/specs/004-integrate-svelte-kit/data-model.md
@@ -0,0 +1,40 @@
+# Data Model: SvelteKit Integration
+
+## Entities
+
+### Route
+Represents a navigable URL in the application.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `path` | String | The URL path (e.g., `/`, `/settings`) |
+| `component` | Svelte Component | The page component to render |
+| `data_requirements` | List<API Endpoint> | Backend data needed for this route |
+| `layout` | Layout | The layout wrapping this route |
+
+**Validation Rules**:
+- `path` must be unique.
+- `path` must follow SvelteKit file-based routing conventions.
+
+### Layout
+Represents a shared UI structure.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | String | Identifier for the layout (e.g., `default`) |
+| `components` | List<Svelte Component> | Shared components (Header, Footer, Sidebar) |
+| `slot` | Placeholder | Where the route content is injected |
+
+## State Transitions
+
+### Navigation
+1.  **Trigger**: User clicks link or `goto(path)` is called.
+2.  **Action**: SvelteKit router intercepts the request.
+3.  **Data Fetching**: `load` function in `+page.ts` or `+layout.ts` is executed.
+4.  **Rendering**: The new page component is rendered within the layout.
+5.  **URL Update**: Browser history is updated.
+
+### Error Handling
+1.  **Trigger**: Navigation to non-existent path or API failure.
+2.  **Action**: SvelteKit renders `+error.svelte`.
+3.  **Display**: User-friendly error message with recovery options.
--- a/specs/004-integrate-svelte-kit/plan.md
+++ b/specs/004-integrate-svelte-kit/plan.md
@@ -0,0 +1,70 @@
+# Implementation Plan: Integrate SvelteKit
+
+**Branch**: `004-integrate-svelte-kit` | **Date**: 2025-12-20 | **Spec**: [specs/004-integrate-svelte-kit/spec.md](specs/004-integrate-svelte-kit/spec.md)
+**Input**: Feature specification from `/specs/004-integrate-svelte-kit/spec.md`
+
+## Summary
+
+Integrate SvelteKit as the primary frontend framework to provide seamless navigation, improved data loading, and a unified layout. The application will be configured as a Static Single Page Application (SPA) to be served by the existing Python backend, preserving all existing functionality while leveraging modern framework features like file-based routing and shared layouts.
+
+## Technical Context
+
+**Language/Version**: Python 3.9+, Node.js 18+  
+**Primary Dependencies**: SvelteKit, FastAPI, Tailwind CSS (inferred from existing frontend)  
+**Storage**: N/A (Frontend integration)  
+**Testing**: pytest (Backend), Vitest/Playwright (Frontend - SvelteKit defaults)  
+**Target Platform**: Linux server (SPA served by backend)
+**Project Type**: Web application (frontend + backend)  
+**Performance Goals**: Page transition time < 200ms (SC-001)  
+**Constraints**: Must be deployable as a Static SPA (FR-003), no Node.js server in production (Assumptions)  
+**Scale/Scope**: Migration of existing Dashboard and Settings pages
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- **Principle Compliance**: The project constitution is currently in a template state. No specific violations identified.
+- **Architecture Alignment**: The move to SvelteKit aligns with the goal of using modern frontend patterns while maintaining the "SPA served by backend" constraint.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/004-integrate-svelte-kit/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Phase 1 output (/speckit.plan command)
+├── quickstart.md        # Phase 1 output (/speckit.plan command)
+├── contracts/           # Phase 1 output (/speckit.plan command)
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+
+```text
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── lib/
+│   ├── routes/          # SvelteKit file-based routing
+│   └── app.html
+├── static/
+└── tests/
+```
+
+**Structure Decision**: Option 2: Web application. The project already has `backend/` and `frontend/` directories. SvelteKit will be integrated into the `frontend/` directory, replacing the current Svelte setup.
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| None | N/A | N/A |
--- a/specs/004-integrate-svelte-kit/quickstart.md
+++ b/specs/004-integrate-svelte-kit/quickstart.md
@@ -0,0 +1,51 @@
+# Quickstart: SvelteKit Integration
+
+This guide provides instructions for setting up and running the SvelteKit frontend integrated with the FastAPI backend.
+
+## Prerequisites
+- Node.js 18+
+- Python 3.9+
+- `npm`
+
+## Frontend Setup
+
+1.  **Initialize SvelteKit**:
+    ```bash
+    cd frontend
+    # (Assuming migration to SvelteKit structure)
+    npm install
+    ```
+
+2.  **Development Mode**:
+    Run the SvelteKit development server:
+    ```bash
+    npm run dev
+    ```
+    The frontend will be available at `http://localhost:5173`.
+
+3.  **Build for Production**:
+    Generate the static SPA files:
+    ```bash
+    npm run build
+    ```
+    The output will be in the `frontend/build` directory.
+
+## Backend Setup
+
+1.  **Install Dependencies**:
+    ```bash
+    cd backend
+    pip install -r requirements.txt
+    ```
+
+2.  **Run Backend**:
+    ```bash
+    python src/app.py
+    ```
+    The backend will serve the static frontend files from `frontend/build`.
+
+## Verification Steps
+
+1.  **Navigation**: Open `http://localhost:8000` (backend URL). Click on "Settings" and verify the URL changes to `/settings` without a page reload.
+2.  **Deep Linking**: Refresh the page at `http://localhost:8000/settings`. Verify the Settings page loads correctly.
+3.  **Data Loading**: Verify that the Dashboard correctly lists available plugins and Settings shows the current configuration.
--- a/specs/004-integrate-svelte-kit/research.md
+++ b/specs/004-integrate-svelte-kit/research.md
@@ -0,0 +1,45 @@
+# Research: SvelteKit Integration
+
+## Decision: SvelteKit SPA with FastAPI Backend
+
+### Rationale
+SvelteKit provides a robust file-based routing system and shared layout mechanism that fulfills the requirements (FR-001, FR-002, FR-004, FR-005). By using `adapter-static` in SPA mode, we can generate a set of static files that can be served by the existing FastAPI backend, satisfying the constraint of no Node.js server in production (FR-003, Assumptions).
+
+### Alternatives Considered
+- **Vanilla Svelte (Current)**: Lacks built-in routing and layout management, leading to manual implementation overhead.
+- **SvelteKit with Node.js Server**: Rejected because the project requires the Python backend to be the primary server.
+- **Inertia.js**: Requires more tight coupling between backend and frontend than desired for this project.
+
+## Technical Implementation Details
+
+### SvelteKit Configuration (SPA Mode)
+1.  **Adapter**: Use `@sveltejs/adapter-static`.
+2.  **Fallback**: Configure `fallback: 'index.html'` in `svelte.config.js`.
+3.  **Client-Side Rendering**: Create `src/routes/+layout.ts` with:
+    ```typescript
+    export const ssr = false;
+    export const prerender = false;
+    ```
+    This ensures the entire app is treated as a SPA.
+
+### FastAPI Backend Integration
+1.  **Static Files**: Mount the `frontend/build` (or `dist`) directory using `StaticFiles`.
+2.  **SPA Routing**: Implement a catch-all route to serve `index.html` for any non-API request. This allows SvelteKit's client-side router to handle deep links like `/settings`.
+    ```python
+    @app.get("/{full_path:path}")
+    async def serve_spa(full_path: str):
+        # Check if path exists in static files, else serve index.html
+        ...
+    ```
+
+### Migration Strategy
+1.  **Layout**: Move shared UI (header, footer) from `App.svelte` to `src/routes/+layout.svelte`.
+2.  **Routes**: 
+    - `Dashboard.svelte` -> `src/routes/+page.svelte` (or `src/routes/dashboard/+page.svelte`)
+    - `Settings.svelte` -> `src/routes/settings/+page.svelte`
+3.  **API Client**: Reuse existing `frontend/src/lib/api.js` but ensure it works within SvelteKit's load functions if needed (though for pure SPA, standard `onMount` or reactive statements also work).
+
+## Best Practices
+- Use SvelteKit's `$lib` alias for shared components and utilities.
+- Leverage `+page.ts` `load` functions for data fetching to ensure data is ready before component mount (User Story 2).
+- Use SvelteKit's `goto` for programmatic navigation.
--- a/specs/004-integrate-svelte-kit/spec.md
+++ b/specs/004-integrate-svelte-kit/spec.md
@@ -0,0 +1,87 @@
+# Feature Specification: Integrate SvelteKit
+
+**Feature Branch**: `004-integrate-svelte-kit`  
+**Created**: 2025-12-20  
+**Status**: Draft  
+**Input**: User description: "Integrate SvelteKit into the project"
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Seamless Navigation (Priority: P1)
+
+As a user, I want to navigate between different parts of the application (Dashboard, Settings) using standard URL paths so that I can bookmark pages and use the browser's back/forward buttons reliably.
+
+**Why this priority**: Core application usability and standard web behavior.
+
+**Independent Test**: Can be tested by clicking navigation links and verifying the URL changes and the correct content renders without a full page reload.
+
+**Acceptance Scenarios**:
+
+1. **Given** I am on the Dashboard, **When** I click the "Settings" link, **Then** the URL changes to `/settings` and the Settings page is displayed.
+2. **Given** I am on `/settings`, **When** I refresh the page, **Then** the Settings page is still displayed (not redirected to home).
+
+---
+
+### User Story 2 - Improved Data Loading (Priority: P2)
+
+As a developer, I want to use modern data loading patterns so that data is fetched efficiently before the page renders, reducing layout shifts and loading spinners.
+
+**Why this priority**: Improves user experience and developer productivity.
+
+**Independent Test**: Can be tested by observing the page load sequence and verifying that data is available to the component immediately upon mount.
+
+**Acceptance Scenarios**:
+
+1. **Given** a page requires data from the backend, **When** the page is navigated to, **Then** the data is fetched and ready before the content is fully visible.
+
+---
+
+### User Story 3 - Unified Layout (Priority: P3)
+
+As a user, I want a consistent look and feel across all pages with a shared navigation bar and footer.
+
+**Why this priority**: Visual consistency and ease of use.
+
+**Independent Test**: Can be tested by navigating between pages and verifying that the header/footer remain static and do not re-render or flicker.
+
+**Acceptance Scenarios**:
+
+1. **Given** I am navigating between Dashboard and Settings, **When** the page changes, **Then** the top navigation bar remains visible and unchanged.
+
+---
+
+### Edge Cases
+
+- **Invalid Routes**: When a user navigates to a non-existent URL, the system should display a user-friendly 404 error page with a link back to the dashboard.
+- **API Failures during Load**: If the backend API is unavailable during a data load operation, the system should display a graceful error message or redirect to a dedicated error page.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST use SvelteKit as the primary frontend framework.
+- **FR-002**: System MUST implement file-based routing for all existing pages (Dashboard, Settings).
+- **FR-003**: System MUST be deployable as a Static Single Page Application (SPA) to be served by the existing backend.
+- **FR-004**: System MUST provide a shared layout mechanism for common UI elements (header, footer).
+- **FR-005**: System MUST handle client-side navigation between routes without full page refreshes.
+- **FR-006**: System MUST integrate with the existing backend API for data retrieval.
+- **FR-007**: System MUST support data submission via existing API endpoints using standard asynchronous requests.
+
+### Key Entities *(include if feature involves data)*
+
+- **Route**: Represents a URL path and its associated page content and data requirements.
+- **Layout**: Represents a shared UI structure that wraps multiple routes.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: Page transition time between Dashboard and Settings is under 200ms.
+- **SC-002**: 100% of existing frontend functionality is preserved after migration.
+- **SC-003**: Application is accessible via direct URLs (e.g., `/settings`) without manual configuration of the web server for SPA routing.
+- **SC-004**: Developer setup time for the frontend is reduced by using standard framework tooling.
+
+## Assumptions
+
+- The application will be deployed as a static site served by the Python backend (no Node.js server in production).
+- Existing API endpoints are sufficient for the frontend needs.
--- a/specs/004-integrate-svelte-kit/tasks.md
+++ b/specs/004-integrate-svelte-kit/tasks.md
@@ -0,0 +1,166 @@
+# Tasks: Integrate SvelteKit
+
+**Input**: Design documents from `/specs/004-integrate-svelte-kit/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: Tests are NOT explicitly requested in the feature specification, so no test-specific tasks are included. Verification will be done via the "Independent Test" criteria for each story.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Web app**: `backend/src/`, `frontend/src/`
+
+---
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Initialize SvelteKit in `frontend/` directory (replacing current setup)
+- [ ] T002 Install `@sveltejs/adapter-static` in `frontend/package.json`
+- [ ] T003 [P] Configure `frontend/svelte.config.js` for static adapter and SPA fallback
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+- [ ] T004 Create `frontend/src/routes/+layout.ts` to disable SSR and prerendering (`ssr = false`, `prerender = false`)
+- [ ] T005 Implement catch-all route in `backend/src/app.py` to serve `index.html` for SPA routing
+- [ ] T006 [P] Update `backend/src/app.py` to mount `frontend/build` directory using `StaticFiles`
+- [ ] T007 [P] Update `frontend/src/lib/api.js` to ensure compatibility with SvelteKit environment
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - Seamless Navigation (Priority: P1) 🎯 MVP
+
+**Goal**: Navigate between Dashboard and Settings using standard URL paths so that users can bookmark pages and use browser navigation.
+
+**Independent Test**: Click navigation links and verify the URL changes and the correct content renders without a full page reload. Verify deep linking by refreshing at `/settings`.
+
+### Implementation for User Story 1
+
+- [ ] T008 [P] [US1] Create Dashboard route in `frontend/src/routes/+page.svelte` (migrating from `App.svelte`/`Dashboard.svelte`)
+- [ ] T009 [P] [US1] Create Settings route in `frontend/src/routes/settings/+page.svelte` (migrating from `Settings.svelte`)
+- [ ] T010 [US1] Implement navigation links between Dashboard and Settings in `frontend/src/routes/+page.svelte` and `frontend/src/routes/settings/+page.svelte`
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently.
+
+---
+
+## Phase 4: User Story 2 - Improved Data Loading (Priority: P2)
+
+**Goal**: Use modern data loading patterns so that data is fetched efficiently before the page renders.
+
+**Independent Test**: Observe the page load sequence and verify that data is available to the component immediately upon mount via the `data` prop.
+
+### Implementation for User Story 2
+
+- [ ] T011 [P] [US2] Implement `load` function for Dashboard in `frontend/src/routes/+page.ts` to fetch plugins from `/api/plugins/`
+- [ ] T012 [P] [US2] Implement `load` function for Settings in `frontend/src/routes/settings/+page.ts` to fetch config and environments from `/api/settings/`
+- [ ] T013 [US2] Update `frontend/src/routes/+page.svelte` to use data from `load` function via `export let data;`
+- [ ] T014 [US2] Update `frontend/src/routes/settings/+page.svelte` to use data from `load` function via `export let data;`
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently.
+
+---
+
+## Phase 5: User Story 3 - Unified Layout (Priority: P3)
+
+**Goal**: Consistent look and feel across all pages with a shared navigation bar and footer.
+
+**Independent Test**: Navigate between Dashboard and Settings and verify that the header/footer remain static and do not re-render or flicker.
+
+### Implementation for User Story 3
+
+- [ ] T015 [US3] Create shared layout in `frontend/src/routes/+layout.svelte` with `<slot />`
+- [ ] T016 [P] [US3] Move navigation bar component to `frontend/src/components/Navbar.svelte` and include in `+layout.svelte`
+- [ ] T017 [P] [US3] Create footer component in `frontend/src/components/Footer.svelte` and include in `+layout.svelte`
+
+**Checkpoint**: All user stories should now be independently functional.
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] T018 [P] Implement custom 404 error page in `frontend/src/routes/+error.svelte`
+- [ ] T019 Add graceful error handling for API failures in `load` functions (T011, T012)
+- [ ] T020 [P] Update `frontend/README.md` with new SvelteKit-based development and build instructions
+- [ ] T021 Run `specs/004-integrate-svelte-kit/quickstart.md` validation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - Depends on US1 routes existing
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - Can be implemented independently of US1/US2 content
+
+### Within Each User Story
+
+- Models/Data fetching before UI implementation
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- T003 (Svelte config) can run in parallel with other setup
+- T006 (Backend mount) and T007 (API client) can run in parallel
+- T008 (Dashboard route) and T009 (Settings route) can run in parallel
+- T011 and T012 (Load functions) can run in parallel
+- T016 and T017 (Navbar/Footer components) can run in parallel
+
+---
+
+## Parallel Example: User Story 2
+
+```bash
+# Launch all load function implementations for User Story 2 together:
+Task: "Implement load function for Dashboard in frontend/src/routes/+page.ts"
+Task: "Implement load function for Settings in frontend/src/routes/settings/+page.ts"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently (Navigation and Deep Linking)
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories