# 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**: Interactive charts for kills over time and kills per hour using D3.js.

## 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 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.