Strategy Desktop

Strategy Desktop ist ein lokaler Rennassistent für iRacing auf Windows.
Das Projekt soll Fahrer während einer Session mit klaren Ansagen, einfacher Übersicht und nachvollziehbarer Strategie unterstützen.

Einfach gesagt:

• iRacing liefert Telemetrie
• diese App versteht die Daten
• daraus entstehen Hinweise wie Sprit reicht noch X Runden oder Boxenfenster ist offen
• die Hinweise werden im Overlay angezeigt und auf Wunsch vorgelesen

Die App ist bewusst local-first gedacht. Sie soll also schon nützlich sein, ohne Cloud-Zwang, ohne Team-Backend und ohne komplizierte Infrastruktur.

---

Was ist das hier?

Dieses Repository enthält eine Desktop-Anwendung auf Basis von Go + Wails.

Ziel ist ein digitaler Begleiter für Rennfahrer, der langfristig mehrere Rollen übernehmen soll:

• Race Engineer – sagt dir wichtige Dinge direkt im Rennen
• Strategy Engineer – hilft bei Sprit, Boxenfenster und Rennplanung
• Spotter – warnt vor Verkehr und kritischen Situationen
• Coach / Trainer – wertet Sessions später aus und hilft beim Lernen

Der aktuelle Stand konzentriert sich vor allem auf den ersten nützlichen Kern:

Lokale iRacing-Daten erfassen → Strategie ableiten → eine klare Ansage erzeugen → im Overlay und per Audio ausgeben

---

Für wen ist das gedacht?

Für Menschen, die iRacing fahren und während einer Session Unterstützung wollen, ohne ständig selbst Zahlen lesen zu müssen.

Zum Beispiel:

• Fahrer, die beim Rennen den Überblick über den Sprit behalten wollen
• Fahrer, die eine einfache Strategiehilfe möchten
• Simracer, die später ihre Sessions besser auswerten wollen
• Entwickler, die an einem lokalen Strategy-/Engineer-System weiterbauen möchten

---

Was wollen wir langfristig erreichen?

Die Vision ist nicht einfach nur ein hübsches Overlay.

Wir wollen ein System bauen, das:

• verlässlich ist
• verständlich bleibt
• lokal funktioniert
• rennrelevante Aussagen deterministisch trifft
• später um Coach-, Analyse- und Sync-Funktionen erweitert werden kann

Wichtig dabei:

• Keine Abhängigkeit von einer Cloud für rennkritische Funktionen
• Keine freie, unkontrollierte KI, die mitten im Rennen irgendetwas erfindet
• Erst eine saubere lokale Basis, dann optionale spätere Erweiterungen

Kurz gesagt:

Erst ein guter lokaler Renningenieur. Danach ein stärkeres Analyse- und Coaching-System.

---

Was kann der aktuelle Stand bereits?

Der aktuelle Code ist noch kein fertiges Endprodukt, aber es gibt schon eine klare funktionierende Grundlage.

Bereits vorhanden

• Windows-Desktop-App mit Wails
• Lokale iRacing-Anbindung über das eingebettete Go-SDK (irsdk)
• Runtime-Service, der Telemetrie, Sessiondaten, Strategie, UI und Audio verbindet
• Einfache Sprit- und Boxenlogik
• Engineer Calls mit Prioritäten und Cooldown
• Overlay-Oberfläche mit Status, Session, Strategie und letzter Ansage
• Text-to-Speech-Ausgabe
  • windows_sapi auf Windows
  • noop als Fallback/Testmodus
• Sprachsteuerungs-Vorbereitung
  • Provider-Grenze für STT ist vorhanden
  • aktuell ist nur disabled aktiv
  • Mock-Textbefehle können bereits verarbeitet werden
• Lokale SQLite-Aufzeichnung
  • Session-Kontext
  • schnelle Telemetrie-Samples
  • langsame Telemetrie-Samples
  • Strategie-Zustände
  • Engineer Calls
  • Sync-Outbox für spätere Upload-/Serverpfade
