FINAL_START_GUIDE.md

ARC Platform - The Real Issue & Solution

🚨 The Problem

Port 5000 is occupied by macOS AirPlay/AirTunes - that's why the backend won't start!

The "zombie process" you're seeing is actually Apple's AirPlay Receiver service.

---

✅ Solution: Use Port 3000 Instead

Step 1: Kill Everything on 5000

# This won't work permanently because macOS restarts AirTunes
sudo lsof -ti:5000 | xargs sudo kill -9

Better: Disable AirPlay Receiver in macOS:

1. System Settings → General → AirDrop & Handoff
2. Turn OFF "AirPlay Receiver"

---

Step 2: Start Backend on Port 3000

# Set port and start
PORT=3000 npm run dev:api

Or create .env file:

echo "PORT=3000" > .env
npm run dev:api

---

Step 3: Test API

# Wait 10 seconds for backend to build & start, then:
curl http://localhost:3000/health

Should return:

{"status":"ok","timestamp":"..."}

---

🧪 Quick Test (Correct Port)

# Terminal 1: Start backend
PORT=3000 npm run dev:api

# Terminal 2: Wait 10 seconds, then test
curl -X POST http://localhost:3000/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@demo.com","password":"Demo123!","full_name":"Test","identity_type":"artist"}'

# Should return success with user data

---

📝 Update All Documentation

Once backend is on port 3000, update:

API Base URL: http://localhost:3000 (not 5000)

Test Script: Update test-api-demo.sh:

API="http://localhost:3000"  # Change from 5000

---

🎯 Recommended Ports

• Backend API: 3000 (avoids AirPlay conflict)
• CHROMA Portal: 3500
• ARC Portal: 3300
• EAGLE Portal: 3600
• Marketplace: 3100

---

✅ Working Demo Commands

# 1. Start backend on port 3000
PORT=3000 npm run dev:api &

# 2. Wait for build (10-15 seconds)
sleep 15

# 3. Test health
curl http://localhost:3000/health

# 4. Register user
curl -X POST http://localhost:3000/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@test.com","password":"Demo123!","full_name":"Demo","identity_type":"artist"}'

# 5. Login
curl -X POST http://localhost:3000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@test.com","password":"Demo123!"}'

# Returns JWT token - save it!

# 6. Test Quality Scoring (Tier-3)
curl http://localhost:3000/v1/ops/quality/stats \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

🔧 Alternative: Disable macOS AirPlay

Permanent fix:

1. Open System Settings
2. Go to General → AirDrop & Handoff
3. Toggle OFF: "AirPlay Receiver"
4. Port 5000 will be free
5. Restart with: npm run dev:api

---

📊 What This Fixes

• ✅ Backend will actually start
• ✅ Health endpoint will respond
• ✅ API will be accessible
• ✅ All 62+ tests will be runnable
• ✅ Tier-2 and Tier-3 features testable

---

Quick Start:

PORT=3000 npm run dev:api

Wait 15 seconds, then test:

curl http://localhost:3000/health