Developer notes / Draft
Integration reference.
Draft data models and exchange patterns for automotive diagnostic sessions.
Overview
The integration gateway connects a local diagnostic application to the service platform. Each session has a unique identifier and accumulates events and reports over time.
Core entities
| Entity | Purpose |
|---|---|
session | A single diagnostic session for a vehicle. |
event | An action or ECU readout result. |
attachment | A file, report or session attachment. |
Session lifecycle
The application opens a session, sends events and eventually closes it. Resending an event with the same event_id must not create a duplicate.
Start a session
Record the vehicle identifier, data source and start time.
Send events
ECU scans, fault codes and service operations.
Attach files
Upload attachments linked to the session identifier.
Complete
Save the final status and processing result.
Example event payload
The sample payload illustrates a minimal message structure. Fields may change as the server component is developed.
{
"version": "0.1-draft",
"session_id": "DEMO-2418",
"event_id": "evt-0042",
"type": "dtc.read.completed",
"recorded_at": "2026-10-17T10:44:00Z",
"source": "kk-diag-desktop",
"payload": {
"ecu": "DME",
"fault_count": 2,
"report_ref": "attachment-001"
}
}Event types
| Type | Meaning |
|---|---|
session.started | A diagnostic session has been opened. |
ecu.scan.completed | ECU identification data received. |
dtc.read.completed | Fault code readout completed. |
service.action | A service action was recorded. |
report.ready | An attachment or report is ready. |
Transport and files
An HTTPS API can handle metadata, WebSocket can carry live session updates, and a separate upload mechanism can handle large diagnostic files.
Design considerations
- Unique message IDs and retry-safe delivery.
- File size limits, integrity checks and resumable uploads.
- Queue-based processing of large attachments.
- Independent tracking of delivery and report processing.
Security
A production integration should authenticate every client and verify access to each session. Attachments must be checked for type, size and vehicle association.
Use TLS, rate limits and audit logs. Keep secrets out of client code and issue separate credentials for each workstation.