motovaultpro/docs/PLATFORM-INTEGRATION-AGENTS.md

# 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
```

8. 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

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

Content:
```markdown
# 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].
```

10. 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:

1. 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:
```markdown
# 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
```

2. VERIFY DOCKER COMPOSE:
Execute:
docker compose config

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

3. STOP ALL CONTAINERS:
Execute:
docker compose down

Verify all containers stopped:
docker ps -a

4. CLEAN UP DOCKER IMAGES:
Remove old platform image:
docker image rm motovaultpro-mvp-platform 2>/dev/null || true

5. REBUILD BACKEND:
Execute:
docker compose build mvp-backend

Verify build succeeds without errors.

6. 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

7. VERIFY HEALTH CHECKS:
Wait 60 seconds for startup.

Check health:
docker compose ps

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

8. 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

9. 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"}, ...]}

10. 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

11. 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)

12. 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.

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

Should be <500ms after cache warm-up.

14. 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):
```bash
# 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):
```bash
# 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:

1. **Restore docker-compose.yml**:
   ```bash
   git restore docker-compose.yml
   ```

2. **Restore platform service**:
   ```bash
   mv archive/platform-services/vehicles/ mvp-platform-services/
   ```

3. **Rebuild containers**:
   ```bash
   docker compose down
   docker compose up -d
   ```

4. **Revert backend changes**:
   ```bash
   git revert HEAD~[n]  # Revert last n commits
   ```

5. **Rebuild backend**:
   ```bash
   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:
1. **Start**: "Agent [N] starting [task]"
2. **Progress**: Regular updates every 30 minutes
3. **Blockers**: Immediate report if stuck
4. **Completion**: "Agent [N] complete - [deliverables]"
5. **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