Commercial Deployment Architecture

# Commercial Deployment Architecture

> **Parent note:** [Sim Racing Telemetry Analysis Platform — Project Plan](joplin://6c0dcb2a567348fd9796f50c790082e4)
> **Created:** 2026-06-25
> **Context:** How to deploy racecraft + rusty-telemetry as a commercial product for karting venues, sim racing centers, and real-world racing.

---

## Architecture Overview

```
                         ┌──────────────────────┐
                         │   Your Cloud (VPS)    │
                         │                       │
  Driver phone ──────────┤  ┌─────────────────┐ │
  (data capture app)     │  │  rusty-telemetry │ │
                         │  │  API (multi-tenant)│ │
  Venue PC/tablet ───────┤  │  + LLM service   │ │
  (coach dashboard)      │  │  + venue data     │ │
                         │  └────────┬──────────┘ │
  Driver web ────────────┤           │             │
  (post-session review)  │  ┌────────▼──────────┐ │
                         │  │  racecraft web    │ │
                         │  │  (white-labeled)   │ │
                         │  └───────────────────┘ │
                         └───────────────────────┘
```

## Multi-Tenant (not per-instance)

One deployment serves all venues. Every table gets a `venue_id` column. Benefits:
- One server to deploy, update, monitor
- One LLM API key
- Cross-venue features (global leaderboards, "fastest across all Austrian karting tracks")
- Low cost: one €10-20/month VPS handles 10+ venues

**Per-instance for enterprise tier only** — large venues or racing schools wanting data isolation / self-hosting get a dedicated Docker stack at a premium.

---

## Components

| Component | What It Is | Status |
|---|---|---|
| **rusty-telemetry API** | Multi-tenant API server (add `venue_id` to sessions, tracks, characteristics) | Exists — needs multi-tenancy layer |
| **LLM coaching service** | New endpoint: session analysis + characteristics + comparative data → coaching report | New — thin layer, ~2-3 days |
| **racecraft web** | White-labeled frontend (venue branding via config, not code forks) | Exists — needs theming/branding layer |
| **Driver mobile app** | Phone GPS/RPM capture → sends to API → receives coaching report | **Major gap** — needs building |
| **Venue dashboard** | Web UI for venue staff (see all drivers, manage sessions, export reports) | Partial — extends existing racecraft |

---

## Access Levels

| Role | Sees | Can Do |
|---|---|---|
| **Super admin** (you) | All venues, global config | Manage venues, set pricing, system health |
| **Venue admin** | Their venue only | Manage drivers, configure branding, export reports, view all sessions |
| **Coach/instructor** | Their venue's drivers | View any driver's data, add manual coaching notes, compare drivers |
| **Driver** | Their own data only | View own sessions, coaching reports, compare with venue leaderboard |

Auth: JWT-based, venue-scoped tokens. Driver accounts created by venue admin (or self-registration with venue code).

---

## Data Flow for a Karting Session

```
1. Driver arrives, rents kart
2. Venue staff mounts GPS puck on kart, starts capture
   (or: instrumented kart with Aim MyChron, data read out after session)
3. Driver does session (5-10 laps)
4. Data uploaded to API (via app, USB, or Aim CSV export)
5. API runs analysis pipeline:
   - Lap detection (spline crossing)
   - Corner analysis (track model)
   - Grip envelope extraction
   - Compare vs. vehicle characteristics
   - Compare vs. other drivers at this venue
6. LLM generates coaching report
7. Driver gets QR code → scans → sees report on phone
8. Report: "T3 you lost 0.4s — brake later, you have 0.3G grip headroom"
```

**Pilot approach (no app needed):** Venue staff captures data with a dedicated phone/GPS puck, then hands drivers a QR code linking to their coaching report on the web. Zero app for drivers — the venue does the capture.

---

## Mobile App Build Options

| Option | Effort | Quality | For pilot? |
|---|---|---|---|
| **PWA (web app with GPS API)** | Low (extend racecraft) | Medium — background GPS limited on iOS | Maybe |
| **Expo (React Native)** | Medium | Good — native GPS, faster dev | Best balance |
| **React Native / Flutter** | High (new codebase) | High — native GPS, background capture | Post-pilot |

---

## Build Priority Order

1. **Multi-tenant layer** in rusty-telemetry (venue_id everywhere, auth middleware)
2. **LLM coaching endpoint** (structured analysis → natural language report)
3. **Venue capture workflow** (staff-triggered, not driver app — much simpler)
4. **Driver web report view** (read-only, QR-code accessible, no login needed)
5. **Mobile app** (later, once pilot validates demand)

---

## Licensing Context

Both repos are AGPL-3.0 + commercial dual license (see LICENSE + COMMERCIAL_LICENSE.md in both repos). Venues that don't want AGPL obligations (self-hosting modified versions, embedding in hardware) need a commercial license.

---

*Created: 2026-06-25*

id: 052dec863e0948868304e44628986973
parent_id: 0e8e00b432a840628faa4df5bc2068bc
created_time: 2026-06-25T10:26:03.487Z
updated_time: 2026-06-25T10:26:03.487Z
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: 1782383163487
user_created_time: 2026-06-25T10:26:03.487Z
user_updated_time: 2026-06-25T10:26:03.487Z
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