204 lines
6.6 KiB
Markdown
204 lines
6.6 KiB
Markdown
# 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
|