# Vehicles Feature Capsule

## Quick Summary (50 tokens)
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

### 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

### 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

### Create Vehicle
```json
POST /api/vehicles
{
  "vin": "1HGBH41JXMN109186",
  "nickname": "My Honda",
  "color": "Blue",
  "licensePlate": "ABC123",
  "odometerReading": 50000
}

Response (201):
{
  "id": "uuid-here",
  "userId": "user-id",
  "vin": "1HGBH41JXMN109186",
  "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",
  "odometerReading": 50000,
  "isActive": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}
```

### 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
```
vehicles/
├── README.md              # This file
├── index.ts               # Public API exports
├── api/                   # HTTP layer
│   ├── vehicles.controller.ts
│   ├── vehicles.routes.ts
│   └── vehicles.validation.ts
├── domain/                # Business logic
│   ├── vehicles.service.ts
│   └── vehicles.types.ts
├── data/                  # Database layer
│   └── vehicles.repository.ts
├── migrations/            # Feature schema
│   └── 001_create_vehicles_tables.sql
├── external/              # Platform Service Integration
│   └── platform-vehicles/
│       ├── platform-vehicles.client.ts
│       └── platform-vehicles.types.ts
├── tests/                 # All tests
│   ├── unit/
│   │   ├── vehicles.service.test.ts
│   │   └── platform-vehicles.client.test.ts
│   └── integration/
│       └── vehicles.integration.test.ts
└── docs/                  # Additional docs
```

## 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

### 📋 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
- **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
- **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

### VIN Validation
- Must be exactly 17 characters
- Cannot contain letters I, O, or Q
- Must pass basic checksum validation
- Auto-populates make, model, year from MVP Platform Vehicles Service

### User Ownership
- Each user can have multiple vehicles
- Same VIN cannot be registered twice by same user
- All operations validate user ownership
- Soft delete preserves data for audit trail

## Dependencies

### Internal Core Services
- `core/auth` - JWT authentication middleware
- `core/config` - Database pool, Redis cache
- `core/logging` - Structured logging with Winston
- `shared-minimal/utils` - Pure validation utilities

### 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

## Caching Strategy

### 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
- `platform-vehicles.client.test.ts` - Platform service client with mocked HTTP

### Integration Tests
- `vehicles.integration.test.ts` - Complete API workflow with test database

### Run Tests
```bash
# All vehicle tests
npm test -- features/vehicles

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

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

# With coverage
npm test -- features/vehicles --coverage
```

## Error Handling

### Client Errors (4xx)
- `400` - Invalid VIN format, validation errors
- `401` - Missing or invalid JWT token
- `403` - User not authorized for vehicle
- `404` - Vehicle not found
- `409` - Duplicate VIN for user

### Server Errors (5xx)
- `500` - Database connection, platform service failures
- `503` - Platform service unavailable (circuit breaker open)
- Graceful degradation when platform service unavailable

## Future Considerations

### Dependent Features
- **fuel-logs** - Will reference `vehicle_id`
- **maintenance** - Will reference `vehicle_id`
- Both features depend on vehicles as primary entity

### Potential Enhancements
- Vehicle image uploads (MinIO 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

```bash
# Run migrations
make migrate

# Start environment
make start

# View feature logs
make logs-backend | grep vehicles

# Open container shell
make shell-backend

# Inside container - run feature tests
npm test -- features/vehicles
```