Refactor to async TimescaleDB backend & add Alembic migrations

README.md

@@ -42,8 +42,6 @@ Python packages:
 - fastapi
 - uvicorn
 - pydantic
-- pandas
-- matplotlib
 - websockets  # required for sample data generator
 
 ## Installation
@@ -60,7 +58,7 @@ Python packages:
    ```
 3. Install dependencies:
    ```bash
-   pip install fastapi uvicorn pydantic pandas matplotlib websockets
+  pip install fastapi uvicorn pydantic websockets
    ```
 
 ## Configuration
@@ -171,6 +169,16 @@ Example chat payload:
 }
 ```
 
+## Event Payload Formats
+
+For a complete reference of JSON payloads accepted by the backend (over `/ws/position`), see the file `EVENT_FORMATS.json` in the project root. It contains example schemas for:
+  - **Telemetry events** (`type`: "telemetry")
+  - **Spawn events** (`type`: "spawn")
+  - **Chat events** (`type`: "chat")
+  - **Rare events** (`type`: "rare")
+
+Each entry shows all required and optional fields, their types, and example values.
+
 ### GET /live
 Returns active players seen within the last 30 seconds:
 
@@ -207,3 +215,26 @@ Response:
 ## Contributing
 
 Contributions are welcome! Feel free to open issues or submit pull requests.
+
+## Roadmap & TODO
+For detailed tasks, migration steps, and future enhancements, see [TODO.md](TODO.md).
+
+### Local Development Database
+This project will migrate from SQLite to PostgreSQL/TimescaleDB. You can configure local development using Docker Compose or connect to an external instance:
+
+1. PostgreSQL/TimescaleDB via Docker Compose (recommended):
+   - Pros:
+     - Reproducible, isolated environment out-of-the-box
+     - No need to install Postgres locally
+     - Aligns development with production setups
+   - Cons:
+     - Additional resource usage (memory, CPU)
+     - Slightly more complex Docker configuration
+
+2. External PostgreSQL instance:
+   - Pros:
+     - Leverages existing infrastructure
+     - No Docker overhead
+   - Cons:
+     - Requires manual setup and Timescale extension
+     - Less portable for new contributors