backend/src/features/vehicles/README.md

@@ -12,6 +12,9 @@ Primary entity for vehicle management consuming MVP Platform Vehicles Service. H
 - `PUT /api/vehicles/:id` - Update vehicle details
 - `DELETE /api/vehicles/:id` - Soft delete vehicle
 
+### VIN Decoding (Pro/Enterprise Only)
+- `POST /api/vehicles/decode-vin` - Decode VIN using NHTSA vPIC API
+
 ### Hierarchical Vehicle Dropdowns
 **Status**: Vehicles service now proxies the platform vehicle catalog to provide fully dynamic dropdowns. Each selection step filters the next list, ensuring only valid combinations are shown.
 
@@ -100,6 +103,12 @@ vehicles/
 │   └── name-normalizer.ts
 ├── data/                  # Database layer
 │   └── vehicles.repository.ts
+├── external/              # External service integrations
+│   ├── CLAUDE.md          # Integration pattern docs
+│   └── nhtsa/             # NHTSA vPIC API client
+│       ├── nhtsa.client.ts
+│       ├── nhtsa.types.ts
+│       └── index.ts
 ├── migrations/            # Feature schema
 │   └── 001_create_vehicles_tables.sql
 ├── tests/                 # All tests
@@ -112,11 +121,45 @@ vehicles/
 
 ## Key Features
 
-### 🔍 Automatic VIN Decoding
-- **Platform Service**: MVP Platform Vehicles Service VIN decode endpoint
-- **Caching**: Platform service handles caching strategy
-- **Fallback**: Circuit breaker pattern with graceful degradation
-- **Validation**: 17-character VIN format validation
+### 🔍 VIN Decoding (NHTSA vPIC API)
+- **Tier Gating**: Pro and Enterprise users only (`vehicle.vinDecode` feature key)
+- **NHTSA API**: Calls official NHTSA vPIC API for authoritative vehicle data
+- **Caching**: Results cached in `vin_cache` table (1-year TTL, VIN data is static)
+- **Validation**: 17-character VIN format, excludes I/O/Q characters
+- **Matching**: Case-insensitive exact match against dropdown options
+- **Confidence Levels**: High (exact match), Medium (normalized match), None (hint only)
+- **Timeout**: 5-second timeout for NHTSA API calls
+
+#### Decode VIN Request
+```json
+POST /api/vehicles/decode-vin
+Authorization: Bearer <jwt>
+{
+  "vin": "1HGBH41JXMN109186"
+}
+
+Response (200):
+{
+  "year": { "value": 2021, "nhtsaValue": "2021", "confidence": "high" },
+  "make": { "value": "Honda", "nhtsaValue": "HONDA", "confidence": "high" },
+  "model": { "value": "Civic", "nhtsaValue": "Civic", "confidence": "high" },
+  "trimLevel": { "value": "EX", "nhtsaValue": "EX", "confidence": "high" },
+  "engine": { "value": null, "nhtsaValue": "2.0L L4 DOHC 16V", "confidence": "none" },
+  "transmission": { "value": null, "nhtsaValue": "CVT", "confidence": "none" },
+  "bodyType": { "value": null, "nhtsaValue": "Sedan", "confidence": "none" },
+  "driveType": { "value": null, "nhtsaValue": "FWD", "confidence": "none" },
+  "fuelType": { "value": null, "nhtsaValue": "Gasoline", "confidence": "none" }
+}
+
+Error (400 - Invalid VIN):
+{ "error": "INVALID_VIN", "message": "Invalid VIN format. VIN must be..." }
+
+Error (403 - Tier Required):
+{ "error": "TIER_REQUIRED", "requiredTier": "pro", "currentTier": "free", ... }
+
+Error (502 - NHTSA Failure):
+{ "error": "VIN_DECODE_FAILED", "message": "Unable to decode VIN from external service" }
+```
 
 ### 📋 Hierarchical Vehicle Dropdowns
 - **Platform Service**: Consumes year-based hierarchical vehicle API