Core DVIR Architecture & FMCSA Compliance

The Driver Vehicle Inspection Report (DVIR) is the operational and regulatory anchor of every commercial motor vehicle safety program. Migrating the DVIR from a static paper artifact into a structured, automated data pipeline is not an operational convenience — it is a compliance obligation enforced under 49 CFR § 396.11 and § 396.13. A production-grade DVIR architecture must reconcile federal mandates with real-world fleet constraints, guaranteeing that every inspection event produces an immutable, cryptographically verifiable, fully auditable record. This guide establishes the reference architecture for engineering, validating, and scaling DVIR processing on FMCSA terms: driver authentication at ingestion, deterministic defect classification, gated state transitions, offline resilience, and Write-Once-Read-Many (WORM) retention. Downstream systems — the DVIR Ingestion & Parsing Workflows pipeline that feeds this architecture and the Defect Classification & Repair Routing engine that consumes it — all depend on the invariants defined here.

Every DVIR system exists to satisfy a specific federal mandate, and the enforcement of that mandate cannot be deferred to configurable business rules. Under 49 CFR § 396.11(a), a driver must prepare a written report at the completion of each day’s work on every vehicle operated, covering at minimum the service brakes, parking brake, steering mechanism, lighting devices and reflectors, tires, horn, windshield wipers, rear-vision mirrors, coupling devices, wheels and rims, and emergency equipment. Under § 396.11(a)(3), any defect that would affect the safety of operation or result in a mechanical breakdown must be documented. Under § 396.11©(2), the motor carrier must certify that the listed defect was repaired — or that repair was unnecessary — before the vehicle is dispatched again. Under § 396.11©(2)(iii), the driver of the next tour must review that certification and sign the prior report.

These clauses translate directly into system-level invariants that a compliant architecture must encode, not merely encourage. The ingestion layer must enforce driver authentication tied to a verifiable credential (typically an ELD-linked identity), precise vehicle identification (VIN and unit ID), UTC-timestamped event capture, and explicit defect acknowledgment before any record can transition to a finalized state. A payload missing a certification signature is not a warning condition — reject the payload at the API boundary and return it to the driver’s client for correction. The FMCSA DVIR Rule 396.11 Breakdown maps each sub-clause to its corresponding mandatory data capture point, signature workflow, and repair-certification gate, and is the authoritative reference for the regulatory obligations this architecture implements.

The consequence of getting this wrong is measured in CSA points and out-of-service orders. A missing or falsified DVIR is a Vehicle Maintenance BASIC violation that raises a carrier’s Safety Measurement System percentile and increases roadside inspection frequency. Treating § 396.11 as an architectural constraint — a set of gates the data physically cannot bypass — is the only reliable defense during a DOT audit.

The DVIR lifecycle is a directed state machine, not a CRUD form. An inspection enters at the ingestion boundary, passes an authentication and schema gate, is normalized into a canonical representation, is classified against a deterministic defect taxonomy, and — depending on severity — either routes to an out-of-service (OOS) hold or to a scheduled maintenance queue. Every transition is appended to an immutable audit log. The diagram below shows the full path a DVIR record travels, and the enforcement points where a non-compliant payload is rejected rather than allowed to progress.

The critical design principle is that state transitions are gated, not implicit. A record cannot reach the RETURNED_TO_SERVICE state without a repair certification event that references the specific defect code. A record cannot reach the FINALIZED state without both the driver signature (§ 396.11(a)) and, where a defect was reported, the mechanic certification (§ 396.11©(2)). The gating logic is enforced in code, backed by database constraints, and mirrored in the append-only audit ledger so that no transition can occur out of band.

Fleet ecosystems span heterogeneous stacks: native mobile inspection apps, telematics gateways, computerized maintenance management systems (CMMS), and legacy scanned paper. A rigid, version-controlled schema eliminates parsing ambiguity and prevents downstream reconciliation failures. The canonical model below is expressed as a Pydantic v2 schema so it can serve simultaneously as the API validation contract, the serialization format, and the source of truth for JSON Schema generation. The full field-level treatment, enumerations, and migration strategy live in the Standardized DVIR JSON Schema Design guide; the model here is the minimum a compliant ingestion boundary must enforce.

