# Feature Specification: Fix UI Styling, WebSocket Port Mismatch, and URL Validation **Feature Branch**: `001-fix-ui-ws-validation` **Created**: 2025-12-20 **Status**: Draft **Input**: User description: "UI Styling: Tailwind CSS is not imported in the root layout, causing the unstyled appearance. WebSocket Mismatch: Port mismatch in dev mode is breaking real-time logs. Validation Error: Strict URL validation in superset_tool/models.py requires /api/v1, which caused the connection failure reported in your feedback." ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Consistent UI Styling (Priority: P1) As a user, I want the application to have a professional and styled appearance so that I can easily navigate and use the interface. **Why this priority**: Unstyled UI makes the application look broken and difficult to use, impacting user trust and usability. **Independent Test**: Can be fully tested by opening the application in a browser and verifying that consistent styling is applied globally across all routes. **Acceptance Scenarios**: 1. **Given** the application is running, **When** I navigate to the home page or settings page, **Then** I should see professional styling applied (e.g., correct fonts, colors, and layout). 2. **Given** a new component is added, **When** it uses standard styling classes, **Then** those classes should be rendered correctly without additional imports. --- ### User Story 2 - Real-time Log Monitoring (Priority: P1) As a developer or operator, I want to see real-time logs for running tasks so that I can monitor progress and debug issues effectively. **Why this priority**: Real-time feedback is essential for long-running tasks like migrations or backups; without it, users are left wondering if the process is stuck. **Independent Test**: Can be tested by starting a task and verifying that logs appear in the UI in real-time without requiring a page refresh. **Acceptance Scenarios**: 1. **Given** a task is running, **When** I view the task details page, **Then** I should see live log updates streamed via real-time communication. 2. **Given** the application is running in development mode, **When** a real-time connection is initiated, **Then** it should correctly target the backend service port. --- ### User Story 3 - Flexible External Service Connection (Priority: P2) As an administrator, I want to connect to external services using their base URL so that I don't have to worry about specific API version paths during configuration. **Why this priority**: Strict validation currently prevents successful connection to valid service instances if the user doesn't provide a very specific suffix, leading to configuration frustration. **Independent Test**: Can be tested by configuring a service connection with a standard base URL and verifying it connects successfully. **Acceptance Scenarios**: 1. **Given** a valid service base URL, **When** I save the connection settings, **Then** the system should validate and accept the URL even if it doesn't explicitly end in a specific API version suffix. 2. **Given** a service URL that already includes an API version suffix, **When** I save the settings, **Then** the system should not duplicate the suffix or fail validation. --- ### Edge Cases - **Connection Disconnection**: How does the system handle a real-time connection drop during a long-running task? (Assumption: It should attempt to reconnect or show a "Connection Lost" message). - **Invalid URL Formats**: How does the system handle URLs that are completely malformed? (Assumption: Standard URL validation should still apply). - **Styling Build Failures**: What happens if the styling assets fail to generate? (Assumption: The app should still be functional but may look unstyled; build logs should indicate the failure). ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: System MUST ensure global styling (Tailwind CSS) is imported in `src/routes/+layout.svelte` to ensure consistent appearance. - **FR-002**: System MUST use an environment variable (e.g., `PUBLIC_WS_URL`) with a fallback to the backend port (8000) to determine the WebSocket connection URL. - **FR-003**: System MUST relax URL validation for external services to allow base URLs and automatically append `/api/v1` if the version suffix is missing. - **FR-004**: System MUST provide visual feedback (toast notification and status indicator in log view) when a real-time connection fails to establish. - **FR-005**: System MUST ensure that service clients correctly handle API versioning internally by using the normalized URL. ### Key Entities *(include if feature involves data)* - **Service Connection**: Represents the configuration for connecting to an external service. - Attributes: Base URL, Credentials (if applicable), Connection Status. - **Task Log Stream**: Represents the real-time data flow of logs from the backend to the frontend. - Attributes: Task ID, Log Message, Timestamp. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: 100% of pages render with consistent, professional styling as verified by visual inspection. - **SC-002**: Real-time communication success rate is 100% in the development environment when both frontend and backend are running. - **SC-003**: Users can successfully configure and save external service connections using only the base domain/IP in 100% of valid cases. - **SC-004**: Real-time updates appear in the UI within 500ms of being generated on the backend. ## Clarifications ### Session 2025-12-20 - Q: WebSocket Reconnection Strategy → A: Automatic reconnection with exponential backoff (Option A). - Q: URL Validation Strictness → A: Automatically append `/api/v1` if missing (Option A). - Q: Global Styling Implementation → A: Import in `src/routes/+layout.svelte` (Option A). - Q: WebSocket Port Configuration → A: Use environment variable with fallback (Option A). - Q: Visual Feedback for Connection Failure → A: Toast notification + Status indicator (Option A).