• Tests für zentrale Teile der Logik

Beispiele für unterstützte Aktionen

• Runtime starten und stoppen
• Quiet Mode ein- und ausschalten
• letzte Ansage wiederholen
• TTS-Provider auswählen
• Textbefehle wie diese senden:
  • fuel status
  • strategy
  • repeat
  • ruhe
  • mehr ansagen

Live-Smoke-Diagnose aktivieren

Der Live-Smoke-Report ist standardmäßig deaktiviert, damit Diagnose- und Laufzeitdaten nicht versehentlich in normalen Builds sichtbar sind. Für lokale iRacing-Tests kann er in der Settings-Datei bewusst eingeschaltet werden:

{
  "diagnostics": {
    "enabled": true
  }
}

Die Settings-Datei liegt unter dem Windows-Benutzerkonfigurationsordner in Strategy Desktop/settings.json. Wenn Diagnostics aktiv ist, zeigt die UI einen zusätzlichen Bereich mit Runtime-Checks, Frame-Zähler, Audio-Status, Recording-Raten und letzter Frame-Zeit an.

---

Was ist noch nicht fertig?

Das ist wichtig, damit Erwartungen sauber gesetzt sind.

Noch nicht vollständig umgesetzt sind unter anderem:

• echtes Mikrofon-STT im produktiven Einsatz
• ausgereifter Spotter
• tiefe Traffic-/Opponent-Modelle
• vollwertiger Driving Coach
• umfangreiche Post-Session-Analyse
• Server-Sync / Cloud-Funktionen
• Multi-Sim-Unterstützung

Das Repository zeigt also bereits die Richtung und die technische Basis, aber nicht schon die komplette Endvision.

---

Wie funktioniert das System – ganz einfach erklärt

Stell dir die App wie eine kleine Kette vor:

1. iRacing erzeugt Live-Daten
2. Die App liest diese Daten lokal aus
3. Die Daten werden in ein einheitliches internes Format gebracht
4. Die Strategielogik berechnet daraus einfache Aussagen
5. Der Narration-Planer entscheidet, ob eine Ansage gerade sinnvoll ist
6. Die Ansage wird:
   • im Overlay angezeigt
   • über Audio vorgelesen
7. Gleichzeitig werden wichtige Daten lokal gespeichert

Oder noch kürzer:

Sim-Daten rein → Logik arbeitet → Hinweis raus → Verlauf wird gespeichert

---

Architektur in verständlicher Form

1. iRacing-Adapter

Der Adapter verbindet sich mit iRacing und liest Telemetrie sowie Session-Informationen aus.

Er kümmert sich um Dinge wie:

• warten, bis iRacing verfügbar ist
• wieder verbinden nach einem Verbindungsabbruch
• passende Telemetrie-Felder abonnieren
• Sessiondaten aus der iRacing-Session lesen

2. Runtime

Die Runtime ist das Herzstück der App.

Sie verbindet:

• Datenquelle
• Strategielogik
• Ansageplanung
• Audio
• UI
• Recorder

3. Strategie-Engine

Die Strategie-Engine ist aktuell bewusst einfach und nachvollziehbar.

Sie berechnet unter anderem:

• aktuellen Spritstand
• geschätzten Verbrauch pro Runde
• verbleibende Runden
• ob das Boxenfenster offen ist

4. Narration / Engineer Calls

Hier wird entschieden:

• muss jetzt überhaupt etwas gesagt werden?
• wie wichtig ist die Meldung?
• soll sie wegen Cooldown unterdrückt werden?
• darf sie im Quiet Mode gesprochen werden?

5. Audio

Wenn Audio aktiv ist, wird eine Ansage gesprochen.
Falls Audio nicht verfügbar ist, soll das System trotzdem weiterlaufen und die Information mindestens im Overlay zeigen.

6. Overlay / UI

