Files

Eric Gullickson 54d97a98b5 Platform Consolidation Planning

2025-11-03 09:21:10 -06:00

32 KiB

Raw Blame History

Platform Service Integration - Agent Execution Manifest

Overview

Integration of mvp-platform vehicles service into backend as a feature module. This document defines specialized agents for parallel execution.

Goal: Convert 6-container architecture to 5-container by absorbing platform service into backend.

Strategy: Single-phase cutover with parallel agent execution.

Estimated Duration: 6-8 hours with 7 agents running in parallel.

Execution Waves

Wave 1: Parallel Foundation (4 agents)

Can execute simultaneously, no dependencies.

Agent 1: Backend Feature Creator
Agent 2: VIN Removal - Backend
Agent 3: VIN Removal - Frontend
Agent 4: Configuration Cleanup

Wave 2: Integration & Testing (2 agents)

Depends on Wave 1 completion.

Agent 5: Integration & Testing
Agent 6: Documentation Updates

Wave 3: Final Cleanup (1 agent)

Depends on Wave 2 completion.

Agent 7: Container Removal & Deployment

Agent Definitions

AGENT 1: Backend Feature Creator

Role: Create new vehicle-data feature module in TypeScript

Subagent Type: feature-agent

Dependencies: None (can start immediately)

Deliverables:

Complete feature structure in backend/src/features/vehicle-data/
TypeScript repository with all SQL queries converted from Python
Caching service using Redis
API routes and controllers
Request/response DTOs
Feature README

Prompt:

Create a new feature module at backend/src/features/vehicle-data/ that replaces the Python FastAPI platform service.

CONTEXT:
- Source: /Users/egullickson/Documents/Technology/coding/motovaultpro/mvp-platform-services/vehicles/
- Python FastAPI service with vehicle hierarchical data (makes/models/trims/engines)
- Uses vehicles schema in PostgreSQL (vehicles.make, vehicles.model, etc.)
- Redis caching with 6-hour TTL
- Authentication via JWT (extract user_id)

REQUIREMENTS:

1. CREATE FEATURE STRUCTURE:
backend/src/features/vehicle-data/
├── api/
│   ├── vehicle-data.routes.ts      # Fastify routes
│   └── vehicle-data.controller.ts  # Controllers
├── domain/
│   ├── vehicle-data.service.ts     # Business logic
│   └── vehicle-data.cache.ts       # Redis caching
├── data/
│   └── vehicle-data.repository.ts  # PostgreSQL queries
├── models/
│   ├── requests.ts                 # DTOs
│   └── responses.ts                # DTOs
├── tests/
│   ├── unit/
│   └── integration/
└── README.md

2. CONVERT PYTHON TO TYPESCRIPT:

Source files:
- Python repo: mvp-platform-services/vehicles/api/repositories/vehicles_repository.py
- Python service: mvp-platform-services/vehicles/api/services/vehicles_service.py
- Python cache: mvp-platform-services/vehicles/api/services/cache_service.py

Convert these methods:
- get_years() → SELECT DISTINCT year FROM vehicles.model_year ORDER BY year DESC
- get_makes(year) → Join vehicles.make through model_year
- get_models(year, make_id) → Join vehicles.model through model_year
- get_trims(year, model_id) → Get trims for model/year
- get_engines(year, model_id, trim_id) → Get engines via trim_engine

3. IMPLEMENT CACHING:
- Use Redis from backend core (already connected)
- Cache keys: vehicle-data:makes:{year}, vehicle-data:models:{year}:{makeId}, etc.
- TTL: 6 hours (21600 seconds)
- Graceful fallback if Redis unavailable

4. CREATE API ROUTES:
All routes require JWT authentication:
- GET /api/vehicle-data/years
- GET /api/vehicle-data/makes?year={year}
- GET /api/vehicle-data/models?year={year}&make_id={id}
- GET /api/vehicle-data/trims?year={year}&model_id={id}
- GET /api/vehicle-data/engines?year={year}&trim_id={id}

5. RESPONSE FORMATS (match Python service):
{
  "years": [2024, 2023, 2022, ...],
  "makes": [{ id: 1, name: "Honda" }, ...],
  "models": [{ id: 1, name: "Civic" }, ...],
  "trims": [{ id: 1, name: "LX" }, ...],
  "engines": [{ id: 1, name: "2.0L I4" }, ...]
}

