New read me

2025-04-30 19:43:39 +00:00 · 2025-04-30 19:43:39 +00:00 · d63cb4ee06
commit d63cb4ee06
parent 39d618e0b8
1 changed files with 147 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,147 @@
+# 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.
+
+## Table of Contents
+- [Overview](#overview)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [API Reference](#api-reference)
+- [Frontend](#frontend)
+- [Database Schema](#database-schema)
+- [Sample Payload](#sample-payload)
+- [Contributing](#contributing)
+
+## Overview
+
+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.
+
+## Features
+
+- **POST /position**: Submit a telemetry snapshot (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**: Charts for kills over time and kills per hour.
+
+## Requirements
+
+- Python 3.9 or newer
+- pip
+- (Optional) virtual environment tool (venv)
+
+Python packages:
+
+- fastapi
+- uvicorn
+- pydantic
+- pandas
+- matplotlib
+
+## Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/yourusername/dereth-tracker.git
+   cd dereth-tracker
+   ```
+2. Create and activate a virtual environment:
+   ```bash
+   python3 -m venv venv
+   source venv/bin/activate  # Windows: venv\Scripts\activate
+   ```
+3. Install dependencies:
+   ```bash
+   pip install fastapi uvicorn pydantic pandas matplotlib
+   ```
+
+## 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`.
+
+## Usage
+
+Start the server using Uvicorn:
+
+```bash
+uvicorn main:app --reload --host 0.0.0.0 --port 8000
+```
+
+- Live Map: `http://localhost:8000/`
+- Analytics Dashboard: `http://localhost:8000/graphs.html`
+
+## API Reference
+
+### POST /position
+Submit a JSON telemetry snapshot. Requires header `X-Plugin-Secret: <shared_secret>`.
+
+**Request Body Example:**
+```json
+{
+  "character_name": "Dunking Rares",
+  "char_tag": "moss",
+  "session_id": "dunk-20250422-xyz",
+  "timestamp": "2025-04-22T13:45:00Z",
+  "ew": 123.4,
+  "ns": 567.8,
+  "z": 10.2,
+  "kills": 42,
+  "deaths": 1,
+  "rares_found": 2,
+  "prismatic_taper_count": 17,
+  "vt_state": "Combat",
+  "kills_per_hour": "N/A",
+  "onlinetime": "00:05:00"
+}
+```
+
+### GET /live
+Returns active players seen within the last 30 seconds:
+
+```json
+{
+  "players": [ { ... } ]
+}
+```
+
+### GET /history
+Retrieve historical snapshots with optional `from` and `to` ISO8601 timestamps:
+
+```
+GET /history?from=2025-04-22T12:00:00Z&to=2025-04-22T13:00:00Z
+```
+
+Response:
+
+```json
+{
+  "data": [ { ... } ]
+}
+```
+
+## Frontend
+
+- **Live Map**: `static/index.html` – Real-time player positions on a map.
+- **Analytics**: `static/graphs.html` – Charts powered by [Chart.js](https://www.chartjs.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.