ws version with nice DB select

README.md

@@ -1,6 +1,6 @@
 # Dereth Tracker
 
-Dereth Tracker is a real-time telemetry service for the world of Dereth. It collects player data, stores it in a SQLite database, and provides both a live map interface and an analytics dashboard.
+Dereth Tracker is a real-time telemetry service for the world of Dereth. It collects player data, stores it in a SQLite database, and provides a live map interface along with a sample data generator for testing.
 
 ## Table of Contents
 - [Overview](#overview)
@@ -12,7 +12,6 @@ Dereth Tracker is a real-time telemetry service for the world of Dereth. It coll
 - [API Reference](#api-reference)
 - [Frontend](#frontend)
 - [Database Schema](#database-schema)
-- [Sample Payload](#sample-payload)
 - [Contributing](#contributing)
 
 ## Overview
@@ -21,16 +20,16 @@ This project provides:
 - A FastAPI backend with endpoints for receiving and querying telemetry data.
 - SQLite-based storage for snapshots and live state.
 - A live, interactive map using static HTML, CSS, and JavaScript.
-- An analytics dashboard for visualizing kills and session metrics.
+- A sample data generator script (`generate_data.py`) for simulating telemetry snapshots.
 
 ## Features
 
-- **POST /position**: Submit a telemetry snapshot (protected by a shared secret).
+- **WebSocket /ws/position**: Stream telemetry snapshots (protected by a shared secret).
 - **GET /live**: Fetch active players seen in the last 30 seconds.
 - **GET /history**: Retrieve historical telemetry data with optional time filtering.
 - **GET /debug**: Health check endpoint.
 - **Live Map**: Interactive map interface with panning, zooming, and sorting.
- - **Analytics Dashboard**: Interactive charts for kills over time and kills per hour using D3.js.
+- **Sample Data Generator**: `generate_data.py` sends telemetry snapshots over WebSocket for testing.
 
 ## Requirements
 
@@ -45,6 +44,7 @@ Python packages:
 - pydantic
 - pandas
 - matplotlib
+- websockets  # required for sample data generator
 
 ## Installation
 
@@ -60,13 +60,14 @@ Python packages:
    ```
 3. Install dependencies:
    ```bash
-   pip install fastapi uvicorn pydantic pandas matplotlib
+   pip install fastapi uvicorn pydantic pandas matplotlib websockets
    ```
 
 ## Configuration
 
 - Update the `SHARED_SECRET` in `main.py` to match your plugin (default: `"your_shared_secret"`).
 - The SQLite database file `dereth.db` is created in the project root. To change the path, edit `DB_FILE` in `db.py`.
+- To limit the maximum database size, set the environment variable `DB_MAX_SIZE_MB` (default: 2048 MB).
 
 ## Usage
 
@@ -76,17 +77,66 @@ Start the server using Uvicorn:
 uvicorn main:app --reload --host 0.0.0.0 --port 8000
 ```
 
-- Live Map: `http://localhost:8000/`
-- Analytics Dashboard: `http://localhost:8000/graphs.html`
+## NGINX Proxy Configuration
+
+If you cannot reassign the existing `/live` and `/trails` routes, you can namespace this service under `/api` (or any other prefix) and configure NGINX accordingly. Be sure to forward WebSocket upgrade headers so that `/ws/live` and `/ws/position` continue to work. Example:
+```nginx
+location /api/ {
+  proxy_pass         http://127.0.0.1:8765/;
+   proxy_http_version 1.1;
+  proxy_set_header   Host              $host;
+  proxy_set_header   X-Real-IP         $remote_addr;
+  proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
+  proxy_set_header   X-Forwarded-Proto $scheme;
+  # WebSocket support
+  proxy_set_header   Upgrade           $http_upgrade;
+  proxy_set_header   Connection        "upgrade";
+  proxy_cache_bypass $http_upgrade;
+}
+```
+Then the browser client (static/script.js) will fetch `/api/live/` and `/api/trails/` to reach this new server.
+
+- Live Map: `http://localhost:8000/` (or `http://<your-domain>/api/` if behind a prefix)
+
+### Frontend Configuration
+
+- In `static/script.js`, the constant `API_BASE` controls where live/trails data and WebSocket `/ws/live` are fetched. By default:
+  ```js
+  const API_BASE = '/api';
+  ```
+  Update `API_BASE` if you mount the service under a different path or serve it at root.
+
+### Debugging WebSockets
+
+- Server logs now print every incoming WebSocket frame in `main.py`:
+  - `[WS-PLUGIN RX] <client>: <raw-payload>` for plugin messages on `/ws/position`
+  - `[WS-LIVE RX]   <client>: <parsed-json>` for browser messages on `/ws/live`
+- Use these logs to verify messages and troubleshoot handshake failures.
+
+### Styling Adjustments
+
+- Chat input bar is fixed at the bottom of the chat window (`.chat-form { position:absolute; bottom:0; }`).
+- Input text and placeholder are white for readability (`.chat-input, .chat-input::placeholder { color:#fff; }`).
+- Incoming chat messages forced white via `.chat-messages div { color:#fff !important; }`.
 
 ## API Reference
 
-### POST /position
-Submit a JSON telemetry snapshot. Requires header `X-Plugin-Secret: <shared_secret>`.
+### WebSocket /ws/position
+Stream telemetry snapshots over a WebSocket connection. Provide your shared secret either as a query parameter or WebSocket header:
+
+```
+ws://<host>:<port>/ws/position?secret=<shared_secret>
+```
+or
+```
+X-Plugin-Secret: <shared_secret>
+```
+
+After connecting, send JSON messages matching the `TelemetrySnapshot` schema. For example:
 
-**Request Body Example:**
 ```json
 {
+  "type": "telemetry",
   "character_name": "Dunking Rares",
   "char_tag": "moss",
   "session_id": "dunk-20250422-xyz",
@@ -104,6 +154,23 @@ Submit a JSON telemetry snapshot. Requires header `X-Plugin-Secret: <shared_secr
 }
 ```
 
+### Chat messages
+You can also send chat envelopes over the same WebSocket to display messages in the browser. Fields:
+- `type`: must be "chat"
+- `character_name`: target player name
+- `text`: message content
+- `color` (optional): CSS color string (e.g. "#ff8800"); if sent as an integer (0xRRGGBB), it will be converted to hex.
+
+Example chat payload:
+```json
+{
+  "type": "chat",
+  "character_name": "MyCharacter",
+  "text": "Hello world!",
+  "color": "#88f"
+}
+```
+
 ### GET /live
 Returns active players seen within the last 30 seconds:
 
@@ -131,17 +198,12 @@ Response:
 ## Frontend
 
 - **Live Map**: `static/index.html` – Real-time player positions on a map.
-- **Analytics Dashboard**: `static/graphs.html` – Interactive charts powered by [D3.js](https://d3js.org/).
 
 ## Database Schema
 
 - **telemetry_log**: Stored history of snapshots.
 - **live_state**: Current snapshot per character (upserted).
 
-## Sample Payload
-
-See `test.json` for an example telemetry snapshot.
-
 ## Contributing
 
 Contributions are welcome! Feel free to open issues or submit pull requests.