motovaultpro/docs/PLATFORM-SERVICES.md

MVP Platform Services

Overview

MVP Platform Services are independent microservices that provide shared capabilities to multiple applications. These services are completely separate from the MotoVaultPro application and can be deployed, scaled, and maintained independently.

Architecture Pattern

Each platform service follows a 3-container microservice pattern:

• Database Container: Dedicated PostgreSQL instance
• API Container: FastAPI service exposing REST endpoints
• ETL Container: Data processing and transformation (where applicable)

Platform Services

1. MVP Platform Vehicles Service

The primary platform service providing comprehensive vehicle data through hierarchical APIs.

Architecture Components

• API Service: Python FastAPI on port 8000
• Database: PostgreSQL on port 5433 with normalized VPIC schema
• Cache: Dedicated Redis instance on port 6380
• ETL Pipeline: MSSQL → PostgreSQL data transformation

API Endpoints

Hierarchical Vehicle Data API:

GET /vehicles/makes?year={year}
GET /vehicles/models?year={year}&make_id={make_id}
GET /vehicles/trims?year={year}&make_id={make_id}&model_id={model_id}
GET /vehicles/engines?year={year}&make_id={make_id}&model_id={model_id}
GET /vehicles/transmissions?year={year}&make_id={make_id}&model_id={model_id}

VIN Decoding:

POST /vehicles/vindecode

Health and Documentation:

GET /health
GET /docs    # Swagger UI

Data Source and ETL

Source: NHTSA VPIC database (MSSQL format) ETL Schedule: Weekly data refresh Data Pipeline:

1. Extract from NHTSA MSSQL database
2. Transform and normalize vehicle specifications
3. Load into PostgreSQL with optimized schema
4. Build hierarchical cache structure

Caching Strategy

Year-based Hierarchical Caching:

• Cache vehicle makes by year (1 week TTL)
• Cache models by year+make (1 week TTL)
• Cache trims/engines/transmissions by year+make+model (1 week TTL)
• VIN decode results cached by VIN (permanent)

Authentication

Service-to-Service Authentication:

• API Key: PLATFORM_VEHICLES_API_KEY
• Header: X-API-Key: {api_key}
• No user authentication (service-level access only)

2. MVP Platform Tenants Service

Multi-tenant management service for platform-wide tenant operations.

Architecture Components

• API Service: Python FastAPI on port 8000
• Database: Dedicated PostgreSQL on port 5434
• Cache: Dedicated Redis instance on port 6381

Capabilities

• Tenant provisioning and management
• Cross-service tenant validation
• Tenant-specific configuration management

3. MVP Platform Landing Service

Marketing and landing page service.

Architecture Components

• Frontend: Vite-based static site served via nginx
• URL: https://motovaultpro.com

Service Communication

Inter-Service Communication

Platform services have no direct communication between each other, but share some infrastructure resources:

Shared Resources:

• Configuration files (./config/shared/production.yml)
• Secret management infrastructure (./secrets/platform/ directory structure)
• Docker network (platform network for internal communication)

Independence Level: Services can be deployed independently but rely on shared configuration and secrets infrastructure.

Application → Platform Communication

• Protocol: HTTP REST APIs
• Authentication: Service API keys
• Circuit Breaker: Application implements circuit breaker pattern for resilience
• Fallback: Application has fallback mechanisms when platform services unavailable

Service Discovery

• Docker Networking: Services communicate via container names
• Environment Variables: Service URLs configured via environment
• Health Checks: Each service exposes /health endpoint

Development Workflow

Local Development

Start All Platform Services:

make start  # Starts platform + application services

Platform Service Logs:

make logs  # All service logs
docker logs mvp-platform-vehicles-api
docker logs mvp-platform-tenants

Platform Service Shell Access:

docker exec -it mvp-platform-vehicles-api bash
docker exec -it mvp-platform-tenants bash

Service-Specific Development

MVP Platform Vehicles Development:

# Access vehicles service
cd mvp-platform-services/vehicles

# Run ETL manually
make etl-load-manual

# Validate ETL data
make etl-validate-json

# Service shell access
make etl-shell

Database Management

Platform Service Databases:

• Platform PostgreSQL (port 5434): Shared platform data
• Platform Redis (port 6381): Shared platform cache
• MVP Platform Vehicles DB (port 5433): Vehicle-specific data
• MVP Platform Vehicles Redis (port 6380): Vehicle-specific cache

Database Access:

# Platform PostgreSQL
docker exec -it platform-postgres psql -U postgres

# Vehicles Database
docker exec -it mvp-platform-vehicles-db psql -U postgres

Deployment Strategy

Independent Deployment

Each platform service can be deployed independently:

• Own CI/CD pipeline
• Independent scaling
• Isolated database and cache
• Zero-downtime deployments

Service Dependencies

Deployment Order: Platform services have no dependencies on each other Rolling Updates: Services can be updated independently Rollback: Each service can rollback independently

Production Considerations

Scaling:

• Each service scales independently based on load
• Database and cache scale with service
• API containers can be horizontally scaled

Monitoring:

• Each service exposes health endpoints
• Independent logging and metrics
• Service-specific alerting

Security:

• API key authentication between services
• Network isolation via Docker networking
• Service-specific security policies

Integration Patterns

Circuit Breaker Pattern

Application services implement circuit breaker when calling platform services:

// Example from vehicles feature
const circuit = new CircuitBreaker(platformVehiclesCall, {
  timeout: 3000,
  errorThresholdPercentage: 50,
  resetTimeout: 30000
});

Fallback Strategies

Application features have fallback mechanisms:

• Cache previous responses
• Degrade gracefully to external APIs
• Queue operations for later retry

Data Synchronization

Platform services are source of truth:

• Application caches platform data with TTL
• Application invalidates cache on platform updates
• Eventual consistency model acceptable

Troubleshooting

Common Issues

Service Discovery Problems:

• Verify Docker networking: docker network ls
• Check container connectivity: docker exec -it container ping service

API Authentication Failures:

• Verify PLATFORM_VEHICLES_API_KEY environment variable
• Check API key in service logs

Database Connection Issues:

• Verify database containers are healthy
• Check port mappings and network connectivity

Health Checks

Verify All Platform Services:

curl http://localhost:8000/health  # Platform Vehicles
curl http://localhost:8000/health  # Platform Tenants (same port as vehicles)
curl https://motovaultpro.com      # Platform Landing

Note: Both platform services (Vehicles and Tenants APIs) run on port 8000. They are differentiated by routing rules in Traefik based on the request path.

Logs and Debugging

Service Logs:

docker logs mvp-platform-vehicles-api --tail=100 -f
docker logs mvp-platform-tenants --tail=100 -f

Database Logs:

docker logs mvp-platform-vehicles-db --tail=100 -f
docker logs platform-postgres --tail=100 -f