# MVP Platform Module

## Overview

The MVP Platform module is fully integrated inside the MotoVaultPro backend container. 

## Architecture

The platform module runs as part of the backend service:
- **Runtime**: `mvp-backend` container (Fastify API)
- **Shared Database**: Uses mvp-postgres
- **Shared Cache**: Uses mvp-redis

## Platform Capabilities

### Vehicle Data Service (Implemented)

The platform provides vehicle hierarchical data lookups:
- Vehicle years (distinct, descending)
- Vehicle makes for a specific year
- Vehicle models for year and make
- Vehicle trims for year, make, and model
- Engine and transmission data

**Endpoints**:
- `GET /api/platform/years` - Available model years
- `GET /api/platform/makes?year={year}` - Makes for year
- `GET /api/platform/models?year={year}&make={make}` - Models for year/make
- `GET /api/platform/trims?year={year}&make={make}&model={model}` - Trims
- `GET /api/platform/engines?year={year}&make={make}&model={model}&trim={trim}` - Engines
- `GET /api/platform/transmissions?...` - Transmissions

### VIN Decoding (Planned/Future)

VIN decoding is planned but not yet implemented. Future capabilities will include:
- `GET /api/platform/vehicle?vin={vin}` - Decode VIN to vehicle details
- PostgreSQL-based VIN decode function
- Gemini VIN decode via OCR service
- Redis caching (7-day TTL for successful decodes)

**Data Source**: Vehicle data from standardized sources
**Cache Strategy**: Year-based hierarchical caching using mvp-redis

## Service Communication

### Application → Platform Communication
- **Protocol**: Internal service calls within the application
- **Database**: Shared mvp-postgres database
- **Cache**: Shared mvp-redis cache

## Deployment Strategy

### Integrated Deployment
The platform module deploys with the main application:
- Same deployment pipeline
- Shares database and cache
- Deployed as part of the 9-container stack (6 application + 3 logging)

See `docs/LOGGING.md` for unified logging system documentation.

## Integration Patterns

### Data Access
Application features access platform data through shared database:
- Direct database queries
- Shared cache for performance
- Single transaction context

## Troubleshooting

### Common Issues

**Service Discovery Problems**:
- Verify Docker networking: `docker network ls`
- Check backend container connectivity: `docker compose exec mvp-backend sh`

**Database Connection Issues**:
- Verify mvp-postgres is healthy
- Check port mappings and network connectivity

### Health Checks

**Verify Backend Service (contains platform module)**:
```bash
docker compose ps mvp-backend
```

### Logs and Debugging

**Service Logs**:
```bash
docker compose logs -f mvp-backend
```

**Database Logs**:
```bash
docker compose logs -f mvp-postgres
```