Die Oberfläche zeigt aktuell vor allem:

• Laufzeitstatus
• Track / Fahrer / Auto / Session
• Sprit- und Strategieinfos
• letzte Ansage
• einfache Steuerung für Runtime, Quiet Mode, Repeat und Provider-Auswahl

7. Lokale Speicherung

Die App speichert Daten in einer SQLite-Datenbank.
Das ist wichtig für:

• spätere Analyse
• Replay / Debugging
• Strategie-Historie
• zukünftige Sync-Funktionen

---

Aktueller Datenfluss

iRacing Shared Memory
        ↓
internal/irsdkadapter
        ↓
internal/runtime
   ├─ internal/strategy
   ├─ internal/narration
   ├─ internal/audio
   ├─ internal/ui
   └─ internal/storage
        ↓
Overlay + Audio + lokale SQLite-Datenbank

---

Projektstruktur

Die wichtigsten Ordner:

• /main.go
  Einstiegspunkt der Desktop-App

• /internal/app
  Wails-gebundene Methoden, die vom Frontend aufgerufen werden

• /internal/runtime
  Orchestrierung der gesamten Laufzeitlogik

• /internal/irsdkadapter
  Verbindung zu iRacing und Telemetrie-Umwandlung

• /internal/strategy
  Strategieberechnung, aktuell vor allem Sprit- und Boxenlogik

• /internal/narration
  Planung und Filterung der Engineer Calls

• /internal/audio
  TTS-Provider und Audio-Ausgabe

• /internal/voice
  STT-Provider-Grenze und Intent-Erkennung für Sprachbefehle

• /internal/storage
  SQLite-Recorder und lokale Datenspeicherung

• /internal/ui
  Projektion des Runtime-Zustands ins Overlay-Modell

• /internal/assets/web
  Eingebettete Web-Oberfläche für die Wails-App

• /docs
  Produkt-, Architektur- und Richtungsdokumente

• /irsdk
  Lokales Go-SDK für die iRacing-Anbindung

---

Warum ist das local-first so wichtig?

Im Rennen zählt:

• geringe Verzögerung
• hohe Verlässlichkeit
• klare Kontrolle

Ein cloudabhängiges System kann im falschen Moment unzuverlässig sein.
Darum ist die Grundidee hier:

• live und lokal
• schnell
• vorhersagbar
• auch ohne Internet nützlich

Spätere Online-Funktionen sind denkbar, aber nur als zusätzliche Schicht, nicht als Pflicht.

---

Aktuelle Produktidee in einem Satz

Ein lokaler iRacing-Begleiter, der während der Fahrt sinnvolle Hinweise gibt und später zu einem vollständigen Strategy-, Spotter- und Coaching-System wachsen kann.

---

Voraussetzungen

Für die echte Live-Nutzung des Produkts ist derzeit vor allem Folgendes relevant:

• Windows
• iRacing
• Go 1.25+
• Wails v2

Wichtig:

• Die Live-iRacing-Anbindung ist ein Windows-Zielsystem
• Die Tests selbst können teilweise auch auf anderen Systemen laufen
• Die Audio-Ausgabe über windows_sapi funktioniert nur auf Windows

---

Entwicklung lokal starten

1. Repository öffnen

cd path/to/strategy-desktop

2. Abhängigkeiten laden

go mod download

3. Tests ausführen

go test ./...

4. App im Entwicklungsmodus starten

Wenn Wails installiert ist:

wails dev

5. Build erzeugen

wails build

Hinweis:
Das MVP nutzt eingebettete Web-Assets. Es ist also bewusst einfach gehalten und setzt nicht auf eine große separate Frontend-Build-Kette.

---

Was speichert die App lokal?

Der Recorder legt eine SQLite-Datenbank an und speichert bereits mehrere wichtige Arten von Informationen:

• Sessiondaten
• schnelle Telemetrie-Samples
• langsamere Telemetrie-Samples
• berechnete Strategie-Zustände
• erzeugte Engineer Calls
• Sync-Outbox-Einträge für spätere Erweiterungen