from __future__ import annotations

from datetime import datetime
from enum import Enum
from uuid import UUID

from pydantic import BaseModel, Field, field_validator


class DefectSeverity(str, Enum):
    # Aligns with DOT Out-of-Service criteria; see Deterministic Defect Classification.
    CRITICAL = "critical"   # score 70-100: OOS condition, immobilize before dispatch
    MAJOR = "major"         # score 35-69: repair within regulated window
    MINOR = "minor"         # score 0-34: schedule at next maintenance interval
    NONE = "none"


class InspectionType(str, Enum):
    PRE_TRIP = "pre_trip"
    POST_TRIP = "post_trip"   # § 396.11(a): required at completion of each day's work


class DefectItem(BaseModel):
    component_code: str = Field(..., description="SAE J1939 SPN or internal taxonomy code")
    description: str = Field(..., max_length=512)
    severity: DefectSeverity
    affects_safe_operation: bool  # § 396.11(a)(3): drives OOS routing
    repaired: bool = False
    repair_unnecessary: bool = False  # § 396.11(c)(2): carrier may certify no repair needed


class DVIR(BaseModel):
    dvir_id: UUID = Field(..., description="Client-generated UUIDv4 idempotency key")
    vin: str = Field(..., min_length=17, max_length=17)
    unit_id: str
    driver_id: str = Field(..., description="ELD-linked, authenticated identity")
    inspection_type: InspectionType
    inspected_at: datetime = Field(..., description="UTC; timezone-aware required")
    odometer_km: float = Field(..., ge=0)
    defects: list[DefectItem] = Field(default_factory=list)
    driver_signature: str = Field(..., description="§ 396.11(a) certification")
    mechanic_certification: str | None = None  # required iff any defect present
    payload_sha256: str = Field(..., description="Evidentiary hash of raw submission")

    @field_validator("inspected_at")
    @classmethod
    def must_be_tz_aware(cls, v: datetime) -> datetime:
        if v.tzinfo is None:
            raise ValueError("inspected_at must be timezone-aware (UTC)")
        return v

    @field_validator("vin")
    @classmethod
    def vin_alphanumeric(cls, v: str) -> str:
        if not v.isalnum() or "I" in v or "O" in v or "Q" in v:
            raise ValueError("VIN must be 17 alphanumeric chars excluding I, O, Q")
        return v

The schema enforces three compliance guarantees at the boundary: timezone-aware timestamps (so audit timelines are unambiguous across jurisdictions), a structurally valid 17-character VIN (rejecting the I/O/Q characters the standard forbids), and a mandatory evidentiary hash. Enforcing this contract inside CI with generated JSON Schema — and running it as a contract test across every producer and consumer — guarantees backward compatibility during migrations and prevents malformed payloads from ever reaching the compliance database.

The ingestion service is where regulatory invariants become executable code. Its single responsibility is to admit only records that can legally exist and to reject everything else deterministically. The pattern below validates the payload, enforces the cross-field rule that a reported defect requires a mechanic certification (§ 396.11©(2)), verifies the evidentiary hash, and only then hands the record to the classification stage. A record that fails any check never enters the processing queue.

import hashlib
import json
from pydantic import ValidationError


class ComplianceRejection(Exception):
    """Raised when a payload cannot legally be admitted. Never swallowed."""


def verify_payload_hash(raw: bytes, claimed_sha256: str) -> None:
    computed = hashlib.sha256(raw).hexdigest()
    if computed != claimed_sha256:
        # Tamper-evidence: the submitted hash must match the raw bytes exactly.
        raise ComplianceRejection(f"hash mismatch: {computed} != {claimed_sha256}")


def admit_dvir(raw: bytes) -> DVIR:
    verify_payload_hash(raw, json.loads(raw)["payload_sha256"])
    try:
        record = DVIR.model_validate_json(raw)
    except ValidationError as exc:
        # Reject at the boundary; return structured errors to the client.
        raise ComplianceRejection(f"schema violation: {exc.errors()}") from exc

    reported = [d for d in record.defects if d.severity is not DefectSeverity.NONE]
    if reported and record.mechanic_certification is None:
        # § 396.11(c)(2): a reported defect cannot be finalized without certification.
        raise ComplianceRejection("reported defect requires mechanic certification")

    unresolved = [
        d for d in reported
        if not (d.repaired or d.repair_unnecessary)
    ]
    if unresolved and record.inspection_type is InspectionType.PRE_TRIP:
        # Do not dispatch: § 396.11(c)(2) certification gate is unmet.
        raise ComplianceRejection("pre-trip DVIR has unresolved safety defects")

    return record

