MVP Version Cleanup and Fresh Start Guide

Status: Complete
Purpose: Reusable guide for transitioning between MVP versions (v1→v2, v2→v3, etc.)
Use Case: Clean slate preparation for autonomous builds while preserving all valuable documentation

Overview

This guide provides comprehensive procedures for cleanly shutting down an MVP version and preparing for the next autonomous build. It ensures all valuable documentation and lessons learned are preserved while completely removing build artifacts and running services.

What This Guide Does:

Documents external service credentials for reuse
Safely removes MVP application and services
Preserves all documentation and research
Prepares clean environment for next version
Provides rollback procedures if needed

When to Use This Guide:

Transitioning from any MVP version to the next (v1→v2, v2→v3, etc.)
Preparing for a fresh autonomous build
Cleaning up after failed or incomplete builds
Archiving completed MVP versions

Pre-Cleanup Checklist

1. Documentation Verification

All /docs/ markdown files are complete and current
/docs/build-logs/build-vX/ contains complete lessons learned
/docs/private/guides/ framework guides are up to date
/docs/private/prompts/ contain enhanced framework versions
/html/ website documentation is generated and current

2. External Service Documentation

All external service credentials documented (see Section 3)
Domain and email configurations recorded
API keys and access tokens saved
Database connection details recorded
Third-party service accounts documented

3. Build Artifact Identification

Identify what will be removed:

MVP application directory (/nudgecampaign-mvp/ or equivalent)
Docker containers and volumes
Root-level node_modules/ and dependencies
Temporary files (logs, backups, dev artifacts)
Running services and port allocations

External Service Credentials Documentation

Email Services

# Postmark Configuration (Production)
POSTMARK_SERVER_API_TOKEN=58c0f839-45de-443e-b0ac-4a8dfc18cfec
POSTMARK_FROM_EMAIL=lindsay@knowcode.tech
POSTMARK_FROM_NAME="Lindsay from NudgeCampaign"

# Domain Configuration
Domain: knowcode.tech
Verified Sender: lindsay@knowcode.tech
Message Stream: marketing

Database Services

# Development Database (Docker)
POSTGRES_PASSWORD=postgres
DATABASE_URL=postgresql://postgres:postgres@localhost:54322/postgres

# Supabase Development Keys
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU
NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321

Automation Services

# n8n Configuration
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=password
N8N_URL=http://localhost:5678

Development Services

# MailDev (Development Email Testing)
MAILDEV_URL=http://localhost:1080
SMTP_HOST=maildev
SMTP_PORT=1025

# Redis Cache
REDIS_URL=redis://localhost:6379

External Service Accounts

Postmark Account: https://postmarkapp.com (linked to knowcode.tech domain)
Supabase Account: https://supabase.io (for production database hosting)
Domain Management: knowcode.tech domain configuration
Docker Hub: For container images and deployment

🧹 Complete Cleanup Procedures

Phase 1: Service Shutdown

1.1 Docker Services Shutdown (Enhanced with V3 Lessons)

