bf-telematics¶

What this service is¶

bf-telematics is a provider-integration service that normalizes telemetry from external providers into BetterFleet-friendly data and APIs.

Code anatomy¶

• src/main.py: FastAPI factory.
• src/v2/*: newer API/domain modules (device, vehicle, provider, polling_tasks).
• src/modules/api_provider and src/modules/telematics_snapshot: provider abstraction and snapshot logic.
• src/event_layer/*: subscription/event-driven paths.
• src/db/alembic: persistence and schema migrations.

Architectural characteristics¶

• Explicit provider abstraction and polling architecture.
• Coexistence of legacy/support modules with v2 structure.

Documentation and tests in-repo¶

• Domain docs under docs/ (domain.md, events.md, device_manager.md, adding_provider.md).
• Tests include provider/device/vehicle and polling task coverage under test/v2.

Internal request lifecycle¶

sequenceDiagram
  participant Provider as telematics provider
  participant Poll as polling task
  participant Normalize as provider normalizer
  participant Snapshot as snapshot module
  participant Api as v2 api

  Poll->>Provider: fetch provider payload
  Provider-->>Poll: raw telemetry data
  Poll->>Normalize: standardize payload
  Normalize->>Snapshot: update fleet state snapshot
  Snapshot->>Api: expose normalized view