# AGENTS.md — rusty-telemetry Project Context

## Mandatory Reference

**Before starting any work on this project, always read the Joplin note that contains the full project plan and architecture.**

- **Joplin Note ID**: `6c0dcb2a567348fd9796f50c790082e4`
- **Title**: "Sim Racing Telemetry Analysis Platform — Project Plan"
- **Tags**: sim-racing, lua, telemetry, rust, project-plan, assetto-corsa

Use the `joplin_get_note` tool with note ID `6c0dcb2a567348fd9796f50c790082e4` to retrieve the full project plan.

## Project Overview

`rusty-telemetry` is a Rust-based multi-port UDP telemetry listener and analysis platform for sim racing. It receives telemetry from Assetto Corsa (KSUDP + Telemetry Tool) and Project CARS 1 & 2, provides a terminal dashboard (ratatui), and exposes a REST API for session management, analysis, and car characteristics aggregation.

## Companion Repository

| Field | Value |
|-------|-------|
| **Repo** | `racecraft` |
| **Path** | `~/WebstormProjects/racecraft` |
| **Language** | TypeScript (Vue 3) |
| **Purpose** | Web client — live telemetry, session UI, charts, track maps |

## Tech Stack

- Rust (edition 2021)
- Tokio (async runtime)
- Axum 0.8 (REST API)
- Ratatui (terminal UI)
- Serde (JSON serialization)

## Key Ports

| Port  | Feed Name         | Source                        | Format  |
|-------|-------------------|-------------------------------|---------|
| 9996  | ksudp             | AC built-in engine             | Binary (3-phase handshake, RTCarInfo) |
| 10101 | telemetry_tool    | Telemetry Tool Python plugin   | Binary (per-driver structs, ~60 Hz) |
| 5606  | pcars             | Project CARS 1 & 2             | Binary (V1 1367B / V2 559B, auto-detected) |
| 8080  | REST API          | Axum HTTP server               | JSON |

## Data Persistence

- **Recordings**: `./data/<uuid>/` — manifest.json + per-feed JSONL files (written on shutdown)
- **Sessions**: `./data/sessions/<id>.json` (metadata + analysis) + `<id>.frames.json` (frames, lazy-loaded)
- **Track Models**: stored in session analysis results, served via `/api/tracks`

## Commands

```bash
cargo run --release    # Start server + TUI
cargo test             # Run 33 unit tests
```