# AGENTS.md — Racecraft 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

`racecraft` is a Vue.js 3 + TypeScript web client for the [rusty-telemetry](https://codeberg.org/jhunnius/rusty-telemetry) sim racing telemetry platform. It provides live telemetry visualization, session management, and data analysis through a browser-based interface.

## Companion Repository

| Field | Value |
|-------|-------|
| **Repo** | `rusty-telemetry` |
| **Path** | `~/RustroverProjects/rusty-telemetry` |
| **Language** | Rust |
| **Purpose** | UDP listener, REST API backend, analysis engine |

## Tech Stack

- Vue 3.5 (Composition API, `<script setup>`)
- TypeScript 5.7
- Vite 6 (dev server with API proxy)
- Pinia 3 (state management)
- Vue Router 4 (client-side routing)
- Axios (HTTP client)
- Chart.js 4 + vue-chartjs 5 (data visualization)
- HTML Canvas 2D (track map rendering)

## Key Ports

| Port | Component | Purpose |
|------|-----------|---------|
| 8080 | rusty-telemetry API | REST API backend |
| 5173 | racecraft (Vite dev) | Frontend dev server |
| 9996 | rusty-telemetry UDP | AC KSUDP handshake |
| 10101 | rusty-telemetry UDP | AC Telemetry Tool |
| 5606 | rusty-telemetry UDP | PCARS telemetry |

## API Communication

Racecraft communicates exclusively with the rusty-telemetry REST API. In development, Vite proxies `/api/*` to `http://127.0.0.1:8080`. See the rusty-telemetry README for full endpoint documentation.

## Commands

```bash
npm run dev      # Start dev server (0.0.0.0:5173)
npm run build    # TypeScript check + Vite production build
npm run preview  # Preview production build
```