6. ERROR HANDLING:
- Validate query parameters (year 1950-2100, IDs positive integers)
- Return 400 for invalid input
- Return 404 if no data found
- Log errors but don't expose internal details

7. REGISTER ROUTES:
Update backend/src/app.ts to register feature:
import { vehicleDataRoutes } from './features/vehicle-data/api/vehicle-data.routes';
app.register(vehicleDataRoutes, { prefix: '/api/vehicle-data' });

CONSTRAINTS:
- Use existing PostgreSQL pool from core
- Use existing Redis client from core
- Follow feature capsule pattern (see backend/src/features/vehicles/ as example)
- NO VIN decoding (that's being removed)
- Production-ready code (error handling, logging, validation)

VERIFICATION:
- All TypeScript compiles without errors
- Routes registered in app.ts
- Repository queries match Python SQL logic
- Caching implementation complete
- Feature README documents all endpoints

Return confirmation when complete with file paths created.

Success Criteria:

✅ Feature structure created
✅ All Python logic converted to TypeScript
✅ Caching implemented
✅ Routes registered
✅ TypeScript compiles
✅ README complete

Estimated Time: 3-4 hours

AGENT 2: VIN Removal - Backend

Role: Remove all VIN decoding logic from backend

Subagent Type: general-purpose

Dependencies: None (can start immediately)

Deliverables:

Removed VIN decode methods from platform client
Removed vPIC fallback client
Updated vehicles service (no auto-populate from VIN)
Updated vehicle creation to require make/model/year
Removed VIN cache methods
Removed circuit breaker for VIN decode

Prompt:

Remove all VIN decoding functionality from the backend codebase.

CONTEXT:
VIN decoding is being removed as a feature. Users will manually select make/model/year instead of auto-populating from VIN.

TASKS:

1. DELETE ENTIRE DIRECTORY:
backend/src/features/vehicles/external/platform-vehicles/
- This contains the platform client with VIN decode
- The entire external integration is being replaced

2. DELETE FILE:
backend/src/features/vehicles/domain/platform-integration.service.ts
- This service wraps platform calls and vPIC fallback
- No longer needed

3. UPDATE VEHICLES SERVICE:
File: backend/src/features/vehicles/domain/vehicles.service.ts

Remove:
- Import of PlatformIntegrationService
- Constructor dependency on platformIntegration
- Any calls to platformIntegration.decodeVIN()
- Auto-population of make/model/year from VIN

Keep VIN as optional string field (for user reference only).

4. UPDATE VEHICLES REPOSITORY:
File: backend/src/features/vehicles/data/vehicles.repository.ts

Remove:
- cacheVINDecode() method
- Any VIN cache queries
- VIN decode cache table references

5. UPDATE VEHICLE CREATION:
File: backend/src/features/vehicles/api/vehicles.controller.ts

Update createVehicle endpoint:
- Remove VIN decode step
- Require make, model, year in request body (not optional)
- VIN field optional (string for reference only)

6. UPDATE VALIDATION:
File: backend/src/features/vehicles/models/requests.ts

Update CreateVehicleRequest:
- make: REQUIRED string
- model: REQUIRED string
- year: REQUIRED number (1950-2100)
- vin: OPTIONAL string (17 chars if provided)

7. REMOVE CIRCUIT BREAKER:
Check package.json for opossum dependency:
- If ONLY used for platform service, remove from package.json
- If used elsewhere, keep but remove platform-specific circuit breaker config

8. REMOVE VPIC CLIENT:
Search for vPIC/NHTSA API client:
- Remove any vPIC fallback client files
- Remove VPIC_API_URL environment variable references

9. UPDATE TESTS:
backend/src/features/vehicles/tests/
- Delete: unit/platform-vehicles.client.test.ts
- Update: integration/vehicles.integration.test.ts
  - Remove VIN decode test scenarios
  - Update create vehicle tests (now requires make/model/year)

VERIFICATION:
- No references to "platform-vehicles" in backend code
- No references to "vindecode" or "decodeVIN"
- No references to "vPIC" or "NHTSA"
- Vehicle creation requires make/model/year
- All tests updated and passing
- TypeScript compiles without errors

Return list of files deleted and modified with confirmation.

Success Criteria:

✅ Platform integration deleted
✅ VIN decode logic removed
✅ Vehicle creation updated
✅ Tests updated
✅ No VIN references remain

Estimated Time: 2-3 hours

AGENT 3: VIN Removal - Frontend

Role: Remove VIN decoding from frontend UI

Subagent Type: first-frontend-agent

Dependencies: None (can start immediately)

Deliverables:

Removed VIN decode button/functionality
Updated vehicle form to require make/model/year dropdowns
Updated form validation
Updated user experience (manual selection)

Prompt:

Remove VIN decoding functionality from the frontend and update vehicle creation form to require manual make/model/year selection.

CONTEXT:
VIN decoding is being removed. Users will now manually select vehicle details from dropdowns instead of auto-populating from VIN.

TASKS:

1. FIND VEHICLE CREATION FORM:
Search for vehicle creation/edit components:
- Likely in: frontend/src/features/vehicles/ or frontend/src/components/vehicles/
- Look for: CreateVehicle, VehicleForm, AddVehicle components

2. REMOVE VIN DECODE UI:
Remove:
- "Decode VIN" button
- VIN input auto-complete/lookup functionality
- Any loading states for VIN decode
- Success/error messages for VIN decode

3. UPDATE FORM FIELDS:
Make these fields REQUIRED with dropdowns:
- Make: Dropdown populated from /api/vehicle-data/makes?year={year}
- Model: Dropdown populated from /api/vehicle-data/models?year={year}&make_id={makeId}
- Year: Dropdown populated from /api/vehicle-data/years
- Trim: Optional dropdown from /api/vehicle-data/trims
- Engine: Optional dropdown from /api/vehicle-data/engines

Make VIN field OPTIONAL (text input for reference only).

4. IMPLEMENT CASCADING DROPDOWNS:
- Year selection → loads Makes
- Make selection → loads Models
- Model selection → loads Trims
- Trim selection → loads Engines

5. UPDATE API CALLS:
Change from:
- /api/vehicles/dropdown/* (old platform proxy)

To:
- /api/vehicle-data/years
- /api/vehicle-data/makes?year={year}
- /api/vehicle-data/models?year={year}&make_id={id}

6. UPDATE FORM VALIDATION:
- Require year, make, model
- VIN optional (17 chars if provided)
- Show clear error messages for required fields

7. UPDATE USER EXPERIENCE:
- Add help text: "Select your vehicle from the dropdowns below"
- Clear dependent dropdowns when parent changes (e.g., clear Models when Make changes)
- Show loading states while fetching dropdown data

8. TEST ON MOBILE + DESKTOP:
- Dropdowns work on mobile
- Touch-friendly dropdown selection
- Responsive layout
- No horizontal scrolling

9. REMOVE VIN DECODE UTILITIES:
Search for and remove:
- VIN validation functions (if only used for decode)
- VIN formatting utilities
- API client methods for VIN decode

VERIFICATION:
- No "Decode VIN" button in UI
- Vehicle form has year/make/model dropdowns (required)
- Cascading dropdowns work correctly
- VIN field is optional
- Form validation updated
- Works on mobile and desktop
- API calls updated to /api/vehicle-data/*
- npm run build succeeds
- npm run lint passes

Return confirmation with screenshots of updated form (mobile + desktop).

Success Criteria:

✅ VIN decode UI removed
✅ Dropdowns implemented
✅ Cascading logic works
✅ Mobile + desktop tested
✅ Validation updated

Estimated Time: 2-3 hours

AGENT 4: Configuration Cleanup

Role: Remove platform service from docker-compose and configuration

Subagent Type: general-purpose

Dependencies: None (can start immediately)

Deliverables:

Updated docker-compose.yml (remove mvp-platform)
Removed environment variables
Removed secrets
Updated Traefik configuration

Prompt:

Remove the mvp-platform service from docker-compose and clean up all related configuration.

CONTEXT:
The platform service is being absorbed into the backend. The mvp-platform container will be removed, reducing from 6 to 5 containers.

TASKS:

1. UPDATE DOCKER-COMPOSE.YML:
File: /Users/egullickson/Documents/Technology/coding/motovaultpro/docker-compose.yml

Remove lines 184-227 (entire mvp-platform service definition).

This includes:
- Service: mvp-platform
- Build context: ./mvp-platform-services/vehicles
- Container name: mvp-platform
- All environment variables
- All volume mounts
- Network connections
- Health check
- Traefik labels

2. UPDATE BACKEND ENVIRONMENT:
File: docker-compose.yml (mvp-backend service)

Remove environment variable:
- PLATFORM_VEHICLES_API_URL: http://mvp-platform:8000

3. REMOVE FROM ENV FILES:
File: .env.development

Remove:
- PLATFORM_VEHICLES_API_URL=http://mvp-platform:8000

4. UPDATE BACKEND CONFIG:
File: config/app/production.yml

Remove any platform service references:
- platform_vehicles_api_url
- platform_api_key

5. DELETE SECRETS:
File: secrets/app/platform-vehicles-api-key.txt

Delete this file (no longer needed).

Update docker-compose.yml backend volumes:
Remove secret mount:
- ./secrets/app/platform-vehicles-api-key.txt:/run/secrets/platform-vehicles-api-key:ro

6. UPDATE TRAEFIK CONFIG:
File: config/traefik/middleware.yml or traefik.yml

Remove:
- Any router rules for /platform prefix
- Any platform service backends
- Platform health checks

7. UPDATE MAKEFILE:
File: Makefile

Remove or update:
- Any platform-specific commands
- Update logs command if it references mvp-platform
- Update rebuild if it specifically references platform

8. VERIFY NETWORK CONFIGURATION:
Check docker-compose.yml networks section:
- Ensure frontend, backend, database networks still defined
- Remove platform-specific networks if any

9. VERIFY VOLUME CONFIGURATION:
Check docker-compose.yml volumes section:
- Ensure mvp_postgres_data, mvp_redis_data still defined
- Remove platform-specific volumes if any

VERIFICATION:
- docker-compose.yml valid YAML (use yamllint or docker compose config)
- Only 5 services defined: mvp-traefik, mvp-frontend, mvp-backend, mvp-postgres, mvp-redis
- No references to "mvp-platform" in config files
- No references to "platform-vehicles-api"
- Secrets file removed
- docker compose config runs without errors

Return confirmation with list of modified files and line numbers.

Success Criteria:

✅ docker-compose.yml updated (5 services)
✅ Environment variables removed
✅ Secrets deleted
✅ Traefik config updated
✅ Valid YAML

Estimated Time: 1 hour

AGENT 5: Integration & Testing

Role: Integrate new vehicle-data feature with vehicles feature and create comprehensive tests

Subagent Type: general-purpose

Dependencies: Agents 1, 2 complete

Deliverables:

Vehicles feature updated to use vehicle-data feature
Unit tests for vehicle-data feature
Integration tests for full workflow
All tests passing

Prompt:

Integrate the new vehicle-data feature with the vehicles feature and create comprehensive tests.

CONTEXT:
- Agent 1 created: backend/src/features/vehicle-data/
- Agent 2 removed: VIN decode and platform integration
- Now need to connect vehicles feature to vehicle-data feature

TASKS:

1. UPDATE VEHICLES SERVICE:
File: backend/src/features/vehicles/domain/vehicles.service.ts

Add dependency:
import { VehicleDataService } from '../../vehicle-data/domain/vehicle-data.service';

Constructor:
constructor(
  private repository: VehiclesRepository,
  private vehicleData: VehicleDataService  // NEW
) {}

Update dropdown methods to use vehicleData:
- Replace platformIntegration.getMakes() → vehicleData.getMakes()
- Replace platformIntegration.getModels() → vehicleData.getModels()
- etc.

2. UPDATE VEHICLES CONTROLLER:
File: backend/src/features/vehicles/api/vehicles.controller.ts

Update dropdown route handlers to call vehicleData service.

3. UPDATE VEHICLES ROUTES:
File: backend/src/features/vehicles/api/vehicles.routes.ts

Ensure dropdown routes call updated controller methods.

4. CREATE UNIT TESTS - VEHICLE DATA:
File: backend/src/features/vehicle-data/tests/unit/vehicle-data.service.test.ts

Test:
- getYears() returns descending array
- getMakes(year) returns makes for year
- getModels(year, makeId) returns models
- Cache hits work correctly
- Cache misses query database
- Invalid parameters throw errors

Mock:
- Repository calls
- Redis calls

5. CREATE UNIT TESTS - REPOSITORY:
File: backend/src/features/vehicle-data/tests/unit/vehicle-data.repository.test.ts

Test:
- Each SQL query method
- Parameter binding
- Error handling
- Empty result sets

Mock:
- PostgreSQL pool

6. CREATE INTEGRATION TESTS:
File: backend/src/features/vehicle-data/tests/integration/vehicle-data.integration.test.ts

Test full workflow:
1. GET /api/vehicle-data/years → [2024, 2023, ...]
2. GET /api/vehicle-data/makes?year=2024 → [{id: 1, name: "Honda"}, ...]
3. GET /api/vehicle-data/models?year=2024&make_id=1 → [{id: 1, name: "Civic"}, ...]
4. GET /api/vehicle-data/trims?year=2024&model_id=1 → [{id: 1, name: "LX"}, ...]
5. GET /api/vehicle-data/engines?year=2024&trim_id=1 → [{id: 1, name: "2.0L I4"}, ...]

Test:
- Authentication required (401 without JWT)
- Invalid parameters return 400
- Caching works (second call faster)
- CORS headers present

7. UPDATE VEHICLES INTEGRATION TESTS:
File: backend/src/features/vehicles/tests/integration/vehicles.integration.test.ts

Update:
- Remove VIN decode scenarios
- Update create vehicle to include make/model/year
- Verify validation requires make/model/year
- Test dropdown endpoints still work

8. RUN ALL TESTS:
Execute:
- npm run test (all unit tests)
- npm run test:integration (all integration tests)

Fix any failures.

9. VERIFY TYPE SAFETY:
Execute:
- npm run type-check or npx tsc --noEmit

Fix any TypeScript errors.

10. RUN LINTER:
Execute:
- npm run lint

Fix any linting issues.

VERIFICATION:
- All unit tests passing
- All integration tests passing
- TypeScript compiles without errors
- Linter passes
- Vehicles feature successfully uses vehicle-data feature
- Dropdown APIs work end-to-end
- Test coverage >80% for new feature

Return test results summary and any issues found.

Success Criteria:

✅ Features integrated
✅ Unit tests complete
✅ Integration tests complete
✅ All tests passing
✅ Type-check passes
✅ Linter passes

Estimated Time: 2-3 hours

AGENT 6: Documentation Updates

Role: Update all documentation to reflect 5-container architecture

Subagent Type: general-purpose

Dependencies: Agents 1, 2, 3, 4 complete

Deliverables:

Updated architecture documentation
Updated API documentation
Updated feature documentation
Migration notes created

Prompt:

Update all documentation to reflect the new 5-container architecture and removal of platform service.

CONTEXT:
- Platform service absorbed into backend as vehicle-data feature
- VIN decoding removed
- Architecture now 5 containers (was 6)

TASKS:

1. UPDATE ARCHITECTURE OVERVIEW:
File: docs/ARCHITECTURE-OVERVIEW.md

Changes:
- Update container count: 6 → 5
- Remove mvp-platform container from list
- Add vehicle-data as backend feature module
- Update architecture diagram (remove platform container)
- Add note: "VIN decoding removed - users manually select vehicle details"

2. UPDATE VEHICLES API DOCS:
File: docs/VEHICLES-API.md

Changes:
- Remove all platform service references
- Update API endpoints from /platform/* to /api/vehicle-data/*
- Remove VIN decode endpoint documentation
- Update dropdown endpoint documentation
- Remove platform reset instructions
- Update troubleshooting section

3. UPDATE DATABASE SCHEMA DOCS:
File: docs/DATABASE-SCHEMA.md

Changes:
- Clarify vehicles schema accessed by vehicle-data feature (backend module)
- Remove VIN decode function references (f_decode_vin)
- Add note: "vehicles schema managed by vehicle-data feature"

4. UPDATE ROOT README:
File: README.md

Changes:
- Line 1-3: Change "6 containers" to "5 containers"
- Remove mvp-platform from container list
- Update quick start section (5 containers expected)

5. UPDATE CLAUDE.MD:
File: CLAUDE.md

Changes:
- Line 94-95: Update architecture description to "5 containers: Traefik, Frontend, Backend, PostgreSQL, Redis"
- Update "Integrated Platform service" to "vehicle-data feature module"
- Remove references to separate platform service

6. UPDATE AI-INDEX.MD:
File: AI-INDEX.md

Changes:
- Update container count to 5
- Update service list
- Update any platform service references

7. CREATE VEHICLE-DATA FEATURE README:
File: backend/src/features/vehicle-data/README.md

Content:
```markdown
# Vehicle Data Feature

Provides hierarchical vehicle data (makes, models, trims, engines) for the vehicles feature.

## Purpose
Replaced the separate mvp-platform Python service. Now integrated as a backend feature module.

## Architecture
- Database: vehicles schema (separate from public schema)
- Caching: Redis with 6-hour TTL
- Authentication: JWT required on all endpoints

## API Endpoints
- GET /api/vehicle-data/years
- GET /api/vehicle-data/makes?year={year}
- GET /api/vehicle-data/models?year={year}&make_id={id}
- GET /api/vehicle-data/trims?year={year}&model_id={id}
- GET /api/vehicle-data/engines?year={year}&trim_id={id}

## Database Tables
vehicles.make, vehicles.model, vehicles.model_year, vehicles.trim, vehicles.engine, vehicles.trim_engine

## Caching Strategy
Redis keys: vehicle-data:makes:{year}, etc.
TTL: 6 hours
Graceful fallback if Redis unavailable

## Notes
- VIN decoding was removed (not part of this feature)
- Users manually select vehicle details from dropdowns

UPDATE VEHICLES FEATURE README: File: backend/src/features/vehicles/README.md

Changes:

Remove VIN decode documentation
Remove platform integration references
Update vehicle creation workflow: "Users manually select make/model/year from dropdowns provided by vehicle-data feature"
Update dependencies: Add vehicle-data feature

CREATE MIGRATION NOTES: File: docs/PLATFORM-INTEGRATION-MIGRATION.md

Content:

# Platform Service Integration - Migration Notes

## Date
[Insert completion date]

## Summary
Integrated the separate mvp-platform Python service into the backend as a TypeScript feature module.

## Changes

### Architecture
- Before: 6 containers (Traefik, Frontend, Backend, PostgreSQL, Redis, Platform)
- After: 5 containers (Traefik, Frontend, Backend, PostgreSQL, Redis)

### Features Removed
- VIN decoding via NHTSA API
- VIN auto-population of vehicle details
- Separate platform container

### Features Added
- vehicle-data feature module in backend
- Manual vehicle selection workflow (dropdowns)

### Breaking Changes
- VIN decode API endpoint removed
- Vehicle creation now requires make/model/year in request
- Frontend updated to use dropdowns instead of VIN decode

### Technical Details
- Python FastAPI code converted to TypeScript/Fastify
- vehicles schema remains unchanged
- Redis caching maintained (6-hour TTL)
- API endpoints moved from /platform/* to /api/vehicle-data/*

## Rationale
Simplify architecture by reducing container count and unifying on Node.js/TypeScript stack.

## Migration Path
Single-phase cutover completed [date].

UPDATE DOCS README: File: docs/README.md

Changes:

Update feature list to include vehicle-data
Update architecture summary (5 containers)

VERIFICATION:

All references to "6 containers" changed to "5 containers"
No references to mvp-platform container
No references to VIN decode API
vehicle-data feature documented
Migration notes complete
All markdown files valid (no broken links)

Return list of files updated with line numbers changed.


**Success Criteria**:
- ✅ All architecture docs updated
- ✅ API docs updated
- ✅ Feature READMEs updated
- ✅ Migration notes created
- ✅ No references to 6 containers

**Estimated Time**: 1-2 hours

---

## AGENT 7: Container Removal & Deployment

**Role**: Final cleanup, container removal, and deployment verification

**Subagent Type**: `general-purpose`

**Dependencies**: All other agents complete

**Deliverables**:
- Platform service directory archived
- Docker images cleaned
- Deployment verified
- 5 containers running

**Prompt**:

Perform final cleanup, remove platform service, and verify deployment.

CONTEXT: All code changes complete. Ready for final cleanup and deployment.

TASKS:

ARCHIVE PLATFORM SERVICE: Move platform service to archive (don't delete from git history): mkdir -p /Users/egullickson/Documents/Technology/coding/motovaultpro/archive/platform-services/ mv /Users/egullickson/Documents/Technology/coding/motovaultpro/mvp-platform-services/vehicles/ /Users/egullickson/Documents/Technology/coding/motovaultpro/archive/platform-services/

Create archive README: File: archive/platform-services/README.md Content:

# Archived Platform Services

## vehicles/
**Archived**: [date]
**Reason**: Integrated into backend as vehicle-data feature module

This Python FastAPI service was replaced by the TypeScript vehicle-data feature in backend/src/features/vehicle-data/.

For migration details, see: docs/PLATFORM-INTEGRATION-MIGRATION.md

VERIFY DOCKER COMPOSE: Execute: docker compose config

Verify:

Valid YAML (no errors)
Exactly 5 services defined
No references to mvp-platform

STOP ALL CONTAINERS: Execute: docker compose down

Verify all containers stopped: docker ps -a

CLEAN UP DOCKER IMAGES: Remove old platform image: docker image rm motovaultpro-mvp-platform 2>/dev/null || true
REBUILD BACKEND: Execute: docker compose build mvp-backend

Verify build succeeds without errors.

START ALL CONTAINERS: Execute: docker compose up -d

Verify 5 containers start: docker ps

Expected:

mvp-traefik
mvp-frontend
mvp-backend
mvp-postgres
mvp-redis

VERIFY HEALTH CHECKS: Wait 60 seconds for startup.

Check health: docker compose ps

All containers should show "healthy" or "running".

VERIFY DATABASE MIGRATIONS: Check vehicles schema exists: docker compose exec mvp-postgres psql -U postgres -d motovaultpro -c "\dn"

Should see "vehicles" schema.

Check tables exist: docker compose exec mvp-postgres psql -U postgres -d motovaultpro -c "\dt vehicles.*"

Should see: make, model, model_year, trim, engine, trim_engine

TEST VEHICLE-DATA ENDPOINTS: Execute (requires JWT token): curl http://localhost/api/vehicle-data/years

Expected: [2024, 2023, ...]

Execute: curl http://localhost/api/vehicle-data/makes?year=2024

Expected: {"makes": [{id: 1, name: "Honda"}, ...]}

TEST FRONTEND: Open: http://localhost

Navigate to vehicles page. Verify:

Dropdowns load (years, makes, models)
Can create vehicle by selecting from dropdowns
No VIN decode button visible
Vehicle creation works

MONITOR LOGS: Execute: docker compose logs -f mvp-backend

Watch for:

No errors on startup
Vehicle-data endpoints responding
No calls to mvp-platform (should be gone)

VERIFY REDIS CACHING: Execute: docker compose exec mvp-redis redis-cli

Run: KEYS vehicle-data:*

After making API calls, should see cached keys.

Run: GET vehicle-data:makes:2024

Should see JSON data.

PERFORMANCE CHECK: Test response times: time curl http://localhost/api/vehicle-data/years

Should be <500ms after cache warm-up.

FINAL VERIFICATION CHECKLIST:

5 containers running (not 6)
All health checks passing
Vehicle-data API endpoints responding
Redis caching working
Frontend loads without errors
Vehicle creation works
No platform service references in logs
No errors in docker logs

VERIFICATION: Return:

Output of: docker ps (should show 5 containers)
Output of: curl http://localhost/api/vehicle-data/years
Confirmation that frontend works
Any errors encountered
Performance metrics (response times)

If any issues found, provide rollback instructions.


**Success Criteria**:
- ✅ Platform service archived
- ✅ 5 containers running
- ✅ Health checks passing
- ✅ APIs responding
- ✅ Frontend working
- ✅ No errors in logs

**Estimated Time**: 1-2 hours

---

## Dependency Graph

Wave 1 (Parallel): ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │ Agent 4 │ │ Backend │ │ VIN Rem │ │ VIN Rem │ │Configuration │ │ Feature │ │ Backend │ │ Frontend │ │ Cleanup │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ └─────────┬───────┴─────────────────┴─────────────────┘ │ Wave 2 (Parallel): │ ┌────────▼────────┐ ┌─────────────────┐ │ Agent 5 │ │ Agent 6 │ │ Integration │ │ Documentation │ │ & Testing │ │ Updates │ └────────┬────────┘ └────────┬────────┘ │ │ Wave 3: └──────────┬─────────┘ │ ┌──────────▼────────┐ │ Agent 7 │ │ Container │ │ Removal & │ │ Deployment │ └───────────────────┘


---

## Execution Instructions

### Start Wave 1 (4 agents in parallel):
```bash
# Spawn all 4 agents simultaneously
/task agent1_prompt
/task agent2_prompt
/task agent3_prompt
/task agent4_prompt

Wait for Wave 1 Completion

Monitor all 4 agents. When all report completion:

Review deliverables
Verify no conflicts
Commit changes from Wave 1

Start Wave 2 (2 agents in parallel):

# Spawn 2 agents simultaneously
/task agent5_prompt
/task agent6_prompt

Wait for Wave 2 Completion

When both agents complete:

Run all tests
Review documentation
Commit changes from Wave 2

Start Wave 3 (1 agent):

# Spawn final agent
/task agent7_prompt

Final Verification

When Agent 7 completes:

Verify 5 containers running
Test all functionality
Create git tag: v1.0-platform-integrated

Rollback Plan

If critical issues during deployment:

Restore docker-compose.yml:
```
git restore docker-compose.yml
```

Restore platform service:

mv archive/platform-services/vehicles/ mvp-platform-services/

Rebuild containers:

docker compose down
docker compose up -d

Revert backend changes:

git revert HEAD~[n]  # Revert last n commits

Rebuild backend:

docker compose build mvp-backend
docker compose restart mvp-backend

Success Metrics

✅ 5 containers running (down from 6)
✅ All automated tests passing
✅ Vehicle dropdown APIs <500ms response time
✅ Redis cache hit rate >80% after warm-up
✅ Zero errors in logs after 1 hour
✅ Frontend vehicle creation works on mobile + desktop
✅ All documentation updated
✅ TypeScript compiles without warnings
✅ Linter passes

Estimated Timeline

Total: 6-8 hours with parallel execution

Wave	Duration	Agents
Wave 1	3-4 hours	4 parallel
Wave 2	2-3 hours	2 parallel
Wave 3	1-2 hours	1 sequential

Sequential Execution: 12-16 hours Parallel Execution: 6-8 hours Time Saved: 50%

Notes

Each agent is independent in Wave 1 (no conflicts expected)
Wave 2 depends on Wave 1 code changes
Wave 3 is deployment only (must be last)
Use feature branches for each wave if needed
Test after each wave before proceeding
Commit after each wave for easy rollback

Agent Communication Protocol

Agents should report:

Start: "Agent [N] starting [task]"
Progress: Regular updates every 30 minutes
Blockers: Immediate report if stuck
Completion: "Agent [N] complete - [deliverables]"
Handoff: Files created/modified for next wave

Coordinator (you) should:

Monitor all agents in parallel
Resolve conflicts between agents
Gate Wave 2 until Wave 1 100% complete
Gate Wave 3 until Wave 2 100% complete
Make final deployment decision

32 KiB Raw Blame History

Platform Service Integration - Agent Execution Manifest

Overview

Execution Waves

Wave 1: Parallel Foundation (4 agents)

Wave 2: Integration & Testing (2 agents)

Wave 3: Final Cleanup (1 agent)

Agent Definitions

AGENT 1: Backend Feature Creator

AGENT 2: VIN Removal - Backend

AGENT 3: VIN Removal - Frontend

AGENT 4: Configuration Cleanup

AGENT 5: Integration & Testing

AGENT 6: Documentation Updates

Wait for Wave 1 Completion

Start Wave 2 (2 agents in parallel):

Wait for Wave 2 Completion

Start Wave 3 (1 agent):

Final Verification

Rollback Plan

Success Metrics

Estimated Timeline

Notes

Agent Communication Protocol

32 KiB

Raw Blame History