motovaultpro/backend/src/features/platform

Platform Feature Capsule

Quick Summary (50 tokens)

Extensible platform service for vehicle hierarchical data lookups and VIN decoding. Replaces Python FastAPI platform service. PostgreSQL-first with vPIC fallback, Redis caching (6hr vehicle data, 7-day VIN), circuit breaker pattern for resilience.

API Endpoints

Vehicle Hierarchical Data

• GET /api/platform/years - Get available model years (distinct, descending)
• GET /api/platform/makes?year={year} - Get makes for specific year
• GET /api/platform/models?year={year}&make_id={id} - Get models for year and make
• GET /api/platform/trims?year={year}&model_id={id} - Get trims for year and model
• GET /api/platform/engines?year={year}&model_id={id}&trim_id={id} - Get engines for trim

VIN Decoding

• GET /api/platform/vehicle?vin={vin} - Decode VIN to vehicle details

Authentication

• All platform endpoints require valid JWT (Auth0)

Request/Response Examples

Get Years

GET /api/platform/years

Response (200):
[2024, 2023, 2022, 2021, ...]

Get Makes for Year

GET /api/platform/makes?year=2024

Response (200):
{
  "makes": [
    {"id": 1, "name": "Honda"},
    {"id": 2, "name": "Toyota"},
    {"id": 3, "name": "Ford"}
  ]
}

Get Models for Make/Year

GET /api/platform/models?year=2024&make_id=1

Response (200):
{
  "models": [
    {"id": 101, "name": "Civic"},
    {"id": 102, "name": "Accord"},
    {"id": 103, "name": "CR-V"}
  ]
}

Decode VIN

GET /api/platform/vehicle?vin=1HGCM82633A123456

Response (200):
{
  "vin": "1HGCM82633A123456",
  "success": true,
  "result": {
    "make": "Honda",
    "model": "Accord",
    "year": 2003,
    "trim_name": "LX",
    "engine_description": "2.4L I4",
    "transmission_description": "5-Speed Automatic",
    "horsepower": 160,
    "torque": 161,
    "top_speed": null,
    "fuel": "Gasoline",
    "confidence_score": 0.95,
    "vehicle_type": "Passenger Car"
  }
}

VIN Decode Error

GET /api/platform/vehicle?vin=INVALID

Response (400):
{
  "vin": "INVALID",
  "success": false,
  "result": null,
  "error": "VIN must be exactly 17 characters"
}

Feature Architecture

Complete Self-Contained Structure

platform/
├── README.md              # This file
├── index.ts               # Public API exports
├── api/                   # HTTP layer
│   ├── platform.controller.ts
│   └── platform.routes.ts
├── domain/                # Business logic
│   ├── vehicle-data.service.ts
│   ├── vin-decode.service.ts
│   └── platform-cache.service.ts
├── data/                  # Database and external APIs
│   ├── vehicle-data.repository.ts
│   └── vpic-client.ts
├── models/                # DTOs
│   ├── requests.ts
│   └── responses.ts
├── tests/                 # All tests
│   ├── unit/
│   └── integration/
└── docs/                  # Additional docs

Key Features

VIN Decoding Strategy

1. Cache First: Check Redis (7-day TTL for success, 1-hour for failures)
2. PostgreSQL: Use vehicles.f_decode_vin() function for high-confidence decode
3. vPIC Fallback: NHTSA vPIC API via circuit breaker (5s timeout, 50% error threshold)
4. Graceful Degradation: Return meaningful errors when all sources fail

Circuit Breaker Pattern

• Library: opossum
• Timeout: 6 seconds
• Error Threshold: 50%
• Reset Timeout: 30 seconds
• Monitoring: Logs state transitions (open/half-open/close)

Hierarchical Vehicle Data

• PostgreSQL Queries: Normalized schema (vehicles.make, vehicles.model, etc.)
• Caching: 6-hour TTL for all dropdown data
• Performance: < 100ms response times via caching
• Validation: Year (1950-2100), positive integer IDs

Database Schema

• Uses Existing Schema: vehicles schema in PostgreSQL
• Tables: make, model, model_year, trim, engine, trim_engine
• Function: vehicles.f_decode_vin(vin text) for VIN decoding
• No Migrations: Uses existing platform database structure

Caching Strategy

Vehicle Data (6 hours)

• Keys: mvp:platform:vehicle-data:{type}:{params}
• Examples:
  • mvp:platform:years
  • mvp:platform:vehicle-data:makes:2024
  • mvp:platform:vehicle-data:models:2024:1
• TTL: 21600 seconds (6 hours)
• Invalidation: Natural expiration via TTL

VIN Decode (7 days success, 1 hour failure)

• Keys: mvp:platform:vin-decode:{VIN}
• Examples: mvp:platform:vin-decode:1HGCM82633A123456
• TTL: 604800 seconds (7 days) for success, 3600 seconds (1 hour) for failures
• Invalidation: Natural expiration via TTL

Business Rules

VIN Validation

• Must be exactly 17 characters
• Cannot contain letters I, O, or Q
• Must be alphanumeric
• Auto-uppercase normalization

Query Parameter Validation

• Year: Integer between 1950 and 2100
• IDs: Positive integers (make_id, model_id, trim_id)
• VIN: 17 alphanumeric characters (no I, O, Q)

Dependencies

Internal Core Services

