ss-tools/specs/001-fix-ui-ws-validation/spec.md

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).