worked backup

specs/005-fix-ui-ws-validation/research.md

@@ -0,0 +1,41 @@
+# Research: Fix UI Styling, WebSocket Port Mismatch, and URL Validation
+
+## WebSocket Port Mismatch Resolution
+
+### Decision
+Use SvelteKit's `$env/static/public` for `PUBLIC_WS_URL` with a client-side fallback logic.
+
+### Rationale
+SvelteKit allows exposing environment variables to the frontend. By using a public environment variable, we can explicitly set the WebSocket URL in different environments (dev vs. prod).
+
+### Alternatives Considered
+- **Hardcoding**: Rejected as it breaks across different environments.
+- **Relative URLs**: WebSockets (`ws://` or `wss://`) cannot be purely relative in all browser contexts without logic to determine the host and port.
+
+---
+
+## URL Validation Relaxation
+
+### Decision
+Modify the Pydantic model to use a `validator` (or `field_validator` in Pydantic v2) that checks for the `/api/v1` suffix and appends it if missing, while still ensuring the base URL is valid.
+
+### Rationale
+This provides a seamless user experience where they can provide just the base URL, and the system handles the API versioning internally.
+
+### Alternatives Considered
+- **Strict Validation with Error Message**: Rejected as it causes user frustration (as noted in the spec).
+- **Manual Suffixing in Service Clients**: Rejected as it's better to have a normalized URL in the data model.
+
+---
+
+## Global Styling (Tailwind CSS)
+
+### Decision
+Import the global CSS file (which includes `@tailwind` directives) in `src/routes/+layout.svelte`.
+
+### Rationale
+This is the standard SvelteKit pattern for ensuring styles are applied globally across all routes.
+
+### Alternatives Considered
+- **Importing in each page**: Rejected as it's redundant and hard to maintain.
+- **Importing in `app.html`**: Possible, but importing in `+layout.svelte` allows for better integration with Svelte's build pipeline.