This gate is deliberately intolerant. There is no “best effort” admission and no partial acceptance: either the record satisfies every invariant or it is rejected with a machine-readable reason. Once admitted, the record is enriched with metadata and enqueued for classification. Free-text driver notes are never interpreted heuristically at this stage — component references are resolved against the standardized taxonomy described in Defect Taxonomy Mapping for Heavy Trucks, which keeps classification deterministic and auditable.

A DVIR’s raw observations carry compliance weight only when classification is guaranteed and reproducible. FMCSA regulations draw a hard line between safety-critical defects — those that invoke the DOT Out-of-Service Criteria — and non-critical deficiencies. Mapping a driver-reported condition to that line demands deterministic, rule-based logic, never free-text NLP inference whose output cannot be defended in an audit. Classification assigns each defect a severity score on a fixed 0–100 scale, and the score bands map directly to compliance actions:

These bands and thresholds are the same values used throughout the site, including the Severity Scoring Algorithms for DVIR Defects reference — reproducing them consistently is what lets a compliance officer reconcile a score to an action without ambiguity. The classification engine maps each defect’s component criticality, the affects_safe_operation flag, and historical failure context to a band, and a critical result immediately triggers the Critical vs Non-Critical Routing Logic workflow that generates the OOS hold. Because fleet compositions differ, static cut-points are refined per vehicle class through Dynamic Threshold Tuning for Fleet Types, but the band boundaries themselves remain fixed so that the meaning of a score never drifts.

Once a record is standardized and classified, the architecture must enforce the boundaries that prevent unauthorized state transitions across distributed services. Stateful DVIR workflows require explicit gating: a repair certification event may only be applied to a record currently in the AWAITING_REPAIR state, and only by an identity holding the mechanic.certify role. The Compliance Boundary Enforcement in Cloud Workflows guide details the idempotent event processing, role-based access control (RBAC), and cryptographic chaining that make these boundaries auditable; the invariant model below is the contract every service must honor.

from enum import Enum


class DVIRState(str, Enum):
    RECEIVED = "received"
    CLASSIFIED = "classified"
    AWAITING_REPAIR = "awaiting_repair"
    OOS_HOLD = "oos_hold"
    RETURNED_TO_SERVICE = "returned_to_service"
    FINALIZED = "finalized"


# Only these transitions are legal. Anything else is a hard rejection.
ALLOWED: dict[DVIRState, set[DVIRState]] = {
    DVIRState.RECEIVED: {DVIRState.CLASSIFIED},
    DVIRState.CLASSIFIED: {DVIRState.AWAITING_REPAIR, DVIRState.OOS_HOLD, DVIRState.FINALIZED},
    DVIRState.AWAITING_REPAIR: {DVIRState.RETURNED_TO_SERVICE, DVIRState.OOS_HOLD},
    DVIRState.OOS_HOLD: {DVIRState.RETURNED_TO_SERVICE},
    DVIRState.RETURNED_TO_SERVICE: {DVIRState.FINALIZED},
    DVIRState.FINALIZED: set(),  # terminal, append-only
}


def transition(current: DVIRState, target: DVIRState, actor_roles: set[str]) -> DVIRState:
    if target not in ALLOWED[current]:
        raise ComplianceRejection(f"illegal transition {current} -> {target}")
    if target in {DVIRState.RETURNED_TO_SERVICE} and "mechanic.certify" not in actor_roles:
        # § 396.11(c)(2): only a certifying role may return a unit to service.
        raise ComplianceRejection("return-to-service requires mechanic.certify role")
    return target

Every accepted transition emits a structured audit event containing the prior state, the new state, the acting identity, the roles asserted, and a SHA-256 hash chained to the previous event. Any deviation from the mandated workflow results in a hard rejection, and the exception is logged for compliance-officer review rather than silently absorbed. This is what converts an abstract regulation into a boundary the data physically cannot cross.

