egullickson/motovaultpro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Community 93 Premium feature complete

Browse Source
This commit is contained in:
Eric Gullickson
2025-12-21 11:31:10 -06:00
parent 1bde31247f
commit 95f5e89e48
60 changed files with 8061 additions and 350 deletions
Download Patch File Download Diff File Expand all files Collapse all files

209
backend/src/features/platform/README.md
View File

@@ -1,7 +1,7 @@
# 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.
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
@@ -12,8 +12,8 @@ Extensible platform service for vehicle hierarchical data lookups and VIN decodi
- `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
### 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)
@@ -56,11 +56,12 @@ Response (200):
}
```
### Decode VIN
### Decode VIN (Planned/Future)
The following endpoint is planned but not yet implemented:
```json
GET /api/platform/vehicle?vin=1HGCM82633A123456
Response (200):
Planned Response (200):
{
"vin": "1HGCM82633A123456",
"success": true,
@@ -70,30 +71,11 @@ Response (200):
"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"
"transmission_description": "5-Speed Automatic"
}
}
```
### VIN Decode Error
```json
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
@@ -105,47 +87,43 @@ platform/
│ ├── 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
│ ├── 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
### 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
### 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), positive integer IDs
- **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**: 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
- **Tables**: `vehicle_options` table for hierarchical lookups
- **Migrations**: `001_create_vehicle_lookup_schema.sql`
### Caching Strategy
@@ -158,25 +136,24 @@ platform/
- **TTL**: 21600 seconds (6 hours)
- **Invalidation**: Natural expiration via TTL
#### VIN Decode (7 days success, 1 hour failure)
#### VIN Decode Caching (Planned/Future)
When VIN decoding is implemented:
- **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
### 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
### 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
@@ -185,75 +162,44 @@ platform/
- `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
### External APIs (Planned/Future)
When VIN decoding is implemented:
- **NHTSA vPIC**: https://vpic.nhtsa.dot.gov/api (VIN decoding fallback)
### 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
### Database Tables
- **vehicle_options** - Hierarchical vehicle data (years, makes, models, trims, engines, transmissions)
### 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)
- **6-hour TTL**: Vehicle hierarchical data (rarely changes)
- **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)
- Connection pooling via backend pool
## Error Handling
### Client Errors (4xx)
- `400` - Invalid VIN format, validation errors
- `400` - Validation errors (invalid year, missing parameters)
- `401` - Missing or invalid JWT token
- `404` - VIN not found in database or API
- `503` - vPIC API unavailable (circuit breaker open)
- `404` - Vehicle data not found
### Server Errors (5xx)
- `500` - Database errors, unexpected failures
- Graceful degradation when external APIs unavailable
- Detailed logging without exposing internal details
### Error Response Format
```json
{
"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
**Current**: Vehicle hierarchical data (years, makes, models, trims, engines, transmissions)
**Planned**: VIN decoding
**Future Examples**:
- Part number lookups
- Service bulletins
@@ -275,9 +221,6 @@ The platform feature is designed to accommodate additional lookup types beyond v
### 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
@@ -285,41 +228,21 @@ The platform feature is designed to accommodate additional lookup types beyond v
### Run Tests
```bash
# All platform tests
npm test -- features/platform
npm test -- --testPathPattern=src/features/platform
# Unit tests only
npm test -- features/platform/tests/unit
npm test -- --testPathPattern=src/features/platform/tests/unit
# Integration tests only
npm test -- features/platform/tests/integration
# Integration tests only
npm test -- --testPathPattern=src/features/platform/tests/integration
# With coverage
npm test -- features/platform --coverage
npm test -- --testPathPattern=src/features/platform --coverage
```
## Migration from Python Service
## Migration History
### 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
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
@@ -334,7 +257,7 @@ make logs-backend | grep platform
make shell-backend
# Inside container - run feature tests
npm test -- features/platform
npm test -- --testPathPattern=src/features/platform
# Type check
npm run type-check
@@ -345,35 +268,33 @@ 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
- 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
- **Relationship**: Consumes platform hierarchical data
- **Integration**: Uses dropdown endpoints for vehicle year/make/model selection
### Frontend Integration
- **Dropdown Components**: Use hierarchical vehicle data endpoints
- **VIN Scanner**: Use VIN decode endpoint for auto-population
- **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 data and future platform capabilities. Production-ready with PostgreSQL, Redis caching, circuit breaker resilience, and comprehensive error handling.
**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.