# MotoVaultPro Simplification - AI Agent Coordination

## Overview

This directory contains comprehensive documentation for executing the MotoVaultPro simplification using multiple AI agents working in parallel. The goal is to transform the current 14-container microservices architecture into a streamlined 6-container stack.

## Architecture Transformation

### Current State (14 containers)
- traefik, admin-frontend, admin-backend, admin-postgres, admin-redis, admin-minio
- mvp-platform-landing, mvp-platform-tenants, mvp-platform-vehicles-api
- platform-postgres, platform-redis, mvp-platform-vehicles-db, mvp-platform-vehicles-redis, mvp-platform-vehicles-etl

### Target State (6 containers)
1. **mvp-traefik** - Reverse proxy and SSL termination
2. **mvp-frontend** - React application
3. **mvp-backend** - Fastify API server
4. **mvp-postgres** - PostgreSQL database
5. **mvp-redis** - Redis cache
6. **mvp-platform** - Simplified vehicles service

## Key Simplifications

1. **Remove Multi-Tenancy** - Application already uses user_id isolation
2. **Replace MinIO** - Use filesystem storage with mounted volume
3. **Consolidate Databases** - 3 PostgreSQL instances → 1 instance
4. **Consolidate Caches** - 3 Redis instances → 1 instance
5. **Simplify Platform Service** - Remove ETL pipeline and MSSQL dependency
6. **Consistent Naming** - All services use mvp-* prefix

## Documentation Structure

### Core Documentation
- **README.md** (this file) - Master coordination document
- **AGENT-MANIFEST.md** - Agent assignments and dependency graph
- **DEPENDENCY-GRAPH.md** - Visual phase dependencies
- **FILE-MANIFEST.md** - Complete file change inventory
- **VALIDATION-CHECKLIST.md** - Success criteria and validation steps
- **ROLLBACK-STRATEGY.md** - Rollback procedures
- **EXECUTION-STATE.json** - Shared state tracking (runtime)

### Phase Documentation (11 files)
- **PHASE-01-DOCKER-COMPOSE.md** - Container renaming and docker-compose.yml
- **PHASE-02-REMOVE-TENANT.md** - Multi-tenant architecture removal
- **PHASE-03-FILESYSTEM-STORAGE.md** - MinIO to filesystem migration
- **PHASE-04-CONFIG-CLEANUP.md** - Configuration and secrets cleanup
- **PHASE-05-NETWORK-SIMPLIFICATION.md** - Network architecture updates
- **PHASE-06-BACKEND-UPDATES.md** - Backend code updates
- **PHASE-07-DATABASE-UPDATES.md** - Database schema updates
- **PHASE-08-PLATFORM-SERVICE.md** - mvp-platform service simplification
- **PHASE-09-DOCUMENTATION.md** - Documentation updates
- **PHASE-10-FRONTEND-UPDATES.md** - Frontend updates
- **PHASE-11-TESTING.md** - Testing and validation

## Agent Execution Strategy

### 8 Specialized Agents

1. **infra-agent** - Phases 1, 5, 7 (Docker, networks, databases)
2. **backend-agent** - Phases 2, 6 (Backend code)
3. **storage-agent** - Phase 3 (MinIO to filesystem)
4. **platform-agent** - Phase 8 (mvp-platform service)
5. **config-agent** - Phase 4 (Configuration cleanup)
6. **frontend-agent** - Phase 10 (Frontend updates)
7. **docs-agent** - Phase 9 (Documentation)
8. **test-agent** - Phase 11 (Testing and validation)

### Execution Waves

**Wave 1 (Parallel - No Dependencies):**
- config-agent (Phase 4)
- docs-agent (Phase 9)

**Wave 2 (Parallel - After Wave 1):**
- infra-agent starts (Phase 1)
- backend-agent starts (Phase 2)
- storage-agent starts (Phase 3)

**Wave 3 (Parallel - After Wave 2):**
- infra-agent continues (Phases 5, 7)
- backend-agent continues (Phase 6)
- platform-agent starts (Phase 8)

**Wave 4 (Sequential):**
- frontend-agent (Phase 10)

**Wave 5 (Sequential - Validates Everything):**
- test-agent (Phase 11)

## Getting Started

### For Orchestration AI

1. **Read Core Documentation:**
   - AGENT-MANIFEST.md - Understand agent assignments
   - DEPENDENCY-GRAPH.md - Understand execution order
   - FILE-MANIFEST.md - Understand file changes

2. **Spawn Agents in Waves:**
   ```
   Wave 1: config-agent, docs-agent
   Wave 2: infra-agent, backend-agent, storage-agent (wait for Wave 1)
   Wave 3: Continue Wave 2 agents, add platform-agent
   Wave 4: frontend-agent (wait for backend-agent)
   Wave 5: test-agent (wait for all)
   ```

3. **Monitor Execution:**
   - Track EXECUTION-STATE.json for phase completion
   - Watch for conflict notifications
   - Validate each wave before starting next

### For Individual Agents

1. **Read Assignment:**
   - Check AGENT-MANIFEST.md for your phases
   - Review DEPENDENCY-GRAPH.md for prerequisites

2. **Execute Phases:**
   - Read PHASE-*.md for detailed instructions
   - Follow step-by-step procedures
   - Run validation checks
   - Update EXECUTION-STATE.json

3. **Coordinate:**
   - Check for file locks before modifying
   - Report conflicts in AGENT-LOG.md
   - Wait for dependent phases to complete

## Success Criteria

### Per-Phase Success
- All validation checks pass
- No file conflicts
- Changes follow coding standards

### Integration Success
- `make rebuild` succeeds
- All 6 containers start healthy
- `make test` passes (all tests green)
- No functionality regressions

### Final Acceptance
- 14 → 6 containers running
- 5 → 3 networks configured
- Multi-tenant code removed
- MinIO replaced with filesystem
- Platform service simplified
- Documentation updated
- All tests passing

## Timeline Estimate

**Sequential Execution:** ~8-12 hours
**Parallel Execution (8 agents):** ~2-3 hours (60-70% time reduction)

## Risk Mitigation

1. **Git Branching:** Each phase works on feature branch
2. **Incremental Validation:** Test after each phase
3. **Rollback Capability:** Each phase documents rollback
4. **Conflict Detection:** File locks prevent concurrent edits
5. **State Tracking:** EXECUTION-STATE.json tracks progress

## Communication Protocols

### State Updates
Agents update EXECUTION-STATE.json when:
- Starting a phase
- Completing a phase
- Encountering conflicts
- Requiring coordination

### Conflict Resolution
If file conflict detected:
1. Agent creates lock file
2. Other agent waits
3. First agent completes work
4. Lock released
5. Second agent proceeds

### Error Handling
If phase fails:
1. Agent reports in EXECUTION-STATE.json
2. Dependent phases are blocked
3. Orchestrator decides: retry or rollback
4. Follow ROLLBACK-STRATEGY.md if needed

## Next Steps

1. **Orchestration AI:** Review AGENT-MANIFEST.md
2. **Spawn Wave 1:** config-agent and docs-agent
3. **Monitor Progress:** Track EXECUTION-STATE.json
4. **Spawn Wave 2:** After Wave 1 completes
5. **Continue Through Waves:** Until test-agent passes

## Questions or Issues

Refer to specific phase documentation for detailed guidance. Each PHASE-*.md file contains:
- Step-by-step instructions
- Validation criteria
- Rollback procedures
- Conflict resolution guidance