🔴 CRITICAL (V3 Lesson #8): Stop previous version containers BEFORE new deployments to prevent port conflicts.

# Navigate to CURRENT VERSION directory (V3 Lesson #7)
# Each version should have its own directory: nudgecampaign-mvp-v2, nudgecampaign-mvp-v3, etc.
cd nudgecampaign-mvp-v[CURRENT_VERSION]

# IMPORTANT: Check what's currently running
docker ps --format "table {{.Names}}\t{{.Ports}}\t{{.Status}}"

# Stop all running containers for this version
docker-compose down

# For complete cleanup including volumes (DESTRUCTIVE)
docker-compose down -v --remove-orphans

# Verify all containers stopped
docker ps | grep nudgecampaign
# Should return nothing

# Clean up Docker volumes
docker volume ls | grep nudgecampaign
docker volume rm $(docker volume ls -q | grep nudgecampaign) 2>/dev/null || true

# IMPORTANT (V3 Lesson #25): Use 'docker compose up -d' for restart, not 'docker compose restart'
# when you need to apply new environment variables

1.2 Process and Port Cleanup (V3 Lesson #12)

Port Management Strategy: Either stop all previous versions OR use version-specific port ranges.

# Check for any processes using common ports
lsof -i :3000    # Next.js app
lsof -i :3001    # Development server  
lsof -i :3002    # Alternative port (if using version-specific)
lsof -i :5678    # n8n
lsof -i :54321   # Supabase Kong
lsof -i :54322   # PostgreSQL
lsof -i :54323   # Supabase Studio
lsof -i :54332   # Alternative PostgreSQL (version-specific)
lsof -i :6379    # Redis
lsof -i :1080    # MailDev
lsof -i :1025    # MailDev SMTP

# Kill any remaining processes if found
# kill -9 [PID]

# Alternative: Use version-specific ports in docker-compose
# v2: 3001, 54322, 5678
# v3: 3002, 54332, 5679
# This allows parallel development but requires port mapping updates

Phase 2: Application Removal

2.1 MVP Application Directory Removal (V3 Lesson #7)

# Navigate to project root
cd /Users/lindsaysmith/Documents/lambda1.nosync/nudge-campaign

# IMPORTANT: Use version-specific directories to prevent conflicts
ls -la | grep nudgecampaign-mvp
# Should show: nudgecampaign-mvp-v2/, nudgecampaign-mvp-v3/, etc.

# CRITICAL: Verify documentation is preserved BEFORE removal
ls -la docs/build-logs/
ls -la docs/private/guides/
ls -la html/

# Remove SPECIFIC VERSION directory (not all versions!)
rm -rf nudgecampaign-mvp-v[VERSION_TO_REMOVE]/
# ⚠️  DESTRUCTIVE: This removes entire application

# Keep other versions for reference if needed

2.2 Root-Level Cleanup (Enhanced with V3 Lessons)

# Remove root-level node_modules if present
rm -rf node_modules/

# IMPORTANT (V3 Lesson #17): Clean up .dockerignore issues
# Check for accidentally created directories instead of files
ls -la | grep -E "postcss.config.js|kong.yml|tailwind.config.js"
# If any show as directories (d--------), remove them:
rm -rf postcss.config.js/ kong.yml/ tailwind.config.js/ 2>/dev/null

# Remove temporary and log files
rm -f dev-server.log
rm -f *.log
rm -rf .next/
rm -rf .npm/

# Remove backup files
rm -f *.backup.*
rm -rf *-backup-*/

# Clean Docker build cache (V3 Lesson #16)
docker system prune -f
docker builder prune -f

2.3 Docker-Specific Cleanup (V3 Lessons #9-#19)

# CRITICAL: Remove orphaned configuration files/directories
# V3 Lesson #9: Configuration files accidentally created as directories
find . -type d -name "*.yml" -o -type d -name "*.yaml" -o -type d -name "*.js" -o -type d -name "*.json" | while read dir; do
  echo "Found directory that should be a file: $dir"
  rm -rf "$dir"
done

# Clean up Docker images from this version
docker images | grep nudgecampaign-mvp-v[VERSION] | awk '{print $3}' | xargs docker rmi -f 2>/dev/null || true

# Remove dangling images
docker image prune -f

# Clean up build cache
docker buildx prune -f

# V3 Lesson #11: Check for specific version tags that may have changed
docker images | grep "supabase/studio" | grep -v "latest"
# Remove old specific versions if present

Phase 3: Documentation Preservation Verification

3.1 Verify Documentation Integrity

# Verify docs directory structure
ls -la docs/
ls -la docs/build-logs/build-v1/
ls -la docs/private/guides/
ls -la docs/private/prompts/

# Verify HTML documentation
ls -la html/

# Check for any missing critical files
find docs/ -name "*.md" -type f | wc -l
# Should show significant number of markdown files

# Verify build logs are complete
ls -la docs/build-logs/build-v1/
# Should contain: lessons-learned.md, gaps-analysis.md, service-access-guide.md, etc.

3.2 Framework Documentation Check

# Verify framework v2 is present
ls -la docs/private/prompts/autonomous-mvp-framework-v2.md

# Verify all guides are present
ls -la docs/private/guides/development/
ls -la docs/private/guides/research/
ls -la docs/private/guides/testing/

# Check for SaaS multi-tenancy guide
ls -la docs/private/guides/development/saas-multi-tenancy-development-guide.md

Cleanup Verification Checklist

Environment Verification

No Docker containers running: docker ps shows no nudgecampaign containers
No Docker volumes remaining: docker volume ls shows no nudgecampaign volumes
Ports are free: lsof -i :3000,3001,5678,54321,54322,54323 shows no processes
MVP directory removed: No nudgecampaign-mvp/ or equivalent directory exists
Root cleanup complete: No temporary files, logs, or node_modules at root level

Documentation Preservation

All docs preserved: /docs/ directory intact with all markdown files
HTML website preserved: /html/ directory intact and complete
Build logs preserved: /docs/build-logs/build-v1/ contains all lessons learned
Framework guides preserved: All /docs/private/guides/ documentation intact
Enhanced framework preserved: autonomous-mvp-framework-v2.md and research prompts saved

External Service Documentation

Credentials documented: All service credentials saved in this guide
Environment template ready: Can recreate .env files for next version
Service accounts accessible: Can access Postmark, domain management, etc.
API keys functional: All external service integrations ready for reuse

Docker Best Practices for Next Version (V3/V4 Lessons)

Critical Docker Setup for New Version

Based on 30+ lessons from V3 Docker deployment, follow these practices:

1. Essential Files to Create First

# MANDATORY: Create .dockerignore BEFORE building (V3 Lesson #17)
cat > .dockerignore << 'EOF'
node_modules
.next
.git
*.log
.env.local
.DS_Store
dist
build
coverage
.npm
.yarn
EOF

# Create proper configuration FILES not directories (V3 Lesson #19)
touch postcss.config.js   # Use touch, not mkdir!
touch tailwind.config.js
touch kong.yml

2. Node.js Docker Volume Strategy (V3 Lesson #10, #16)

# docker-compose.yml best practices
services:
  app:
    volumes:
      # ❌ WRONG: Mounting entire directory
      # - .:/app
      
      # ✅ CORRECT: Selective mounting
      - ./src:/app/src
      - ./public:/app/public
      - ./package.json:/app/package.json
      - ./.env:/app/.env
      # CRITICAL: Preserve container's node_modules
      - /app/node_modules

3. Environment Variable Management (V3 Lesson #25)

# IMPORTANT: Restart doesn't apply new env vars!
# ❌ WRONG
docker compose restart service-name

# ✅ CORRECT: Recreate to apply changes
docker compose up -d service-name

4. Database Migration Order (V3 Lesson #29)

# Name migrations with proper ordering
001_auth_schema.sql      # Auth tables first
002_app_tables.sql       # Application tables depend on auth
003_rls_policies.sql     # Policies last

Fresh Environment Preparation

Directory Structure for Next Version

# Current clean state should show:
/Users/lindsaysmith/Documents/lambda1.nosync/nudge-campaign/
├── docs/                    # ✅ Preserved - All research and specifications
├── html/                    # ✅ Preserved - Website documentation
├── CLAUDE.md               # ✅ Preserved - Project instructions
├── change-log.md           # ✅ Preserved - Change tracking
├── doc-builder.config.js   # ✅ Preserved - Documentation builder
└── package.json            # ✅ Preserved - Root project configuration

# Ready for new MVP directory (VERSION-SPECIFIC):
└── nudgecampaign-mvp-v[NEXT_VERSION]/   # 🚀 Ready for next version

Environment Prerequisites for Next Build

Docker Desktop running and accessible
Node.js 18+ installed and functional
Git repository clean and ready
External services accessible: Postmark account, domain access
Framework v2 ready: Enhanced autonomous framework available
All lessons learned documented: Previous version gaps captured

Framework v2 Readiness Check

AI-first validation phase added to framework
Commercial platform validation phase added to framework
Enhanced testing methodology with 25+ validation tests
Multi-tenant SaaS development guide available
All implementation guides created and accessible

Rollback Procedures (Emergency)

If Cleanup Goes Wrong

If documentation is accidentally removed or cleanup causes issues:

1. Stop Immediately

# Stop any running cleanup commands
Ctrl+C

# Assess what was removed
ls -la docs/
ls -la html/

2. Restore from Backups

# Check for backup directories
ls -la docs-backup-*/
ls -la *-backup-*/

# Restore if backups exist
cp -r docs-backup-*/ docs/
# Or restore from git if committed
git checkout HEAD -- docs/

3. Verify External Services

# Test external service access
curl -H "X-Postmark-Server-Token: 58c0f839-45de-443e-b0ac-4a8dfc18cfec" \
     "https://api.postmarkapp.com/server"

# Should return server information if token is valid

Success Criteria

Cleanup Success Indicators

Clean Environment: No running services or application artifacts
Documentation Preserved: All research, guides, and lessons learned intact
Credentials Available: External services ready for immediate reuse
Framework Ready: Enhanced v2 framework available for next build
Rollback Possible: Can restore or restart if needed

Ready for Next Version

Prerequisites Met: All framework v2 prerequisites satisfied
External Services: All accounts and credentials functional
Development Environment: Clean Docker and Node.js environment
Documentation Base: Complete knowledge base for autonomous build
Lessons Integrated: All previous version learnings captured in framework

Next Steps

Immediate Actions After Cleanup

Verify cleanup success using verification checklist
Confirm external service access with test API calls
Review framework v2 enhancements and new validation phases
Plan next version scope based on lessons learned
Execute autonomous build using enhanced framework v2

Framework v2 Enhanced Features Ready

Phase 0: Prerequisites validation with external service setup
Phase 0.5: AI-first architecture validation (for AI platforms)
Phase 1.5: Commercial SaaS platform validation (for SaaS products)
Enhanced testing: 25+ automated validation tests
Multi-tenant architecture: Complete SaaS development guide
Commercial readiness: Legal compliance and customer experience