Initial Commit
This commit is contained in:
Eric Gullickson
@@ -1,17 +1,26 @@
|
||||
# Vehicles Feature Capsule
|
||||
|
||||
## Quick Summary (50 tokens)
|
||||
Primary entity for vehicle management with VIN decoding via NHTSA vPIC API. Handles CRUD operations, automatic vehicle data population, user ownership validation, caching strategy (VIN lookups: 30 days, user lists: 5 minutes). Foundation for fuel-logs and maintenance features.
|
||||
Primary entity for vehicle management consuming MVP Platform Vehicles Service. Handles CRUD operations, hierarchical vehicle dropdowns, VIN decoding via platform service, user ownership validation, caching strategy (user lists: 5 minutes). Foundation for fuel-logs and maintenance features.
|
||||
|
||||
## API Endpoints
|
||||
- `POST /api/vehicles` - Create new vehicle with VIN decoding
|
||||
|
||||
### Vehicle Management
|
||||
- `POST /api/vehicles` - Create new vehicle with platform VIN decoding
|
||||
- `GET /api/vehicles` - List all user's vehicles (cached 5 min)
|
||||
- `GET /api/vehicles/:id` - Get specific vehicle
|
||||
- `PUT /api/vehicles/:id` - Update vehicle details
|
||||
- `DELETE /api/vehicles/:id` - Soft delete vehicle
|
||||
|
||||
## Authentication Required
|
||||
All endpoints require valid JWT token with user context.
|
||||
### Hierarchical Vehicle Dropdowns (Platform Service Proxy)
|
||||
- `GET /api/vehicles/dropdown/makes?year={year}` - Get makes for year
|
||||
- `GET /api/vehicles/dropdown/models?year={year}&make_id={make_id}` - Get models for make/year
|
||||
- `GET /api/vehicles/dropdown/trims?year={year}&make_id={make_id}&model_id={model_id}` - Get trims
|
||||
- `GET /api/vehicles/dropdown/engines?year={year}&make_id={make_id}&model_id={model_id}` - Get engines
|
||||
- `GET /api/vehicles/dropdown/transmissions?year={year}&make_id={make_id}&model_id={model_id}` - Get transmissions
|
||||
|
||||
## Authentication
|
||||
- All vehicles endpoints (including dropdowns) require a valid JWT (Auth0).
|
||||
|
||||
## Request/Response Examples
|
||||
|
||||
@@ -31,9 +40,9 @@ Response (201):
|
||||
"id": "uuid-here",
|
||||
"userId": "user-id",
|
||||
"vin": "1HGBH41JXMN109186",
|
||||
"make": "Honda", // Auto-decoded
|
||||
"model": "Civic", // Auto-decoded
|
||||
"year": 2021, // Auto-decoded
|
||||
"make": "Honda", // Auto-decoded via platform service
|
||||
"model": "Civic", // Auto-decoded via platform service
|
||||
"year": 2021, // Auto-decoded via platform service
|
||||
"nickname": "My Honda",
|
||||
"color": "Blue",
|
||||
"licensePlate": "ABC123",
|
||||
@@ -44,6 +53,30 @@ Response (201):
|
||||
}
|
||||
```
|
||||
|
||||
### Get Makes for Year
|
||||
```json
|
||||
GET /api/vehicles/dropdown/makes?year=2024
|
||||
|
||||
Response (200):
|
||||
[
|
||||
{"id": 1, "name": "Honda"},
|
||||
{"id": 2, "name": "Toyota"},
|
||||
{"id": 3, "name": "Ford"}
|
||||
]
|
||||
```
|
||||
|
||||
### Get Models for Make/Year
|
||||
```json
|
||||
GET /api/vehicles/dropdown/models?year=2024&make_id=1
|
||||
|
||||
Response (200):
|
||||
[
|
||||
{"id": 101, "name": "Civic"},
|
||||
{"id": 102, "name": "Accord"},
|
||||
{"id": 103, "name": "CR-V"}
|
||||
]
|
||||
```
|
||||
|
||||
## Feature Architecture
|
||||
|
||||
### Complete Self-Contained Structure
|
||||
@@ -62,14 +95,14 @@ vehicles/
|
||||
│ └── vehicles.repository.ts
|
||||
├── migrations/ # Feature schema
|
||||
│ └── 001_create_vehicles_tables.sql
|
||||
├── external/ # External APIs
|
||||
│ └── vpic/
|
||||
│ ├── vpic.client.ts
|
||||
│ └── vpic.types.ts
|
||||
├── external/ # Platform Service Integration
|
||||
│ └── platform-vehicles/
|
||||
│ ├── platform-vehicles.client.ts
|
||||
│ └── platform-vehicles.types.ts
|
||||
├── tests/ # All tests
|
||||
│ ├── unit/
|
||||
│ │ ├── vehicles.service.test.ts
|
||||
│ │ └── vpic.client.test.ts
|
||||
│ │ └── platform-vehicles.client.test.ts
|
||||
│ └── integration/
|
||||
│ └── vehicles.integration.test.ts
|
||||
└── docs/ # Additional docs
|
||||
@@ -78,21 +111,28 @@ vehicles/
|
||||
## Key Features
|
||||
|
||||
### 🔍 Automatic VIN Decoding
|
||||
- **External API**: NHTSA vPIC (Vehicle Product Information Catalog)
|
||||
- **Caching**: 30-day Redis cache for VIN lookups
|
||||
- **Fallback**: Graceful handling of decode failures
|
||||
- **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
|
||||
|
||||
### 📋 Hierarchical Vehicle Dropdowns
|
||||
- **Platform Service**: Consumes year-based hierarchical vehicle API
|
||||
- **Performance**: < 100ms response times via platform service caching
|
||||
- **Parameters**: Hierarchical filtering (year → make → model → trims/engines/transmissions)
|
||||
- **Circuit Breaker**: Graceful degradation with cached fallbacks
|
||||
|
||||
### 🏗️ Database Schema
|
||||
- **Primary Table**: `vehicles` with soft delete
|
||||
- **Cache Table**: `vin_cache` for external API results
|
||||
- **Indexes**: Optimized for user queries and VIN lookups
|
||||
- **Constraints**: Unique VIN per user, proper foreign keys
|
||||
- **Platform Integration**: No duplicate caching - relies on platform service
|
||||
|
||||
### 🚀 Performance Optimizations
|
||||
- **Redis Caching**: User vehicle lists cached for 5 minutes
|
||||
- **VIN Cache**: 30-day persistent cache in PostgreSQL
|
||||
- **Indexes**: Strategic database indexes for fast queries
|
||||
- **Platform Service**: Offloads heavy VIN decoding and vehicle data caching
|
||||
- **Circuit Breaker**: Prevents cascading failures with fallback responses
|
||||
- **Indexes**: Strategic database indexes for fast user queries
|
||||
- **Soft Deletes**: Maintains referential integrity
|
||||
|
||||
## Business Rules
|
||||
@@ -101,7 +141,7 @@ vehicles/
|
||||
- Must be exactly 17 characters
|
||||
- Cannot contain letters I, O, or Q
|
||||
- Must pass basic checksum validation
|
||||
- Auto-populates make, model, year from vPIC API
|
||||
- Auto-populates make, model, year from MVP Platform Vehicles Service
|
||||
|
||||
### User Ownership
|
||||
- Each user can have multiple vehicles
|
||||
@@ -117,32 +157,36 @@ vehicles/
|
||||
- `core/logging` - Structured logging with Winston
|
||||
- `shared-minimal/utils` - Pure validation utilities
|
||||
|
||||
### External Services
|
||||
- **NHTSA vPIC API** - VIN decoding service
|
||||
### Platform Services
|
||||
- **MVP Platform Vehicles Service** - VIN decoding and hierarchical vehicle data
|
||||
- **PostgreSQL** - Primary data storage
|
||||
- **Redis** - Caching layer
|
||||
|
||||
### Database Tables
|
||||
- `vehicles` - Primary vehicle data
|
||||
- `vin_cache` - External API response cache
|
||||
|
||||
## Caching Strategy
|
||||
|
||||
### VIN Decode Cache (30 days)
|
||||
- **Key**: `vpic:vin:{vin}`
|
||||
- **TTL**: 2,592,000 seconds (30 days)
|
||||
- **Rationale**: Vehicle specifications never change
|
||||
### Platform Service Caching
|
||||
- **VIN Decoding**: Handled entirely by MVP Platform Vehicles Service
|
||||
- **Hierarchical Data**: Year-based caching strategy managed by platform service
|
||||
- **Performance**: < 100ms responses via platform service optimization
|
||||
|
||||
### User Vehicle List (5 minutes)
|
||||
- **Key**: `vehicles:user:{userId}`
|
||||
- **TTL**: 300 seconds (5 minutes)
|
||||
- **Invalidation**: On create, update, delete
|
||||
|
||||
### Platform Service Integration
|
||||
- **Circuit Breaker**: Prevent cascading failures
|
||||
- **Fallback Strategy**: Cached responses when platform service unavailable
|
||||
- **Timeout**: 3 second timeout with automatic retry
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit Tests
|
||||
- `vehicles.service.test.ts` - Business logic with mocked dependencies
|
||||
- `vpic.client.test.ts` - External API client with mocked HTTP
|
||||
- `platform-vehicles.client.test.ts` - Platform service client with mocked HTTP
|
||||
|
||||
### Integration Tests
|
||||
- `vehicles.integration.test.ts` - Complete API workflow with test database
|
||||
@@ -172,8 +216,9 @@ npm test -- features/vehicles --coverage
|
||||
- `409` - Duplicate VIN for user
|
||||
|
||||
### Server Errors (5xx)
|
||||
- `500` - Database connection, VIN API failures
|
||||
- Graceful degradation when vPIC API unavailable
|
||||
- `500` - Database connection, platform service failures
|
||||
- `503` - Platform service unavailable (circuit breaker open)
|
||||
- Graceful degradation when platform service unavailable
|
||||
|
||||
## Future Considerations
|
||||
|
||||
@@ -184,9 +229,10 @@ npm test -- features/vehicles --coverage
|
||||
|
||||
### Potential Enhancements
|
||||
- Vehicle image uploads (MinIO integration)
|
||||
- VIN decode webhook for real-time updates
|
||||
- Vehicle value estimation integration
|
||||
- Enhanced platform service integration for real-time updates
|
||||
- Vehicle value estimation via additional platform services
|
||||
- Maintenance scheduling based on vehicle age/mileage
|
||||
- Advanced dropdown features (trim-specific engines/transmissions)
|
||||
|
||||
## Development Commands
|
||||
|
||||
@@ -194,8 +240,8 @@ npm test -- features/vehicles --coverage
|
||||
# Run migrations
|
||||
make migrate
|
||||
|
||||
# Start development environment
|
||||
make dev
|
||||
# Start environment
|
||||
make start
|
||||
|
||||
# View feature logs
|
||||
make logs-backend | grep vehicles
|
||||
|
||||
Reference in New Issue
Block a user