audi-app/COMPANION_APP_ARCHITECTURE.md

DataMetric360 — Companion App Architecture (design decided, not yet built)

App name: DataMetric360 (decided 2026-08-10). Public hostname: a subdomain of datametric360.app, a dedicated domain registered at all-inkl solely for this purpose (see §5.4 for why it must be a separate domain). Both the app name and the domain are deliberately neutral — they don't advertise "Audi", "car", or "GPS tracker" to anyone who sees the hostname or the app icon, which is a small but free privacy win for a hostname that will be publicly resolvable.

Status: architecture decisions locked in during design discussion on 2026-08-10. No code for this exists yet — this is a separate, not-yet-started project sitting alongside the finished HA panel described in SPECIFICATION.md. Implementation is explicitly deferred until the FMM003 hardware is installed and wired (owner's own framing: "Inbetriebnahme findet separat statt, wenn die HW vorrätig ist"). This file exists so the decisions already made aren't lost before that point.

Relationship to the rest of the repo:

• homeassistant/ — the finished, in-use HA panel (SPECIFICATION.md is authoritative for it). Its data source today is the HACS integration TommiG1/HA_VAG-EU-Data-Act plus the iPhone Companion App's WLAN sensor for trip detection.
• design-system/ — the React component library (no Audi brand assets) built to feed Claude Design. Becomes directly useful here: it's the intended shared UI foundation for the app described below.
• This file — describes a new, third piece: a companion app that will eventually supersede the HA panel's role, once built.

---

1. Concept

One responsive web app, built with the design-system/ component library, shipped three ways:

1. Native iOS app — via Capacitor.
2. Native Android app — via Capacitor.
3. Embedded in Home Assistant — as a plain panel_iframe (not panel_custom/hass injection), so the same build just gets more screen space and reflows via CSS breakpoints instead of floating a fixed phone-card layout in the middle of a bigger screen.

Once this exists, it supersedes homeassistant/www/audi-dashboard-app.js — the current panel_custom implementation is not meant to be maintained forever in parallel; it gets replaced, not duplicated. That's an explicit, confirmed decision, not an assumption. audi-dashboard-app.js gets archived, not deleted, once superseded — same safety-net pattern already used in this project (.bak-before-audit-merge files).

Distribution: sideload only, no App Store / Play Store. Confirmed decision. This matters beyond convenience: the Audi Type font, the four-rings SVG, and the model-badge SVGs are licensed only for this one private, non-published installation (SPECIFICATION.md §2, bauauftrag.md §8/§12) — exactly why design-system/ strips all of that out, since it gets uploaded to a third party (Claude Design). A sideloaded app installed directly onto the owner's own two phones, never published to a store, stays inside that same private-installation scope — so the companion app can use the real Audi assets, matching the "same look and feel" decision already made, no generic-fallback treatment needed.

Frontend head start via design-system/ + Claude Design: the component-library sync gave Claude Design the real building blocks (tokens, ~19 components) to design with — it has not yet designed this app's actual screens (Home, Trips, Fuel, Settings, reworked around the REST/WebSocket data model instead of hass). That's a future step, following the same pattern as the original Design-Audit task this session started with: design in Claude Design using the real components, then implement the result into actual Capacitor/React code.

The iPhone stops being a data source entirely — it becomes purely a display device for this app, same as Android. All vehicle data comes from the FMM003 (see §2), not from the iPhone Companion App.

---

2. Data source: FMM003 replaces the iPhone + VAG integration

Confirmed, explicit decision (retiring two existing data sources):

• The iPhone Companion App's WLAN sensor (sensor.iphone_wifi_connection), used today for trip start/end detection, is fully retired. No fallback to it.
• The HACS integration TommiG1/HA_VAG-EU-Data-Act is fully retired as a data source.
• All vehicle data comes from the FMM003 (fully wired to the vehicle's CAN/FMS bus), via Codec8, into Home Assistant as one combined, flexibly-mapped entity (no hardcoded field list — see the no-hardcoding mapping system discussed separately, not yet written to a file).

Decided (2026-08-10, after web research — see rationale below): Traccar, minimal variant.

Research question: is there something more efficient than Traccar for decoding Codec8 from an FMM003? Checked and ruled out:

• HA's official "Teltonika" integration — for Teltonika routers (RUT series: signal/modem/network monitoring), unrelated to GPS/AVL trackers. Not applicable.
• A Teltonika-RMS-based HA integration exists (derliebemarcus/teltonika_rms) but connects through Teltonika's own cloud (RMS) — same objection as the earlier Flespi rejection: vehicle/GPS data would transit an external vendor cloud, which is exactly what this whole redesign was meant to avoid.
• OpenRemote (an alternative fleet platform some Teltonika docs point to) — a full IoT asset-management platform with a rule engine and dashboards; heavier than Traccar, not lighter.
• Minimal standalone Codec8 parser libraries (e.g. teltonika-go, small Python GPS-server scripts) — genuinely lighter in principle (no bundled platform/Tomcat), but sacrifice exactly what makes Traccar the safer choice: even Traccar itself, mature and community-maintained for years, still has open issues about firmware-specific Codec8 decoding quirks per device generation. A standalone parser would hit the same class of edge cases with none of that accumulated fixing behind it.

Conclusion: no better alternative found — Traccar stays, but in a genuinely minimal shape:

• Database: H2 (embedded, file-based), not MariaDB. This was a wrong assumption in the first draft of this document — Traccar's own upstream default database is H2, and the HA Community Add-on (hassio-addons/addon-traccar) ships with H2 pre-configured (jdbc:h2:/data/traccar) out of the box. MariaDB is only the add-on docs' recommendation for larger/multi-user production deployments, not a hard requirement. For one vehicle, one device, one private user, H2 is the right call — no MariaDB add-on needed at all, one fewer service to run and back up.
  • Known trade-off (from community reports): occasional H2 corruption/data loss across Traccar version upgrades. Mitigation: extend the existing daily backup.py routine to also copy Traccar's .mv.db file alongside the other data files — same backup pattern already in place, no new mechanism.
• Disable geofencing and reports/notifications in Traccar's config — none of that applies to a single always-known vehicle; keeps the running feature surface to just device ingestion + Position Forwarding, which is all this project actually uses.
• Position Forwarding → HA webhook (as already planned) remains the integration path for CAN/FMS attributes (fuel, RPM, etc.), since HA's own official traccar_server integration is device_tracker/geofence-focused and wouldn't surface those extra AVL fields on its own.

Hardware confirmed sufficient for this: Dell OptiPlex 3000 TC, Pentium N6005, 16 GB DDR4, 256 GB NVMe — comfortably enough for Traccar alone, more so without a MariaDB add-on alongside it.

Trip detection (substitutes the old WLAN-based logic)

• Start / end trigger: FMM003 ignition state (CAN), not WLAN connectivity.
• Pause-tolerance behavior carries over unchanged from the existing design — this was iterated three times during design and is settled:
  • Ignition never drops during engine start-stop (confirmed technical fact), so no separate hold-time is needed to filter start-stop out — the ignition: 1→0 condition already excludes it.
  • The existing user-configurable pause-tolerance setting (fahrten_pausenzeit_min, today's default 15 min, editable in Settings) is a real, intentional product feature and must be preserved: if the vehicle restarts within that window after a genuine ignition-off, it's one trip, not two.
  • Implementation pattern (unchanged from the current fahrterkennung.py approach, just re-triggered off the FMM003 ignition entity instead of the WLAN sensor): task.unique() cancels a pending task.sleep() if ignition comes back on within the pause window; the trip's recorded end timestamp/odometer is backdated to the actual ignition-off moment, not the timer-expiry moment.
• sensor.iphone_wifi_connection drops out of pyscript/modules/einstellungen.py entirely once this ships.

---

3. Frontend data access: HA REST/WebSocket API, not hass injection

The new app is not a panel_custom element, so it has no injected hass object. Instead:

• Auth: a Home Assistant Long-Lived Access Token (LLAT), generated once per install in the HA user profile. Sufficient for a private single-user install — no need for the full OAuth flow the official Companion App uses.
• Reads: GET /api/states/<entity_id> per entity, or subscribe over HA's WebSocket API for push updates instead of polling.
• Writes: POST /api/services/<domain>/<service> — calling the same pyscript.audi_dashboard_* services the current panel already calls via hass.callService() (e.g. audi_dashboard_profil_schreiben, audi_dashboard_beleg_hochladen). Same backend function, same file written server-side — a receipt upload or a FIN/plate edit from the phone is a real round-trip to the shared dataset, never a local-only change. The phone only caches for offline viewing and holds the token; it is never the source of truth.
• This same REST/WebSocket client is what makes the iframe-in-HA case (§1.3) work identically to the native apps — one data-access layer for all three targets, no hass-injection special-casing needed for the iframe case.

LLAT provisioning (decided)

Primary: manual paste into a one-time setup screen, saved to secure on-device storage (iOS Keychain / Android Keystore, via a Capacitor secure-storage plugin). Always available, no permissions, no extra infrastructure — and the guaranteed fallback if anything about the QR path misbehaves.

Secondary (preferred by the owner, build if it stays simple): QR code scan. The one real objection to QR — that generating it would mean pasting a long-lived token into some third-party online QR generator — is avoidable: generate the QR locally, in a small self-hosted page under HA's /local/, using an offline JS QR library, rendering entirely client-side with no network call. The token then never leaves the local network on its way into the QR. On the app side this needs a Capacitor barcode/camera plugin and the camera permission. Both halves are small and well-trodden; if the implementation turns out to be more than a modest amount of work, ship manual paste alone — it's fully sufficient on its own.

A URL/deep-link bootstrap was considered and rejected: it needs a registered custom URL scheme plus some channel to send yourself the link, which exposes the token in transit at least as much as pasting it, for no gain over the two options above.

Offline behavior (decided)

• The app shows the last cached data when it has no route to HA, with a visible "Offline" marker in the header/title area — never a blank screen or silent staleness.
• All edits made while offline are queued (receipt uploads, profile edits, manual trip/fill-up entries, etc.) and flushed once connectivity returns, rather than rejected outright. Given this is a single-user app, conflict resolution can stay simple (last-write-wins) — there's no concurrent second editor to reconcile against.

---

4. Connectivity: Option B — narrow gateway, chosen over Tailscale-always-on

Decision: Option B. (Option A — making the phone's Tailscale connection always-on instead of triggered by the car's WLAN SSID — was the lower-effort alternative and remains available if this turns out to be worth revisiting, but Option B is what's being built.)

Goal

The app must be able to read and write data from any network the phone is on (cellular, foreign Wi-Fi, home Wi-Fi) — not just when Tailscale happens to be connected — while Home Assistant itself stays exactly as closed/local-only as it is today: no port-forward, no Funnel, HA's own port/UI/login never reachable from the public internet. Only a narrow, purpose-built slice of the API is ever exposed.

Shape (two existing, maintained HA Community Add-ons — not custom code to maintain)

1. Cloudflared add-on — runs cloudflared as an HA add-on. Opens an outbound-only encrypted tunnel from the HAOS host (the OptiPlex) to Cloudflare's edge; no router port ever opens. Confirmed capable of routing multiple public hostnames to multiple local ports/services — so it points at the reverse-proxy add-on's port below, not at HA's own port 8123.
2. Nginx Proxy Manager or Traefik add-on — a path-scoped reverse proxy sitting between the tunnel and HA's internal API, on the Supervisor's internal Docker network. Configured with an allowlist of only the specific paths the companion app needs (e.g. /api/states/sensor.audi_*, /api/services/pyscript/audi_dashboard_* — exact path list still TBD, depends on the final entity/ service names once the FMM003 mapping is built). Everything else — /lovelace, /config, /auth, the HA frontend itself — is blocked at this layer, never reaching the tunnel at all.
3. Auth stays a second, independent layer: every proxied call still requires the same Bearer LLAT HA's REST API already demands. Even a path that slipped through the allowlist would be useless without that token, and any individual LLAT can be revoked from the HA profile if the phone is ever lost.

Why this over Option A

Feels like a normal app to the user — plain HTTPS, no VPN client running on the phone, no "why is my battery draining" VPN-always-on tradeoff. The cost is two add-ons' worth of configuration (tunnel + path allowlist) instead of a single phone setting, and the honest caveat that a narrow, purpose-built surface is now internet-facing (even though HA itself never is) — accepted as worth it for the UX.

Explicitly not chosen

• Tailscale Funnel — ruled out earlier for the raw FMM003→decoder TCP ingress path (port/protocol restrictions), and not adopted for this gateway either, since it would mean quietly reversing the existing "no Funnel" rule; not adopted without that being an explicit, separate decision.
• Direct port-forward — ruled out, contradicts the standing "Home Assistant is never exposed publicly" principle from bauauftrag.md §3, which continues to hold for HA itself under this design.

---

5. Open items (not yet decided)

Deliberately deferred until hardware arrives / the next architecture review — not blocking anything else in this document:

1. Exact reverse-proxy path allowlist — depends on the final pyscript entity/service names once the FMM003 combined-entity mapping is implemented; write these down here once decided.

2. No-hardcoding mapping system for the FMM003 combined entity — discussed in an earlier session, not yet written to a file or finalized in detail.

3. Reverse-proxy add-on: Nginx Proxy Manager vs. Traefik — both viable (§4), pick deferred to the next audit pass. Doesn't depend on the FMM003 — could be set up and tested against HA's existing API before the hardware arrives, if worth doing ahead of time.

4. Cloudflare Tunnel domain — ✅ DECIDED: datametric360.app, being registered fresh at all-inkl for this purpose only (no websites, no mail on it). The tunnel will publish a subdomain of it. Note .app is on the HSTS preload list, so browsers force HTTPS on it unconditionally — which suits a Cloudflare Tunnel (always HTTPS) and removes any chance of an accidental plaintext request.

   The constraint that drove "register a separate domain rather than reuse an existing one":

   Cloudflare Tunnel needs the domain's DNS hosted at Cloudflare — i.e. "Full setup": the domain's nameservers get repointed to Cloudflare, moving all DNS records for that domain (A, MX/email, everything) out of all-inkl's DNS management. The alternative that avoids this — Cloudflare's "partial / CNAME setup", which keeps DNS at the existing provider — is Business-plan-only ($200/month), i.e. not realistic here.

   Therefore: never point this at an existing all-inkl domain carrying live websites or email — hence the dedicated datametric360.app. Nothing about the owner's existing domains/mail is touched.

   Note the all-inkl "Neue Domain anlegen" dialog asks for a target (Webspace / Redirect / Webbaukasten) — that choice is irrelevant here, since DNS gets delegated to Cloudflare afterwards and the all-inkl webspace binding then goes unused. The meaningful step is the nameserver change to Cloudflare, done after registration, not anything in that dialog.

---

6. Explicit non-goals for this piece (carried over from bauauftrag.md)

• Home Assistant's own UI/API is never exposed publicly, under either connectivity option.
• No change to the vehicle being read-only (no remote control) — this app remains a viewer/data-entry tool, same as the existing panel.