Initial Commit
This commit is contained in:
Eric Gullickson
260
docs/PLATFORM-SERVICES.md
Normal file
260
docs/PLATFORM-SERVICES.md
Normal file
@@ -0,0 +1,260 @@
|
||||
# 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 8001
|
||||
- **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 are **completely independent** - no direct communication between platform services.
|
||||
|
||||
### 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:8001/health # Platform Tenants
|
||||
curl https://motovaultpro.com # Platform Landing
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
Reference in New Issue
Block a user