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**:
```bash
make start  # Starts platform + application services
```

**Platform Service Logs**:
```bash
make logs  # All service logs
docker logs mvp-platform-vehicles-api
docker logs mvp-platform-tenants
```

**Platform Service Shell Access**:
```bash
docker exec -it mvp-platform-vehicles-api bash
docker exec -it mvp-platform-tenants bash
```

### Service-Specific Development

**MVP Platform Vehicles Development**:
```bash
# 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**:
```bash
# 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:
```javascript
// 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**:
```bash
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**:
```bash
docker logs mvp-platform-vehicles-api --tail=100 -f
docker logs mvp-platform-tenants --tail=100 -f
```

**Database Logs**:
```bash
docker logs mvp-platform-vehicles-db --tail=100 -f
docker logs platform-postgres --tail=100 -f
```