• core/config/database - PostgreSQL pool
• core/config/redis - Redis cache service
• core/auth - JWT authentication middleware
• core/logging - Winston structured logging

External APIs

• NHTSA vPIC: https://vpic.nhtsa.dot.gov/api
  • VIN decoding fallback
  • 5-second timeout
  • Circuit breaker protected
  • Free public API

Database Schema

• vehicles.make - Vehicle manufacturers
• vehicles.model - Vehicle models
• vehicles.model_year - Year-specific models
• vehicles.trim - Model trims
• vehicles.engine - Engine configurations
• vehicles.trim_engine - Trim-engine relationships
• vehicles.f_decode_vin(text) - VIN decode function

NPM Packages

• opossum - Circuit breaker implementation
• axios - HTTP client for vPIC API
• zod - Request validation schemas

Performance Optimizations

Caching Strategy

• 6-hour TTL: Vehicle data rarely changes
• 7-day TTL: VIN decode results are immutable
• 1-hour TTL: Failed VIN decode (prevent repeated failures)
• Cache Prefix: mvp:platform: for isolation

Circuit Breaker

• Prevents cascading failures to vPIC API
• 30-second cooldown after opening
• Automatic recovery via half-open state
• Detailed logging for monitoring

Database Optimization

• Uses existing indexes on vehicles schema
• Prepared statements via node-postgres
• Connection pooling (max 10 connections)

Error Handling

Client Errors (4xx)

• 400 - Invalid VIN format, validation errors
• 401 - Missing or invalid JWT token
• 404 - VIN not found in database or API
• 503 - vPIC API unavailable (circuit breaker open)

Server Errors (5xx)

• 500 - Database errors, unexpected failures
• Graceful degradation when external APIs unavailable
• Detailed logging without exposing internal details

Error Response Format

{
  "vin": "1HGCM82633A123456",
  "success": false,
  "result": null,
  "error": "VIN not found in database and external API unavailable"
}

Extensibility Design

Future Lookup Types

The platform feature is designed to accommodate additional lookup types beyond vehicle data:

Current: Vehicle hierarchical data, VIN decoding Future Examples:

• Part number lookups
• Service bulletins
• Recall information
• Maintenance schedules
• Tire specifications
• Paint codes

Extension Pattern

1. Create new service in domain/ (e.g., part-lookup.service.ts)
2. Add repository in data/ if database queries needed
3. Add external client in data/ if API integration needed
4. Add routes in api/platform.routes.ts
5. Add validation schemas in models/requests.ts
6. Add response types in models/responses.ts
7. Update controller with new methods

Testing

Unit Tests

• vehicle-data.service.test.ts - Business logic with mocked dependencies
• vin-decode.service.test.ts - VIN decode logic with mocked API
• vpic-client.test.ts - vPIC client with mocked HTTP
• platform-cache.service.test.ts - Cache operations

Integration Tests

• platform.integration.test.ts - Complete API workflow with test database

Run Tests

# All platform tests
npm test -- features/platform

# Unit tests only
npm test -- features/platform/tests/unit

# Integration tests only  
npm test -- features/platform/tests/integration

# With coverage
npm test -- features/platform --coverage

Migration from Python Service

What Changed

• Language: Python FastAPI -> TypeScript Fastify
• Feature Name: "vehicles" -> "platform" (extensibility)
• API Routes: /vehicles/* -> /api/platform/*
• VIN Decode: Kept and migrated (PostgreSQL + vPIC fallback)
• Caching: Redis implementation adapted to TypeScript
• Circuit Breaker: Python timeout -> opossum circuit breaker

What Stayed the Same

• Database schema (vehicles.*)
• Cache TTLs (6hr vehicle data, 7-day VIN)
• VIN validation logic
• Hierarchical query structure
• Response formats

Deprecation Plan

1. Deploy TypeScript platform feature
2. Update frontend to use /api/platform/* endpoints
3. Monitor traffic to Python service
4. Deprecate Python service when traffic drops to zero
5. Remove Python container from docker-compose

Development Commands

# Start environment
make start

# View feature logs
make logs-backend | grep platform

# Open container shell
make shell-backend

# Inside container - run feature tests
npm test -- features/platform

# Type check
npm run type-check

# Lint
npm run lint

Future Considerations

Potential Enhancements

• Batch VIN decode endpoint (decode multiple VINs)
• Admin endpoint to invalidate cache patterns
• VIN decode history tracking
• Alternative VIN decode APIs (CarMD, Edmunds)
• Real-time vehicle data updates
• Part number cross-reference lookups
• Service bulletin integration
• Recall information integration

Performance Monitoring

• Track cache hit rates
• Monitor circuit breaker state
• Log slow queries (> 200ms)
• Alert on high error rates
• Dashboard for vPIC API health

Related Features

Vehicles Feature

• Path: backend/src/features/vehicles/
• Relationship: Consumes platform VIN decode endpoint
• Integration: Uses /api/platform/vehicle?vin={vin} for VIN decode

Frontend Integration

• Dropdown Components: Use hierarchical vehicle data endpoints
• VIN Scanner: Use VIN decode endpoint for auto-population
• Vehicle Forms: Leverage platform data for validation

---

Platform Feature: Extensible foundation for vehicle data and future platform capabilities. Production-ready with PostgreSQL, Redis caching, circuit breaker resilience, and comprehensive error handling.