egullickson/motovaultpro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Redesign

Browse Source
This commit is contained in:
Eric Gullickson
2025-11-01 21:27:42 -05:00
parent 20953c6dee
commit 046c66fc7d
203 changed files with 5699 additions and 404943 deletions
Download Patch File Download Diff File Expand all files Collapse all files

252
docs/PLATFORM-SERVICES.md
View File

@@ -1,231 +1,83 @@
# MVP Platform Services
# MVP Platform Service
## 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.
The MVP Platform service is an **integrated service** that provides platform capabilities to the MotoVaultPro application. This service is part of the simplified 6-container architecture.
## Architecture Pattern
## Architecture
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)
The platform service is integrated into the main application stack:
- **Service Container**: mvp-platform
- **Shared Database**: Uses mvp-postgres
- **Shared Cache**: Uses mvp-redis
## Platform Services
## Platform Capabilities
### 1. MVP Platform Vehicles Service
### Vehicle Data Service
The primary platform service providing comprehensive vehicle data through hierarchical APIs.
The platform provides vehicle data capabilities including:
- Vehicle makes, models, trims
- Engine and transmission data
- VIN decoding
- Year-based vehicle information
#### 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`
**Data Source**: Vehicle data from standardized sources
**Cache Strategy**: Year-based hierarchical caching using mvp-redis
## 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
- **Protocol**: Internal service calls within the application
- **Database**: Shared mvp-postgres database
- **Cache**: Shared mvp-redis cache
## Development Workflow
### Local Development
**Start All Platform Services**:
**Start All Services**:
```bash
make start # Starts platform + application services
make start # Starts all 6 containers
```
**Platform Service Logs**:
**Service Logs**:
```bash
make logs # All service logs
docker logs mvp-platform-vehicles-api
docker logs mvp-platform-tenants
docker logs mvp-platform
```
**Platform Service Shell Access**:
**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
docker exec -it mvp-platform sh
```
### 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
**Shared Database**:
- **PostgreSQL** (port 5432): mvp-postgres
- **Redis** (port 6379): mvp-redis
**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
# PostgreSQL
make db-shell-app
```
## 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
### Integrated Deployment
The platform service deploys with the main application:
- Same deployment pipeline
- Shares database and cache
- Deployed as part of 6-container stack
## 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
### Data Access
Application features access platform data through shared database:
- Direct database queries
- Shared cache for performance
- Single transaction context
## Troubleshooting
@@ -233,37 +85,27 @@ Platform services are source of truth:
**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
- Check container connectivity: `docker exec -it mvp-platform sh`
**Database Connection Issues**:
- Verify database containers are healthy
- Verify mvp-postgres is healthy
- Check port mappings and network connectivity
### Health Checks
**Verify All Platform Services**:
**Verify Platform Service**:
```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
docker ps | grep mvp-platform
```
**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
docker logs mvp-platform --tail=100 -f
```
**Database Logs**:
```bash
docker logs mvp-platform-vehicles-db --tail=100 -f
docker logs platform-postgres --tail=100 -f
```
docker logs mvp-postgres --tail=100 -f
```