racecraft — Vue.js Web Client Notes

# racecraft — Vue.js Web Client Notes

> **Parent note:** [Sim Racing Telemetry Analysis Platform — Project Plan](joplin://6c0dcb2a567348fd9796f50c790082e4)
> **Repo:** `~/WebstormProjects/racecraft`
> **Companion:** [rusty-telemetry — REST API Reference](joplin://0c837f4e6b7e462a997cbc19e47c864a)
> **Current version:** v0.1.6

---

## Tech Stack

| Component | Technology |
|-----------|-----------|
| Framework | Vue 3.5 (Composition API, `<script setup>`) |
| Language | TypeScript 5.7 |
| Build | Vite 6 (dev server with API proxy to localhost:8080) |
| State | Pinia 3 |
| Routing | Vue Router 4 |
| HTTP | Axios |
| Charts | Chart.js 4 + vue-chartjs 5 |
| Track maps | HTML Canvas 2D |

---

## Architecture

```
src/
├── api/
│   └── client.ts              — Axios HTTP client, all API functions
├── components/
│   └── FeedStatus.vue         — Per-feed health display
├── router/
│   └── index.ts               — Vue Router config (9 routes)
├── stores/
│   ├── sessions.ts            — Pinia store for session/run management
│   ├── telemetry.ts           — Pinia store for live telemetry polling
│   └── tracks.ts              — Pinia store for track model CRUD
├── types/
│   └── index.ts               — TypeScript interfaces matching API responses
├── utils/
│   └── analysis.ts            — Type guards for analysis results
├── views/
│   ├── DashboardView.vue      — Main dashboard (live feeds, status cards)
│   ├── LiveView.vue           — Live telemetry gauges
│   ├── SessionsView.vue       — Session list + create
│   ├── SessionDetailView.vue  — Session detail, run management, analysis, track mapping workflow
│   ├── ShiftPointsView.vue    — Shift point analysis charts
│   ├── GripAnalysisView.vue   — Car grip envelope visualization (v0.1.6)
│   ├── CharacteristicsView.vue — Car characteristics aggregation (v0.1.5)
│   ├── TracksView.vue         — Stored track model listing
│   └── TrackDetailView.vue    — Track model detail with full geometry rendering
├── App.vue
└── main.ts
```

---

## Key Pages & Features

### Dashboard (`/`)
- System status cards (API Server, Sim Connection, Recording) in 3-column grid
- Active recording info
- Quick links to sessions and tracks

### Live View (`/live`)
- Real-time telemetry gauges (speed, RPM, gear, throttle, brake)
- Per-feed status panels via FeedStatus component
- Polls `/api/live` endpoint

### Sessions (`/sessions`)
- Session list with status badges
- Create new session form (use case selector including Car Grip, Track Mapping)
- Delete sessions

### Session Detail (`/sessions/:id`)
- Session info card (use case, runs, timestamps, guidance)
- **Run management:** start/stop/delete runs, merge feeds toggle
- **Session lifecycle:** complete, reopen, re-analyze
- **Quick stats** for shift points (recommended RPM, crossover count, runs analyzed)
- **Quick stats** for car grip (max lateral/accel/brake/combined G)
- **Quick stats** for track map (boundaries, total points)
- **Track Mapping workflow** — Build Track Model button with validation

### Shift Points Analysis (`/analysis/shift-points/:id`)
- Summary stats + 4 charts (RPM vs Force, Speed vs Force, Speed vs RPM, Crossover Points)
- Crossover points table

### Car Grip Analysis (`/analysis/grip/:id`) — v0.1.6
- Summary stats: max lateral G, max accel G, max brake G, max combined G, peak lateral speed
- **4 charts:**
  1. **Grip Envelope** — peak G (lateral/accel/brake) vs speed (line chart, envelope extraction)
  2. **Grip Circle** — longitudinal G vs lateral G scatter (friction circle)
  3. **Cornering Grip vs Speed** — peak lateral G vs speed
  4. **Steering Response** — steer angle vs lateral G scatter
- Accessed from SessionDetailView "View Full Analysis" button for `car_grip` sessions

### Car Characteristics (`/characteristics`) — v0.1.5
- Expandable car cards with aggregated shift-point profiles

### Tracks (`/tracks`) and Track Detail (`/tracks/:game/:trackName`) — v0.1.4
- Track model listing and Canvas 2D geometry rendering

---

## TypeScript Types

Defined in `src/types/index.ts`. Key interfaces:

- `UseCase` — `shift_points`, `car_grip`, `racing_line`, `braking_analysis`, `lap_times`, `sector_analysis`, `track_mapping`, `general`
- **Car grip types (v0.1.6):**
  - `CarGripAnalysis` — `{ summary, grip_envelope, grip_circle, steering_response, runs_analyzed, total_frames_analyzed }`
  - `GripEnvelopePoint` — `{ speed_kmh, max_lateral_g, max_accel_g, max_brake_g, sample_count }`
  - `GripCirclePoint` — `{ longitudinal_g, lateral_g }`
  - `SteeringResponsePoint` — `{ steer, lateral_g, speed_kmh }`
  - `GripSummary` — `{ max_lateral_g, max_accel_g, max_brake_g, max_combined_g, peak_lateral_speed_kmh }`
- Shift point types: `ShiftPointAnalysis`, `GearCurve`, `GearDataPoint`, `CrossoverPoint`
- Car characteristics types (v0.1.5): `CarProfile`, `CarGearProfile`, `CarProfileDetail`
- Track model types (v0.1.4): `TrackModel`, `TrackSummary`, `Corner`, `Sector`, `BuildTrackModelRequest`

### Type Guards (`src/utils/analysis.ts`)
- `isShiftPointAnalysis(data)` — checks for `gear_curves`
- `isCarGripAnalysis(data)` — checks for `grip_envelope` (v0.1.6)
- `isTrackMapAnalysis(data)` — checks for `boundaries`
- `isNotImplemented(data)` — checks for `status: 'not_implemented'`

---

## Change Log

### v0.1.6 (2026-06-24) — Car Grip Analysis

**New Features:**
- New view: GripAnalysisView (`/analysis/grip/:id`) with 4 scatter/line charts:
  1. Grip Envelope (peak lateral/accel/brake G vs speed — envelope extraction)
  2. Grip Circle (longitudinal G vs lateral G scatter — friction circle)
  3. Cornering Grip vs Speed (peak lateral G vs speed)
  4. Steering Response (steer angle vs lateral G scatter)
- Summary stats: max lateral/accel/brake/combined G, peak lateral speed, frames analyzed
- Grip analysis types: `CarGripAnalysis`, `GripEnvelopePoint`, `GripCirclePoint`, `SteeringResponsePoint`, `GripSummary`
- `isCarGripAnalysis` type guard in utils/analysis.ts
- `car_grip` added to `UseCase` type
- SessionDetailView: grip analysis quick stats (4 stat cards) + "View Full Analysis" button for `car_grip`
- Route: `/analysis/grip/:id`
- Global `.grid-4` CSS utility added to main.css

### v0.1.5 (2026-06-24) — Characteristics Views, track_map Removal, Auto-Analyze

- CharacteristicsView (`/characteristics`) — expandable car cards with aggregated shift-point profiles
- Tracks views committed (TracksView, TrackDetailView, tracks store)
- `track_map` use case removed, `TrackMapView.vue` deleted
- `handleBuildTrack` auto-runs `reAnalyze()` before `buildTrackModel()`
- `Game` type values updated to snake_case

### v0.1.4 (2026-06-08) — Track Mapping Web Client

- Track model types, API client functions, tracks Pinia store
- TracksView, TrackDetailView (Canvas 2D geometry rendering)
- Build Track Model workflow in SessionDetailView

### v0.1.3 (2026-06-06) — Run Management & Feed Merging
### v0.1.2 (2026-06-06) — Shifting Analysis Charts
### v0.1.1 (2026-06-05) — Dashboard Status Card Layout
### v0.1.0 (2026-06-05) — Initial Release

---

## Cross-References

- **Main project plan:** [Sim Racing Telemetry Analysis Platform — Project Plan](joplin://6c0dcb2a567348fd9796f50c790082e4)
- **API reference:** [rusty-telemetry — REST API Reference](joplin://0c837f4e6b7e462a997cbc19e47c864a)
- **Architecture note:** [Architecture & Infrastructure](joplin://c1c3a7b2055642268ab230b95551f470)

---

*Last updated: 2026-06-24 — v0.1.6: car grip analysis view (grip envelope, grip circle, steering response, cornering grip vs speed). v0.1.5: car characteristics, track_map removal, auto-analyze, tracks views committed.*

id: 50a09627d5d347009197b94bcee90411
parent_id: 0e8e00b432a840628faa4df5bc2068bc
created_time: 2026-06-06T08:10:39.362Z
updated_time: 2026-06-24T08:23:56.553Z
is_conflict: 0
latitude: 0.00000000
longitude: 0.00000000
altitude: 0.0000
author: 
source_url: 
is_todo: 0
todo_due: 0
todo_completed: 0
source: joplin-desktop
source_application: net.cozic.joplin-desktop
application_data: 
order: 1780733439362
user_created_time: 2026-06-06T08:10:39.362Z
user_updated_time: 2026-06-24T08:23:56.553Z
encryption_cipher_text: 
encryption_applied: 0
markup_language: 1
is_shared: 0
share_id: 
conflict_original_id: 
master_key_id: 
user_data: 
deleted_time: 0
type_: 1