Architecture Decision Records¶
Decisions for the Pitwall Sprint, adapted from the Pitwall open-source project with modifications for the Google hardware stack and production requirements.
Index¶
| ADR | Title | Status | Origin |
|---|---|---|---|
| 001 | Confidence-Annotated Telemetry Frame | Accepted | From Pitwall, adapted for Racelogic + OBDLink |
| 002 | Split-Brain Architecture with Message Arbiter | Accepted | From Pitwall, adapted for Gemma 4 + Gemini 3 |
| 003 | Gemma 4 as Edge LLM on Pixel 10 TPU | Accepted | New for sprint (replaces Pitwall's rules engine) |
| 004 | Antigravity Store-and-Forward Pipeline | Accepted | New for sprint (replaces Pitwall's SSE streaming) |
| 005 | Pedagogical Vector Retrieval from Ross Bentley Curriculum | Accepted | New for sprint (replaces Pitwall's hardcoded rules) |
| 006 | Sensor Fusion for Racelogic + OBDLink | Accepted | From Pitwall ADR-026, adapted for pro hardware |
| 007 | Event-Sourced Driver Profile | Accepted | From Pitwall ADR-023, unchanged |
| 008 | Pedagogical Vector Regression Testing | Accepted | From Pitwall ADR-027, adapted for vectors |
| 009 | Graceful Degradation Protocol | Accepted | From Pitwall ADR-028, adapted for single-device |
| 010 | HTTP Bridge as Warm-Path Tier 1 | Accepted | New 2026-04-28 — codifies src/pitwall/__main__.py |
| 011 | Named-Marker Schema for Track Coaching | Accepted | New 2026-04-28 — markers, nicknames, coaching tips |
| 012 | Coach Engine Adapter (on-device LiteRT-LM) | Accepted | New 2026-04-28 — RuleCoach + LitertCoach |
| 013 | Frontend Visualizes, Backend Reasons | Accepted | New 2026-04-28 — backend owns LLM logic + system prompts |
| 014 | Sonoma is the Product | Accepted | New 2026-04-28 — three-mode coaching + analysis pipeline + visualisation bundles, all Sonoma-hardcoded |
| 015 | Universal Telemetry Sink + Capability Model | Accepted | New 2026-04-29 — tall signal store + registry + capability-aware coaches/widgets for any car / any data feed |
| 016 | USB-CAN Ingest + Vue PWA Frontend | Accepted | New 2026-04-29 — kills BLE + native Flutter app; everything non-presentation goes in pitwall, frontend becomes a Vue PWA |
| 017 | Three-Tier Coach Architecture (LLM in paddock, canonical phrases on track) | Accepted | New 2026-04-29 — LitertCoach.propose() no longer calls the LLM; in-drive becomes RuleCoach + canonical phrases; LLM reserved for brief() + debrief(); cloud Gemini removed |
| 018 | Field-readiness blockers + pedagogy tuning (Team 2 review) | Accepted | New 2026-04-30 — LLM friction sink, audio ducker, Kalman dead-reckoning, transition-focused pedagogy, highlight-reel debrief opener; framework refactor deferred post-Sonoma |
| 019 | ADK Multi-Agent Paddock Backend | Accepted | New 2026-05-01 — 18-agent ADK topology, 15 SQL-safe tools, conversations + agent_traces tables, /coach/ask Q&A endpoint |
| 020 | ADK Agent Architecture Refactor | Accepted | New 2026-05-01 — 7 structural fixes: PitwallOrchestrator, SequentialAgent/ParallelAgent pipelines, output_key pattern, SQL safety, save_voice_scripts |
| 021 | ADK Second Audit — Runner, Concurrency, Feature Gaps | Accepted | New 2026-05-01 — Runner API, race-condition fix, persistent sessions for KV-cache reuse, PitwallTracingPlugin + agent_traces |
| 022 | On-Phone LocalLLM Server (OpenAI-Compatible) | Accepted | New 2026-05-12 — adopts LocalLLM APK as the primary on-device LLM server; PITWALL_ADK_BACKEND=openai dials it over 127.0.0.1:8099/v1. Legacy engine (in-process) and litertlm (lit serve) remain available; same openai path also covers Ollama / LM Studio / llama.cpp / vLLM on dev boxes |
| 023 | On-Device Voice (ONNX) for TTS + STT | Proposed | New 2026-05-23 — replaces Web Speech API with onnxruntime-web + Piper en-GB TTS + sherpa-onnx streaming Zipformer STT, ~55 MB models cached in OPFS; restores on-device guarantee at the voice layer; pre-rendered MP3 hot-phrase fast path retained |