MosswartOverlord/LESSONSLEARNED.md

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:

  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:

  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.