Commercial fleets routinely operate in cellular dead zones, so a resilient DVIR architecture must tolerate connectivity loss without ever compromising data integrity. Mobile clients write inspections to encrypted local storage and drain a queue with bounded retry and exponential backoff on reconnection. The server side must be idempotent by construction: because every record carries a client-generated dvir_id (UUIDv4), a duplicate submission during a retry storm is a no-op, not a second compliance record.

def ingest_idempotent(record: DVIR, store) -> str:
    # The dvir_id is the idempotency key. Re-submission returns the existing id.
    existing = store.get(record.dvir_id)
    if existing is not None:
        if existing.payload_sha256 != record.payload_sha256:
            # Same id, different content: reject as a tamper/replay anomaly.
            raise ComplianceRejection(f"idempotency conflict on {record.dvir_id}")
        return str(record.dvir_id)  # already stored; safe no-op
    store.put(record.dvir_id, record)
    return str(record.dvir_id)

Three failure modes recur in production and must be handled explicitly. First, timestamp drift: an offline device’s clock may be skewed, so the server records both the client inspected_at and a server-side receipt time, and reconciliation flags records whose skew exceeds a defined tolerance rather than trusting either blindly. Second, duplicate defect submission: the idempotency key above collapses replays, but reconciliation must still detect the same physical defect reported under two dvir_ids across a connectivity gap. Third, schema drift on old clients: a client running a prior schema version is admitted only if its payload validates against a supported version range, and is otherwise rejected with an upgrade directive. The batching and backpressure behavior for reconnection surges is covered in Async Batching for High-Volume Ingestion; the normalization that resolves vendor-specific field names on reconnection is covered in Automated Field Mapping & Data Normalization.

DOT audits demand rapid, verifiable access to historical inspection records, and the architecture must guarantee immutability, tamper-evidence, and precise retention scheduling. Under 49 CFR § 396.11©(2)(iii), the original signed report and the certification of repair must be retained for at least three months from the date the report was prepared. Compliant systems store the canonical record in WORM storage — AWS S3 Object Lock in Compliance mode or Azure Immutable Blob — with a SHA-256 digest of the raw payload recorded at ingestion so that any post-hoc alteration is provably detectable.

import hashlib
from datetime import datetime, timedelta, timezone

RETENTION_MINIMUM = timedelta(days=92)  # § 396.11(c)(2)(iii): >= 3 months


def audit_record(record: DVIR) -> dict:
    prepared = record.inspected_at
    return {
        "dvir_id": str(record.dvir_id),
        "vin": record.vin,
        "prepared_at": prepared.isoformat(),
        "retain_until": (prepared + RETENTION_MINIMUM).isoformat(),
        "payload_sha256": record.payload_sha256,
        "worm_locked": True,
    }


def verify_chain(prev_hash: str, event: dict) -> str:
    # Append-only ledger: each event hashes the prior hash + its own payload.
    body = prev_hash + repr(sorted(event.items()))
    return hashlib.sha256(body.encode()).hexdigest()

Retention policies must honor the federal minimum while accommodating jurisdictional or contractual overrides that require longer holds, and expired records are archived or purged only through the same append-only ledger so that the act of disposal is itself auditable. The practical audit-access pattern is a query over the WORM store keyed by VIN and date range, returning the signed record, its certification event, and the unbroken hash chain proving the record was never altered.

By treating each regulatory clause as an architectural constraint rather than an afterthought, fleet operators and engineering teams deploy DVIR pipelines that scale securely, validate deterministically, and withstand rigorous DOT scrutiny.

• FMCSA DVIR Rule 396.11 Breakdown — clause-by-clause mapping of the federal mandate to system requirements.
• Standardized DVIR JSON Schema Design — the canonical field-level schema and migration strategy.
• Defect Taxonomy Mapping for Heavy Trucks — component hierarchies and standardized defect codes.
• Compliance Boundary Enforcement in Cloud Workflows — idempotent events, RBAC, and cryptographic audit chaining.
• Defect Classification & Repair Routing — how classified defects become routed, tracked repair orders.

This guide is the top-level reference for DVIR architecture on this site. Back to Fleet Compliance home.