Church-Music/legacy-site/documentation/md-files/MULTI_DEVICE_SETUP.md

# Multi-Device Local Network Access Guide

## Quick Setup (5 Minutes)

Your Church SongLyric system is already configured for multi-device access! Follow these steps:

---

## ✅ Backend Status (Server PC)

**Current Configuration:**

- ✅ Backend running on port 5000
- ✅ Listening on all interfaces (0.0.0.0)
- ✅ Windows Firewall allows port 5000
- ✅ CORS enabled for cross-origin requests
- ✅ WebSocket enabled for real-time sync

**Server IP Addresses:**

- Primary LAN: `192.168.10.178`
- Alternative IPs: `10.5.0.2`, `192.168.233.1`, `192.168.74.1`

---

## 📱 Device Setup Instructions

### Step 1: Find Your Server IP

On the **server PC** (where backend runs), open PowerShell and run:

```powershell
ipconfig | Select-String "IPv4"
```

Look for the IP starting with `192.168.x.x` (most common) - typically `192.168.10.178`

### Step 2: Configure Each Device

On **each device** (phone, tablet, laptop):

1. **Open the app** in a browser:
   - Same network: `http://192.168.10.178:3000`
   - Or access via computer name: `http://YOUR-PC-NAME:3000`

2. **Go to Settings** (⚙️ icon in top navigation)

3. **Switch to Online Mode:**
   - Click "Online Mode (No-IP DNS)" option
   - This enables backend sync

4. **Configure Connection:**
   - Protocol: `http`
   - Hostname: `192.168.10.178` (your server IP)
   - Port: `5000`
   - Click **Save DNS Settings**

5. **Migrate Data (if needed):**
   - If prompted, click "Yes, Migrate Now"
   - Wait 5-10 seconds for completion
   - Data will sync from local storage to backend

### Step 3: Verify Connection

After saving settings:

1. Click **Run Diagnostics** in Settings
2. All tests should show ✅:
   - ✅ DNS Resolution
   - ✅ Localhost Connectivity
   - ✅ Backend Connectivity
   - ✅ Local Network (LAN) Test

3. Test data sync:
   - Add a song on one device
   - Check if it appears on another device within seconds
   - Real-time sync via WebSocket!

---

## 🔧 Troubleshooting

### Device Can't Connect

**Check 1: Same Wi-Fi Network?**

- All devices must be on the same Wi-Fi
- Check Wi-Fi name on each device

**Check 2: Backend Running?**

- On server PC, verify: `netstat -ano | findstr :5000`
- Should show: `0.0.0.0:5000` LISTENING
- Restart if needed: `node backend/server.js`

**Check 3: Correct IP Address?**

- Ping from device: `ping 192.168.10.178`
- Should get responses (not timeout)
- If timeout, check firewall or IP changed

**Check 4: Firewall Allows Port?**

- On server PC: `netsh advfirewall firewall show rule name=all | Select-String "5000"`
- Should show: `Action: Allow`
- If not, create rule (see below)

### Create Firewall Rule (if needed)

On **server PC**, run PowerShell as Administrator:

```powershell
New-NetFirewallRule -DisplayName "Church SongLyric Backend" -Direction Inbound -Protocol TCP -LocalPort 5000 -Action Allow
```

### IP Address Changed?

If server PC IP changed (after router reboot):

1. Find new IP: `ipconfig | Select-String "IPv4"`
2. Update Settings on all devices with new IP
3. Save and test

---

## 📊 Testing Multi-Device Sync

### Test 1: Real-Time Song Creation

1. **Device A**: Add a new song in Database
2. **Device B**: Refresh Database page
3. **Result**: New song appears instantly ✨

### Test 2: Profile Switching

1. **Device A**: Switch to different profile
2. **Device B**: Profile selection syncs automatically
3. **Result**: Both devices show same profile ✨

### Test 3: Worship Plan Creation

1. **Device A**: Create a worship plan with songs
2. **Device B**: Open Planning page
3. **Result**: Plan appears with all songs ✨

