motovaultpro/backend/src/features/platform

Platform Feature Capsule

Quick Summary (50 tokens)

Extensible platform service for vehicle hierarchical data lookups. Replaces Python FastAPI platform service. PostgreSQL-first with Redis caching (6hr vehicle data). VIN decoding is planned but not yet implemented.

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 (Planned/Future - Not Yet Implemented)

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

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 (Planned/Future)

The following endpoint is planned but not yet implemented:

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

Planned 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"
  }
}

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    # Hierarchical vehicle lookups
│   └── platform-cache.service.ts  # Redis caching layer
├── data/                  # Database layer
│   └── vehicle-data.repository.ts
├── models/                # DTOs
│   ├── requests.ts
│   └── responses.ts
├── migrations/            # Database schema
│   └── 001_create_vehicle_lookup_schema.sql
├── tests/                 # All tests
│   ├── unit/
│   │   └── vehicle-data.service.test.ts
│   └── integration/
│       └── platform.integration.test.ts
└── docs/                  # Additional docs

Key Features

Hierarchical Vehicle Data (Implemented)

• PostgreSQL Queries: Uses vehicle_options table for hierarchical lookups
• Caching: 6-hour TTL for all dropdown data via Redis
• Performance: < 100ms response times via caching
• Validation: Year (1950-2100), string-based parameters
• Endpoints: years, makes, models, trims, engines, transmissions

VIN Decoding Strategy (Planned/Future)

When implemented, VIN decoding will use:

1. Cache First: Check Redis (7-day TTL for success, 1-hour for failures)
2. PostgreSQL: Database function for high-confidence decode
3. vPIC Fallback: NHTSA vPIC API with circuit breaker protection
4. Graceful Degradation: Return meaningful errors when all sources fail

Database Schema

• Uses Existing Schema: vehicles schema in PostgreSQL
• Tables: vehicle_options table for hierarchical lookups
• Migrations: 001_create_vehicle_lookup_schema.sql

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 Caching (Planned/Future)

When VIN decoding is implemented:

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

Business Rules

Query Parameter Validation

• Year: Integer between 1950 and 2100
• Make/Model/Trim: String-based parameters (not IDs)

VIN Validation (Planned/Future)

When VIN decoding is implemented:

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

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 (Planned/Future)

When VIN decoding is implemented:

• NHTSA vPIC: https://vpic.nhtsa.dot.gov/api (VIN decoding fallback)

Database Tables

• vehicle_options - Hierarchical vehicle data (years, makes, models, trims, engines, transmissions)

NPM Packages

• zod - Request validation schemas

Performance Optimizations

Caching Strategy

• 6-hour TTL: Vehicle hierarchical data (rarely changes)
• Cache Prefix: mvp:platform: for isolation

Database Optimization

• Prepared statements via node-postgres
• Connection pooling via backend pool

Error Handling

Client Errors (4xx)

• 400 - Validation errors (invalid year, missing parameters)
• 401 - Missing or invalid JWT token
• 404 - Vehicle data not found

Server Errors (5xx)

• 500 - Database errors, unexpected failures
• Detailed logging without exposing internal details

Extensibility Design

Future Lookup Types

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

Current: Vehicle hierarchical data (years, makes, models, trims, engines, transmissions) Planned: 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

Integration Tests

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

Run Tests

# All platform tests
npm test -- --testPathPattern=src/features/platform

# Unit tests only
npm test -- --testPathPattern=src/features/platform/tests/unit

# Integration tests only
npm test -- --testPathPattern=src/features/platform/tests/integration

# With coverage
npm test -- --testPathPattern=src/features/platform --coverage

Migration History

The platform feature was migrated from a separate Python FastAPI service (mvp-platform container) to a TypeScript feature module within the backend. The Python container has been removed and platform capabilities are now fully integrated into the mvp-backend container.

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 -- --testPathPattern=src/features/platform

# Type check
npm run type-check

# Lint
npm run lint

Future Considerations

Planned Features

• VIN decoding endpoint with PostgreSQL + vPIC fallback
• Circuit breaker pattern for external API resilience

Potential Enhancements

• Batch VIN decode endpoint (decode multiple VINs)
• Admin endpoint to invalidate cache patterns
• Part number cross-reference lookups
• Service bulletin integration
• Recall information integration

Performance Monitoring

• Track cache hit rates
• Log slow queries (> 200ms)

Related Features

Vehicles Feature

• Path: backend/src/features/vehicles/
• Relationship: Consumes platform hierarchical data
• Integration: Uses dropdown endpoints for vehicle year/make/model selection

Frontend Integration

• Dropdown Components: Use hierarchical vehicle data endpoints for year/make/model/trim selection
• Vehicle Forms: Leverage platform data for validation
• VIN Scanner: Will use VIN decode endpoint when implemented (Planned/Future)

---

Platform Feature: Extensible foundation for vehicle hierarchical data. Production-ready with PostgreSQL, Redis caching, and comprehensive error handling. VIN decoding is planned for future implementation.