KwestKarz VIN Capture and Decode Specification - wwestlake/KwestKarz GitHub Wiki

KwestKarz VIN Capture and Decode Specification

This document outlines the flow and design for capturing, decoding, and storing VIN data for vehicles within the KwestKarz platform. The solution supports both desktop/web use and a dedicated mobile app for advanced capture tasks.

๐Ÿงญ Primary Use Cases

Web (Phone or Desktop)

  • Fleet Managers and Helpers use web app to:
    • Enter VIN manually or paste from clipboard
    • Trigger VIN decode lookup
    • Review and confirm decoded data
    • Enter additional metadata (tags, notes)
    • Assign tasks or flag for maintenance

Mobile App (Fleet Owner or Manager)

  • App includes advanced VIN capture via phone camera
  • Scans barcode (Code 39) or OCRs windshield/door tag
  • Allows attaching photos
  • Immediately decodes and registers vehicle
  • Enables task creation and inspection notes on the spot

๐Ÿ“ฆ Data Flow Overview

graph TD;
  A[Scan VIN] --> B[Extract VIN string];
  B --> C[Call NHTSA VIN Decoder];
  C --> D[Parse Make, Model, Year];
  D --> E[Confirm/Create Vehicle Record];
  E --> F[Attach Photos / Notes / Tags];
  F --> G[Assign Tasks or Save];

๐Ÿ” VIN Decoding Service

API Used: NHTSA Vehicle API

Endpoint Example:

GET https://vpic.nhtsa.dot.gov/api/vehicles/decodevinvalues/{VIN}?format=json

Expected Response (Trimmed)

{
  "Results": [
    {
      "Make": "HONDA",
      "Model": "Accord",
      "ModelYear": "2003",
      "VehicleType": "PASSENGER CAR"
    }
  ]
}

๐Ÿ“ฑ Mobile App-Specific Features

  • Barcode scanning via camera (Code 39)
  • Photo upload (stickers, condition, tags)
  • Local validation of VIN format
  • Offline scan queue (optional future feature)
  • Immediate vehicle registration with decoding
  • Optionally assign initial tasks immediately

๐Ÿงพ Stored Data Format

{
  "vin": "1HGCM82633A004352",
  "make": "HONDA",
  "model": "Accord",
  "year": 2003,
  "type": "Passenger Car",
  "photos": ["url1.jpg", "url2.jpg"],
  "notes": "Front fender sticker shows damage history",
  "scannedBy": "[email protected]",
  "scannedAt": "2025-05-02T15:12:00Z"
}

๐Ÿ” Access & Roles

  • FleetManagers can scan, decode, and add vehicles
  • Helpers may view decoded vehicle info but not modify
  • Mobile App feature limited to trusted users

โœ… Benefits

  • Fast onboarding of new vehicles
  • Accurate make/model/year recognition
  • No manual data entry from the field
  • Flexible use: phone-friendly web + app-exclusive capture