motovaultpro/docs/PLATFORM-SERVICES.md

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):

docker compose ps mvp-backend

Logs and Debugging

Service Logs:

docker compose logs -f mvp-backend

Database Logs:

docker compose logs -f mvp-postgres