Redesign

2025-11-01 21:27:42 -05:00
parent 20953c6dee
commit 046c66fc7d
203 changed files with 5699 additions and 404943 deletions
--- a/docs/redesign/PHASE-01-DOCKER-COMPOSE.md
+++ b/docs/redesign/PHASE-01-DOCKER-COMPOSE.md
@@ -0,0 +1,402 @@
+# Phase 1: Docker Compose Simplification
+
+## Agent Assignment
+**Primary Agent:** infra-agent
+**Collaborators:** None
+**Estimated Duration:** 25-30 minutes
+
+## Prerequisites
+- **Phases that must complete first:** Phase 4 (Config Cleanup)
+- **Files that must not be locked:** docker-compose.yml
+- **System state:** All containers stopped or ready for restart
+
+## Objectives
+
+1. Rename all services from `admin-*` to `mvp-*` naming convention
+2. Rename `mvp-platform-vehicles-api` to `mvp-platform`
+3. Remove 8 unnecessary platform service containers
+4. Add filesystem volume mount for document storage
+5. Update all Traefik labels for new service names
+6. Ensure 6 containers total in final configuration
+
+## Files to Modify
+
+### docker-compose.yml
+**Action:** Major restructure
+**Location:** `/docker-compose.yml`
+
+## Step-by-Step Instructions
+
+### Step 1: Stop All Running Containers
+```bash
+# Stop all services
+docker compose down
+
+# Verify all stopped
+docker compose ps
+# Expected: No containers listed
+```
+
+### Step 2: Backup Current docker-compose.yml
+```bash
+# Create backup
+cp docker-compose.yml docker-compose.yml.backup-phase1-$(date +%Y%m%d)
+
+# Verify backup
+ls -la docker-compose.yml*
+```
+
+### Step 3: Rename Services
+
+**Services to Rename:**
+
+```yaml
+# OLD → NEW
+traefik → mvp-traefik
+admin-frontend → mvp-frontend
+admin-backend → mvp-backend
+admin-postgres → mvp-postgres
+admin-redis → mvp-redis
+mvp-platform-vehicles-api → mvp-platform
+```
+
+**Find and Replace:**
+```bash
+# In docker-compose.yml, replace:
+sed -i.bak 's/admin-frontend/mvp-frontend/g' docker-compose.yml
+sed -i.bak 's/admin-backend/mvp-backend/g' docker-compose.yml
+sed -i.bak 's/admin-postgres/mvp-postgres/g' docker-compose.yml
+sed -i.bak 's/admin-redis/mvp-redis/g' docker-compose.yml
+sed -i.bak 's/mvp-platform-vehicles-api/mvp-platform/g' docker-compose.yml
+
+# Note: traefik already has correct name
+```
+
+### Step 4: Remove Platform Services
+
+**Delete these entire service definitions from docker-compose.yml:**
+
+```yaml
+admin-minio:              # DELETE entire block
+mvp-platform-landing:     # DELETE entire block
+mvp-platform-tenants:     # DELETE entire block
+platform-postgres:        # DELETE entire block
+platform-redis:           # DELETE entire block
+mvp-platform-vehicles-db: # DELETE entire block
+mvp-platform-vehicles-redis: # DELETE entire block
+mvp-platform-vehicles-etl:   # DELETE entire block
+```
+
+### Step 5: Add Filesystem Volume Mount
+
+**Add to mvp-backend service:**
+
+```yaml
+mvp-backend:
+  # ... existing config ...
+  volumes:
+    - ./config/app/production.yml:/app/config/production.yml:ro
+    - ./secrets/app/postgres-password.txt:/run/secrets/postgres-password:ro
+    - ./data/documents:/app/data/documents  # ADD THIS LINE
+  # ... rest of config ...
+```
+
+**Create directory on host:**
+```bash
+mkdir -p ./data/documents
+chmod 755 ./data/documents
+```
+
+### Step 6: Update Volume Names
+
+**Find and replace volume names:**
+
+```yaml
+# OLD volumes:
+admin_postgres_data
+admin_redis_data
+admin_minio_data  # DELETE
+
+# NEW volumes:
+mvp_postgres_data
+mvp_redis_data
+```
+
+**At bottom of docker-compose.yml:**
+```yaml
+volumes:
+  mvp_postgres_data:
+    name: mvp_postgres_data
+  mvp_redis_data:
+    name: mvp_redis_data
+  # Remove admin_minio_data
+```
+
+### Step 7: Update Traefik Labels
+
+**For mvp-frontend:**
+```yaml
+mvp-frontend:
+  labels:
+    - "traefik.enable=true"
+    - "traefik.http.routers.mvp-frontend.rule=Host(`admin.motovaultpro.com`)"  # Updated
+    - "traefik.http.routers.mvp-frontend.entrypoints=websecure"
+    - "traefik.http.routers.mvp-frontend.tls=true"
+    - "traefik.http.services.mvp-frontend.loadbalancer.server.port=80"  # Updated service name
+```
+
+**For mvp-backend:**
+```yaml
+mvp-backend:
+  labels:
+    - "traefik.enable=true"
+    - "traefik.http.routers.mvp-backend.rule=Host(`admin.motovaultpro.com`) && PathPrefix(`/api`)"
+    - "traefik.http.routers.mvp-backend.entrypoints=websecure"
+    - "traefik.http.routers.mvp-backend.tls=true"
+    - "traefik.http.services.mvp-backend.loadbalancer.server.port=3001"  # Updated service name
+```
+
+**For mvp-platform:**
+```yaml
+mvp-platform:
+  labels:
+    - "traefik.enable=true"
+    - "traefik.http.routers.mvp-platform.rule=Host(`admin.motovaultpro.com`) && PathPrefix(`/platform`)"
+    - "traefik.http.routers.mvp-platform.entrypoints=websecure"
+    - "traefik.http.routers.mvp-platform.tls=true"
+    - "traefik.http.services.mvp-platform.loadbalancer.server.port=8000"  # Updated service name
+```
+
+### Step 8: Update Internal Service References
+
+**In mvp-backend environment variables or config:**
+```yaml
+mvp-backend:
+  environment:
+    - DATABASE_HOST=mvp-postgres  # Updated from admin-postgres
+    - REDIS_HOST=mvp-redis        # Updated from admin-redis
+    - PLATFORM_VEHICLES_API_URL=http://mvp-platform:8000  # Updated
+```
+
+**In mvp-platform:**
+```yaml
+mvp-platform:
+  environment:
+    - DATABASE_HOST=mvp-postgres  # Will use same postgres as backend
+    - REDIS_HOST=mvp-redis        # Will use same redis as backend
+```
+
+### Step 9: Validate docker-compose.yml
+
+```bash
+# Validate syntax
+docker compose config
+
+# Expected: No errors, valid YAML output
+
+# Check service count
+docker compose config --services | wc -l
+# Expected: 6
+```
+
+### Step 10: Update .env if Needed
+
+**Ensure .env references new service names:**
+```bash
+# .env should have:
+DATABASE_URL=postgresql://postgres:password@mvp-postgres:5432/motovaultpro
+REDIS_URL=redis://mvp-redis:6379
+PLATFORM_VEHICLES_API_URL=http://mvp-platform:8000
+```
+
+### Step 11: Start Services
+
+```bash
+# Build and start all containers
+docker compose up -d --build
+
+# Check status
+docker compose ps
+# Expected: 6 services running
+
+# Expected services:
+# - mvp-traefik
+# - mvp-frontend
+# - mvp-backend
+# - mvp-postgres
+# - mvp-redis
+# - mvp-platform
+```
+
+### Step 12: Verify Traefik Dashboard
+
+```bash
+# Access Traefik dashboard
+open http://localhost:8080
+
+# Check discovered services
+curl -s http://localhost:8080/api/http/services | jq -r '.[].name'
+# Expected to see: mvp-frontend, mvp-backend, mvp-platform
+
+# Check routers
+curl -s http://localhost:8080/api/http/routers | jq -r '.[].name'
+# Expected to see: mvp-frontend, mvp-backend, mvp-platform routers
+```
+
+## Validation Criteria
+
+### Container Validation
+- [ ] Exactly 6 containers running
+- [ ] All containers have "healthy" or "running" status
+- [ ] No "admin-*" named containers (except in volumes)
+- [ ] mvp-platform exists (not mvp-platform-vehicles-api)
+
+**Validation Command:**
+```bash
+docker compose ps --format "table {{.Service}}\t{{.Status}}"
+```
+
+### Service Validation
+- [ ] mvp-traefik accessible at localhost:8080
+- [ ] mvp-frontend accessible at https://admin.motovaultpro.com
+- [ ] mvp-backend accessible at https://admin.motovaultpro.com/api/health
+- [ ] mvp-postgres accepting connections
+- [ ] mvp-redis accepting connections
+- [ ] mvp-platform accessible (internal)
+
+**Validation Commands:**
+```bash
+# Test Traefik
+curl -s http://localhost:8080/api/version | jq
+
+# Test backend health
+curl -s -k https://admin.motovaultpro.com/api/health
+
+# Test postgres
+docker compose exec mvp-postgres pg_isready -U postgres
+
+# Test redis
+docker compose exec mvp-redis redis-cli ping
+# Expected: PONG
+
+# Test platform service (internal)
+docker compose exec mvp-backend curl http://mvp-platform:8000/health
+```
+
+### Volume Validation
+- [ ] mvp_postgres_data volume exists
+- [ ] mvp_redis_data volume exists
+- [ ] ./data/documents directory exists and is writable
+- [ ] No admin_minio_data volume
+
+**Validation Commands:**
+```bash
+# Check volumes
+docker volume ls | grep mvp
+# Expected: mvp_postgres_data, mvp_redis_data
+
+# Check filesystem mount
+docker compose exec mvp-backend ls -la /app/data/documents
+# Expected: Directory exists, writable
+
+# Verify no MinIO volume
+docker volume ls | grep minio
+# Expected: Empty (no results)
+```
+
+### Network Validation (Phase 5 will simplify further)
+- [ ] Services can communicate internally
+- [ ] Traefik can route to all services
+- [ ] No network errors in logs
+
+**Validation Commands:**
+```bash
+# Test internal communication
+docker compose exec mvp-backend ping -c 1 mvp-postgres
+docker compose exec mvp-backend ping -c 1 mvp-redis
+docker compose exec mvp-backend ping -c 1 mvp-platform
+
+# Check logs for network errors
+docker compose logs mvp-backend | grep -i "network\|connection"
+# Expected: No critical errors
+```
+
+## Rollback Procedure
+
+If validation fails:
+
+```bash
+# 1. Stop containers
+docker compose down
+
+# 2. Restore backup
+cp docker-compose.yml.backup-phase1-YYYYMMDD docker-compose.yml
+
+# 3. Restart with original config
+docker compose up -d
+
+# 4. Verify rollback
+docker compose ps
+# Expected: 14 containers (original state)
+```
+
+See ROLLBACK-STRATEGY.md Phase 1 section for detailed procedure.
+
+## Dependencies on Other Phases
+
+### Blocks These Phases:
+- Phase 5 (Network Simplification) - needs new service names
+- Phase 7 (Database Updates) - needs new container names
+- Phase 8 (Platform Service) - needs new mvp-platform name
+
+### Blocked By:
+- Phase 4 (Config Cleanup) - needs clean configuration first
+
+## Estimated Duration
+**25-30 minutes**
+- Backup and preparation: 5 minutes
+- Service renaming: 10 minutes
+- Validation: 10 minutes
+- Troubleshooting buffer: 5 minutes
+
+## Conflict Zones
+**None** - This phase exclusively owns docker-compose.yml during execution.
+
+## Success Indicators
+1. `docker compose config` validates successfully
+2. All 6 containers start and reach healthy status
+3. Traefik dashboard shows 3 services
+4. Application accessible via browser
+5. No errors in container logs
+
+## Update EXECUTION-STATE.json
+
+```json
+{
+  "phases": {
+    "1": {
+      "status": "in_progress",
+      "started_at": "[timestamp]",
+      "agent": "infra-agent"
+    }
+  }
+}
+```
+
+**On completion:**
+```json
+{
+  "phases": {
+    "1": {
+      "status": "completed",
+      "started_at": "[timestamp]",
+      "completed_at": "[timestamp]",
+      "duration_minutes": 28,
+      "validation_passed": true
+    }
+  }
+}
+```
+
+## Next Phase
+After successful completion, infra-agent can proceed to Phase 5 (Network Simplification), and platform-agent can start Phase 8 (Platform Service Simplification).