# Lessons Learned

_This document captures the key takeaways and implementation details from today's troubleshooting session._

## 1. API Routing & Proxy Configuration
- **API_BASE constant**: The frontend (`static/script.js`) uses a base path `API_BASE` (default `/api`) to prefix all HTTP and WebSocket calls. Always update this to match your proxy mount point.
- **Nginx WebSocket forwarding**: To proxy WebSockets, you must forward the `Upgrade` and `Connection` headers:
  ```nginx
  proxy_set_header Upgrade    $http_upgrade;
  proxy_set_header Connection "upgrade";
  ```
  Without these, the WS handshake downgrades to a normal HTTP GET, resulting in 404s.

## 2. Debugging WebSocket Traffic
- Logged all incoming WS frames in `main.py`:
  - `[WS-PLUGIN RX] <client>: <raw>` for messages on `/ws/position`
  - `[WS-LIVE RX]   <client>: <parsed-json>` for messages on `/ws/live`
- These prints surface registration, telemetry, chat, and command packets, aiding root-cause analysis.

## 3. Data Serialization Fix
- Python `datetime` objects are not JSON-serializable by default. We wrapped outbound payloads via FastAPI’s `jsonable_encoder` in `_broadcast_to_browser_clients` so that:
  ```python
  data = jsonable_encoder(snapshot)
  await ws.send_json(data)
  ```
  This ensures ISO8601 strings for timestamps and eliminates `TypeError: Object of type datetime is not JSON serializable`.

## 4. Frontend Adjustments
- **Chat input positioning**: Moved the `.chat-form` to `position: absolute; bottom: 0;` so the input always sticks to the bottom of its window.
- **Text color**: Forced the input text and placeholder to white (`.chat-input, .chat-input::placeholder { color: #fff; }`) and forcibly set all incoming messages to white via `.chat-messages div { color: #fff !important; }`.
- **Padding for messages**: Added `padding-bottom` to `.chat-messages` to avoid new messages being hidden behind the fixed input bar.

## 5. General Best Practices
- Clear browser cache after updating static assets to avoid stale JS/CSS.
- Keep patches targeted: fix the source of issues (e.g., JSON encoding or missing headers) rather than applying superficial workarounds.
- Use consistent CSS variables for theming (e.g., `--text`, `--bg-main`).

By consolidating these lessons, we can onboard faster next time and avoid repeating these pitfalls.