Warum das wichtig ist:

• Man kann später auswerten, was während der Session passiert ist
• Strategieentscheidungen werden nachvollziehbar
• spätere Coaching- und Analysefunktionen bekommen eine saubere Datenbasis

---

Beispiel für die Benutzererfahrung

So soll sich die App für einen Fahrer anfühlen:

1. App starten
2. Solange iRacing nicht läuft: Status zeigt waiting for iRacing
3. Sobald iRacing verfügbar ist: Verbindung wird automatisch hergestellt
4. Track-, Fahrer- und Sessiondaten erscheinen
5. Sprit- und Strategiedaten werden laufend aktualisiert
6. Wenn nötig, kommt eine klare Ansage wie:
   • Fuel low
   • Pit window open
7. Dieselbe Information ist sichtbar und hörbar

Das Ziel ist nicht, den Fahrer mit Informationen zu überladen.
Das Ziel ist, im richtigen Moment die richtige kurze Aussage zu liefern.

---

Dokumente im Repository

Wenn du die fachliche Richtung besser verstehen möchtest, schau besonders in:

• /docs/source_prd_alignment.md
• /docs/go_wails_mvp_plan.md
• /docs/telemetry_data_strategy.md
• /docs/audio_stt_storage_architecture.md

Diese Dateien beschreiben:

• worauf sich das Produkt inhaltlich stützt
• wie die MVP-Architektur gedacht ist
• welche Telemetriedaten relevant sind
• wie Audio, STT und Speicherung weiter ausgebaut werden sollen

---

Roadmap in einfacher Sprache

Kurzfristig

• stabile lokale Engineer-Basis
• saubere Overlay-Anzeige
• bessere Strategiehinweise
• robustere Audio-/Voice-Wege
• verlässliche lokale Aufzeichnung

Mittelfristig

• bessere Sprachsteuerung
• stärkerer Spotter
• mehr Traffic- und Strategie-Kontext
• Replay- und Auswertungsfunktionen
• mehr Coach-Daten und Abschnittsanalyse

Langfristig

• tieferes Coaching
• umfangreichere Post-Session-Analysen
• optionale Sync-/Server-Funktionen
• mögliche Plattform-Erweiterungen

---

Beitrag leisten

Beiträge sind willkommen – besonders bei:

• Stabilität und Robustheit
• besserer Strategielogik
• Voice-/Audio-Architektur
• SQLite-/Recorder-Themen
• Overlay-Usability
• Testabdeckung
• klarer Dokumentation

Wenn du an dem Projekt mitarbeitest, ist der wichtigste Grundsatz:

Rennkritische Funktionen sollen lokal, nachvollziehbar und zuverlässig bleiben.

---

Zusammenfassung

Strategy Desktop ist der Anfang eines lokalen Rennassistenten für iRacing.

Heute liegt der Fokus auf:

• lokaler Telemetrie
• einfacher, robuster Strategielogik
• klaren Engineer Calls
• Overlay + Audio
• lokaler Datenspeicherung

Langfristig soll daraus ein System entstehen, das Fahrer während des Rennens unterstützt und nach dem Rennen beim Lernen hilft – ohne die lokale Zuverlässigkeit aus den Augen zu verlieren.

Diagnostics Export Bundle

Use the Settings view to run Export diagnostics bundle. The app writes a local zip bundle under the Strategy Desktop diagnostics folder and returns the full output path in the UI.

Included:

• app version, commit, build date, and Go runtime environment
• sanitized settings summary
• runtime smoke report
• recent bounded diagnostic events
• recorder diagnostics when available
• recent recorded session summaries
• SQLite PRAGMA integrity_check result when the local database is present and readable

Excluded:

• secrets, tokens, raw credentials, and unsanitized settings files
• raw high-volume telemetry dumps
• personally identifying path details beyond a redacted database basename