02-Architecture / 02.02.Tesla-Data-Architecture

02.02.Tesla Data Architecture

02.02. Tesla Data Architecture

Purpose

This document defines the Tesla data architecture for Car Pulse Tracker.

It should be read together with:

• doc/md/bnc-cpt-api.CORE-DATA-ARCHITECTURE.md

This document remains Tesla-specific. The core-data architecture document defines the provider-agnostic target model that Tesla must fit into.

It is not an endpoint catalog. It defines:

1. what is fetched once per order/report request
2. what is fetched per VIN
3. which token type is used
4. the canonical normalized Tesla data shape
5. how reports must be derived without cross-vehicle mixing

Current Problem

Current Tesla report generation is still centered on per-vehicle fetch/build logic.

That is wrong for multi-vehicle accounts because:

• shared datasets such as charging history are handled inside per-vehicle report builds
• cross-vehicle attribution is solved too late
• report builders are still too close to raw Tesla fetches

The main example is charging history:

• Tesla returns charging sessions with their own vin
• current code fetches charging history during _build_vehicle_report(...)
• current code filters later instead of using a normalized vehicle-root structure first

That is not reliable enough for enterprise use.

Source Of Truth

The source-of-truth chain must be:

1. Tesla endpoint responses
2. requestRaw
3. vehiclesByVin
4. derived report model
5. WUI / PDF rendering

Renderers must never solve vehicle attribution.

Fetch Phases

Phase 0: Request Context

Inputs:

• Tesla token set
• selected VINs
• current Fleet API region/base URL

Output:

• requestContext

Phase 1: Request-Level Fetch

Fetch once per order/report request:

• GET /api/1/users/region
• GET /api/1/vehicles
• GET /api/1/dx/charging/history

Purpose:

• determine region/base URL
• obtain the account vehicle set
• obtain one shared charging-history dataset

Phase 2: Vehicle-Root Initialization

Create one root object per VIN:

• vehiclesByVin[vin]

Populate root identity from:

• GET /api/1/vehicles
• optionally GET /api/1/vehicles/{vin}

Phase 3: Per-VIN Enrichment

Fetch per selected VIN:

• GET /api/1/vehicles/{vin}/vehicle_data
• GET /api/1/vehicles/{vin}/recent_alerts
• GET /api/1/vehicles/{vin}/service_data
• GET /api/1/vehicles/{vin}/release_notes
• GET /api/1/dx/vehicles/options?vin={vin}
• GET /api/1/dx/warranty/details?vin={vin}

Conditional:

• GET /api/1/vehicles/{vin}/specs only when a partner token is available

Phase 4: Normalization

Normalize raw Tesla payloads into:

• requestRaw
• vehiclesByVin

This is the only phase where:

• shared charging history is partitioned by VIN
• empty vs error vs not-fetched is resolved
• raw endpoint wrappers are normalized into stable internal shapes

Phase 5: Derived Product Data

Build:

• report view model
• PDF view model
• invoice summary model
• raw debug view

These must all derive from vehiclesByVin, not from live Tesla calls.

Token Rules

Third-Party Token

Use for current customer-authorized flows.

Use for:

• users/region
• vehicles
• vehicles/{vin}
• vehicle_data
• recent_alerts
• service_data
• release_notes
• options
• warranty_details
• charging_history
• charging_invoice

Partner Token

Use where Tesla explicitly requires it.

Current known case:

• GET /api/1/vehicles/{vin}/specs

Third-Party Business Token

Future fleet mode only.

Relevant Tesla endpoint:

• GET /api/1/dx/charging/sessions

Canonical Normalized Shape

{
  "requestContext": {
    "tokenType": "third_party",
    "fleetApiBaseUrl": "https://fleet-api.prd.eu.vn.cloud.tesla.com",
    "selectedVins": [
      "LRW3E7EK1RC988948"
    ],
    "fetchedAt": "2026-03-07T18:00:00Z"
  },
  "requestRaw": {
    "userRegion": {},
    "vehicles": {},
    "chargingHistory": {}
  },
  "vehiclesByVin": {
    "LRW3E7EK1RC988948": {
      "vehicle": {},
      "vehicleData": {},
      "recentAlerts": [],
      "serviceData": {},
      "releaseNotes": [],
      "options": {},
      "warrantyDetails": {},
      "vehicleSpecs": {},
      "chargingHistory": []
    }
  }
}

Core Rules

1. VIN is the master root key.
2. Shared charging history is fetched once and partitioned once.
3. vehicle_data is enrichment, not root identity.
4. Raw Tesla payloads are preserved in requestRaw.
5. Reports are derived only from vehiclesByVin.
6. Invoice metadata stays attached to charging sessions for the same VIN.
7. Invoice exports must contain only invoice files for the requested VIN.
8. The main vehicle PDF may expose charging totals and invoice availability, but invoice PDFs remain separate artifacts.

Charging History Rule

Charging sessions already carry their own vin.

So the correct rule is:

1. fetch full charging history once
2. iterate all returned sessions
3. append each session to vehiclesByVin[session.vin].chargingHistory

The wrong rule is:

• fetch charging history inside _build_vehicle_report(...)
• then solve ownership with a late filter there

That late filter can remain as a sanity guard, but it must not be the architecture.

Current-To-Target Change

Current

• generate_reports() loops selected vehicles
• _build_vehicle_report() fetches Tesla modules per vehicle
• charging history is fetched there
• report object is assembled there

Target

1. fetch Tesla data before report building
2. normalize Tesla data before report building
3. build reports from normalized per-VIN objects

Meaning:

• _build_vehicle_report() should stop being a Tesla fetch function
• it should become a transformation from normalized vehicle data to report data

Acceptance Criteria

The architecture change is complete only when all are true:

1. charging history is fetched once per order/report request, not once per report build
2. every selected VIN produces exactly one vehiclesByVin[vin] root
3. options uses GET /api/1/dx/vehicles/options?vin={vin}
4. specs is fetched only through a partner-token path or is explicitly absent
5. service_data empty responses remain non-breaking
6. reports and PDFs are built from normalized vehicle-root data only
7. no cross-vehicle charging or invoice contamination is possible

Decision

For Tesla integration:

• first build one normalized Tesla request aggregate
• then build one VIN-root object per vehicle
• then derive reports from those VIN-root objects

No further report expansion should depend on the old per-vehicle fetch/build architecture.