---

## 🌐 Access URLs for Your Network

**Server PC (localhost):**

```text
http://localhost:3000
http://localhost:5000/api
```

**Other Devices on LAN:**

```text
Frontend: http://192.168.10.178:3000
Backend API: http://192.168.10.178:5000/api
Health Check: http://192.168.10.178:5000/api/health
```

**Quick Test Command (any device):**

```powershell
curl http://192.168.10.178:5000/api/health
```

Should return:

```json
{"status":"ok","ts":1764470523364,"uptime_ms":121825.9212}
```

---

## 🚀 Starting the System

### On Server PC

**Terminal 1 - Backend:**

```powershell
cd "E:\Documents\Website Projects\Church_SongLyric\backend"
node server.js
```

**Terminal 2 - Frontend:**

```powershell
cd "E:\Documents\Website Projects\Church_SongLyric\frontend"
npm start
```

### On Other Devices

#### Option 1: Open Browser

```text
http://192.168.10.178:3000
```

**Option 2: Access via Computer Name** (if DNS resolves)

```text
http://YOUR-PC-NAME:3000
```

---

## ✨ Features Working Across Devices

- ✅ **Real-time song database** - Add, edit, delete songs
- ✅ **Profile management** - Create and switch profiles
- ✅ **Worship list** - Create plans with song lists
- ✅ **Chord transposition** - Per-profile key adjustments
- ✅ **Instant sync** - Changes appear on all devices within seconds
- ✅ **WebSocket updates** - No manual refresh needed
- ✅ **Offline fallback** - Can switch back to Local Mode anytime

---

## 💡 Best Practices

1. **Keep server PC running** - Backend must be active for multi-device access
2. **Use Static IP** - Assign static IP in router to prevent address changes
3. **Bookmark the URL** - Save `http://192.168.10.178:3000` on each device
4. **Test connectivity first** - Run diagnostics before troubleshooting
5. **One migration per device** - Only migrate data once when switching to Online Mode

---

## 🔐 Security Notes

**Local Network Only:**

- Current setup works on local Wi-Fi only
- Data is not encrypted (HTTP not HTTPS)
- Fine for church/home network
- For internet access, see `EXTERNAL_ACCESS_CHECKLIST.md`

**Data Storage:**

- Backend stores data in `backend/data.json`
- Backup this file regularly
- Each device can also keep local copy (Local Mode)

---

## 📞 Need Help?

**Quick Diagnostics:**

1. Settings → Run Diagnostics
2. Check all 4 tests pass
3. Review error messages

**Common Issues:**

- "Connection refused" = Backend not running
- "Timeout" = Wrong IP or firewall blocking
- "404 Not found" = Wrong port number
- "CORS error" = Backend CORS not configured (already set up for you!)

**Health Check Script:**

```powershell
.\backend\health-check.ps1 http://192.168.10.178:5000
```

---

## ✅ Verification Checklist

Before using across devices, verify:

- [ ] Backend running: `node backend/server.js` shows "API listening on port 5000"
- [ ] Firewall allows port 5000 (already configured)
- [ ] Can access from server: `curl http://localhost:5000/api/health` returns OK
- [ ] Can access from LAN: `curl http://192.168.10.178:5000/api/health` returns OK
- [ ] Frontend accessible: Open `http://192.168.10.178:3000` in browser
- [ ] Settings configured: Online Mode selected, hostname set to `192.168.10.178`
- [ ] Diagnostics pass: All 4 tests show ✅ in Settings → Diagnostics

If all checked, you're ready! 🎉

---

## 🎯 Next Steps

1. **Connect your first additional device** - Follow Step 2 above
2. **Test real-time sync** - Add a song and watch it appear on other device
3. **Explore features** - Profiles, plans, chord transposition
4. **Optional**: Set up external access (see `EXTERNAL_ACCESS_CHECKLIST.md`)

Your Church SongLyric system is ready for multi-device collaboration! 🙌