333 lines
8.8 KiB
Markdown
333 lines
8.8 KiB
Markdown
# Sync Button - Complete Guide
|
|
|
|
## 🔄 Overview
|
|
|
|
The sync button provides **manual synchronization** between local device storage and the server database. It works on both **HTTPS (production)** and **HTTP (local network)** connections across all devices.
|
|
|
|
---
|
|
|
|
## ✨ Features
|
|
|
|
### 1. **Manual Sync Button**
|
|
|
|
- **Location**: Top navigation bar (desktop) and mobile hamburger menu
|
|
- **Function**: Bidirectional sync (push local changes + pull server changes)
|
|
- **Use Case**: When internet connection was lost and you need to sync after reconnecting
|
|
|
|
### 2. **Auto-Sync (Background)**
|
|
|
|
- **Polling Interval**: Every 5 seconds
|
|
- **Function**: Automatically checks for server changes and updates all devices
|
|
- **Mode**: Only works in **Online Mode**
|
|
|
|
---
|
|
|
|
## 🎯 How It Works
|
|
|
|
### Manual Sync Process
|
|
|
|
1. **Press Sync Button** (🔄 icon in navigation)
|
|
2. **Upload Phase**: Pushes all local changes to server
|
|
- Songs created/modified
|
|
- Profiles created/modified
|
|
- Worship lists created/modified
|
|
- Profile-song associations
|
|
- Custom song keys per profile
|
|
3. **Download Phase**: Pulls all server changes to local device
|
|
- Merges with existing local data
|
|
- Deduplicates by ID
|
|
4. **Success Notification**: Shows ✅ confirmation
|
|
|
|
### Auto-Sync Process (Background)
|
|
|
|
- Runs automatically every 5 seconds in Online Mode
|
|
- Triggers refresh events across all components
|
|
- No user action needed
|
|
- Keeps all devices synchronized in real-time
|
|
|
|
---
|
|
|
|
## 📱 Multi-Device Support
|
|
|
|
### Supported Configurations
|
|
|
|
| Device Type | HTTPS (Production) | HTTP (Local) |
|
|
|------------|-------------------|--------------|
|
|
| Desktop PC | ✅ <https://houseofprayer.ddns.net> | ✅ <http://localhost:5100> |
|
|
| Phone | ✅ <https://houseofprayer.ddns.net> | ✅ <http://192.168.10.178:5100> |
|
|
| Tablet | ✅ <https://houseofprayer.ddns.net> | ✅ <http://192.168.10.178:5100> |
|
|
| Laptop | ✅ <https://houseofprayer.ddns.net> | ✅ <http://192.168.10.178:5100> |
|
|
|
|
---
|
|
|
|
## 🔧 Setup Requirements
|
|
|
|
### For Sync to Work
|
|
|
|
1. **Online Mode Enabled**
|
|
- Go to **Settings** → **Access Mode**
|
|
- Select **"Online Mode (Multi-Device Sync)"**
|
|
- Click **Save Settings**
|
|
|
|
2. **Backend Connection**
|
|
- Settings → **Online/DNS Settings**
|
|
- Protocol: `http` or `https`
|
|
- Hostname: `houseofprayer.ddns.net` (production) or local IP
|
|
- Port: `8080` (backend) or `5100` (frontend)
|
|
|
|
3. **Internet Connection**
|
|
- For HTTPS: Requires internet
|
|
- For HTTP Local: Requires WiFi on same network
|
|
|
|
---
|
|
|
|
## 💡 Use Cases
|
|
|
|
### Scenario 1: Lost WiFi Connection
|
|
|
|
1. WiFi drops while editing songs
|
|
2. Changes saved to local storage automatically
|
|
3. WiFi reconnects
|
|
4. **Press Sync Button** to upload changes to server
|
|
5. ✅ All devices now have your changes
|
|
|
|
### Scenario 2: Working Offline
|
|
|
|
1. Switch to **Local Mode** in Settings
|
|
2. Create/edit songs, worship lists, profiles
|
|
3. Later, switch back to **Online Mode**
|
|
4. **Press Sync Button** to upload everything
|
|
5. ✅ Data now synced across all devices
|
|
|
|
### Scenario 3: Multiple People Editing
|
|
|
|
- **Person A** adds songs on desktop
|
|
- **Person B** creates worship list on phone
|
|
- Auto-sync updates both devices every 5 seconds
|
|
- No manual sync needed (happens automatically)
|
|
- **Use Sync Button** if connection was unstable
|
|
|
|
---
|
|
|
|
## 🚨 Troubleshooting
|
|
|
|
### Sync Button Says "Only Available in Online Mode"
|
|
|
|
**Problem**: App is in Local Mode
|
|
**Solution**:
|
|
|
|
1. Go to **Settings**
|
|
2. Select **"Online Mode (Multi-Device Sync)"**
|
|
3. Click **Save Settings**
|
|
4. Try sync button again
|
|
|
|
### Sync Fails with Error
|
|
|
|
**Problem**: Cannot reach backend server
|
|
**Solution**:
|
|
|
|
1. Check internet/WiFi connection
|
|
2. Verify Settings → Online/DNS Settings are correct
|
|
3. Check backend is running: `sudo systemctl status church-music-backend`
|
|
4. Test API directly:
|
|
- Production: <https://houseofprayer.ddns.net/api/health>
|
|
- Local: <http://localhost:8080/api/health>
|
|
|
|
### Auto-Sync Not Working
|
|
|
|
**Problem**: Changes from other devices not appearing
|
|
**Solution**:
|
|
|
|
1. Verify **Online Mode** is enabled in Settings
|
|
2. Check connection status (green dot vs red dot in top navigation)
|
|
3. Try manual sync button to force refresh
|
|
4. Check browser console (F12) for errors
|
|
|
|
### Data Conflicts
|
|
|
|
**Problem**: Same data edited on two devices simultaneously
|
|
**Solution**:
|
|
|
|
- Backend is source of truth
|
|
- Local changes merge with backend on sync
|
|
- Deduplication by ID prevents duplicates
|
|
- Later edits overwrite earlier ones
|
|
- No data is lost (both versions attempted)
|
|
|
|
---
|
|
|
|
## 🎨 Visual Indicators
|
|
|
|
### Connection Status (Top Navigation)
|
|
|
|
| Indicator | Meaning |
|
|
|-----------|---------|
|
|
| 🟢 Online | Connected to backend server |
|
|
| 🔴 Offline | No backend connection |
|
|
|
|
### Sync Feedback
|
|
|
|
| Message | Meaning |
|
|
|---------|---------|
|
|
| ✅ Sync complete! | Successful sync (desktop) |
|
|
| ✅ Sync complete! Your changes are now on the server. | Successful sync (mobile) |
|
|
| ❌ Sync failed: [error] | Connection or server error |
|
|
| ⚠️ Sync is only available in Online Mode | Need to enable Online Mode |
|
|
|
|
---
|
|
|
|
## 📊 What Gets Synced
|
|
|
|
### Data Types
|
|
|
|
- ✅ **Songs**: Title, lyrics, chords, key, tempo, time signature
|
|
- ✅ **Profiles**: Name, description, settings
|
|
- ✅ **Worship Lists**: Date, notes, profile association
|
|
- ✅ **Song Assignments**: Which songs in which worship lists
|
|
- ✅ **Profile Songs**: Favorite songs per profile
|
|
- ✅ **Custom Keys**: Transposed keys per profile-song combination
|
|
|
|
### Sync Operations
|
|
|
|
| Operation | Upload (Local → Server) | Download (Server → Local) |
|
|
|-----------|-------------------------|---------------------------|
|
|
| **New Items** | Creates on server | Creates locally |
|
|
| **Modified Items** | Updates server | Updates local |
|
|
| **Deleted Items** | Not synced (manual delete only) | Not synced |
|
|
| **Conflicts** | Latest timestamp wins | Backend is source of truth |
|
|
|
|
---
|
|
|
|
## ⚡ Performance
|
|
|
|
### Sync Speed
|
|
|
|
- **Small datasets** (< 100 songs): < 2 seconds
|
|
- **Medium datasets** (100-500 songs): 2-5 seconds
|
|
- **Large datasets** (> 500 songs): 5-10 seconds
|
|
|
|
### Network Requirements
|
|
|
|
- **Minimum**: 1 Mbps upload/download
|
|
- **Recommended**: 5+ Mbps for smooth operation
|
|
- **Latency**: < 500ms for responsive sync
|
|
|
|
---
|
|
|
|
## 🔐 Security
|
|
|
|
### Data Protection
|
|
|
|
- HTTPS encryption in production
|
|
- JWT authentication tokens
|
|
- Profile-based access control
|
|
- No sensitive data in localStorage
|
|
- Passwords hashed (never synced)
|
|
|
|
### Privacy
|
|
|
|
- Sync only when authenticated
|
|
- Data isolated per user account
|
|
- No cross-user data leakage
|
|
- Local fallback if server unreachable
|
|
|
|
---
|
|
|
|
## 📝 Code Reference
|
|
|
|
### Sync Functions
|
|
|
|
**Location**: `frontend/src/migration.js`
|
|
|
|
```javascript
|
|
// Full bidirectional sync
|
|
fullSync(customBase)
|
|
- migrateLocalStorageToBackend() // Upload
|
|
- syncFromBackendToLocalStorage() // Download
|
|
|
|
// Manual upload only
|
|
migrateLocalStorageToBackend(customBase)
|
|
|
|
// Manual download only
|
|
syncFromBackendToLocalStorage(customBase)
|
|
```
|
|
|
|
### Sync Button Implementation
|
|
|
|
**Location**: `frontend/src/App.js`
|
|
|
|
- **Desktop**: Line ~7538 (top navigation)
|
|
- **Mobile**: Line ~7831 (hamburger menu)
|
|
|
|
Both buttons call `fullSync()` from migration.js
|
|
|
|
### Auto-Sync Polling
|
|
|
|
**Location**: `frontend/src/App.js` line ~7178
|
|
|
|
```javascript
|
|
// Polls every 5 seconds in Online Mode
|
|
useEffect(() => {
|
|
if (!isAuthenticated) return;
|
|
let syncTimer;
|
|
async function pollForChanges() {
|
|
// Dispatch refresh events
|
|
window.dispatchEvent(new Event("songsChanged"));
|
|
window.dispatchEvent(new Event("plansChanged"));
|
|
window.dispatchEvent(new Event("profileChanged"));
|
|
}
|
|
syncTimer = setInterval(pollForChanges, 5000);
|
|
return () => clearInterval(syncTimer);
|
|
}, [isAuthenticated]);
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 Best Practices
|
|
|
|
### For Reliable Sync
|
|
|
|
1. **Enable Online Mode** when connected to internet/WiFi
|
|
2. **Use Local Mode** only when working completely offline
|
|
3. **Press Sync Button** after switching from Local to Online Mode
|
|
4. **Wait for confirmation** (✅ message) before closing app
|
|
5. **Check connection indicator** (green dot) before creating important data
|
|
|
|
### For Multi-Device Teams
|
|
|
|
1. **One person per task** - avoid simultaneous edits
|
|
2. **Refresh before editing** - ensure you have latest data
|
|
3. **Save frequently** - changes auto-sync every 5 seconds
|
|
4. **Use Sync Button** if connection was unstable
|
|
5. **Coordinate worship list creation** - avoid duplicate lists
|
|
|
|
---
|
|
|
|
## 🚀 Deployment
|
|
|
|
Deployed: December 17, 2025 23:18 CST
|
|
Version: v=2380
|
|
Bundle: main.bf5e2e29.js (114.15 kB gzipped)
|
|
|
|
### Access URLs
|
|
|
|
- **Production (HTTPS)**: <https://houseofprayer.ddns.net>
|
|
- **Local Network (HTTP)**: <http://192.168.10.178:5100>
|
|
- **Localhost**: <http://localhost:5100>
|
|
|
|
---
|
|
|
|
## 📞 Support
|
|
|
|
If sync issues persist:
|
|
|
|
1. Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
|
2. Review browser console logs (F12 → Console)
|
|
3. Test backend health: `/api/health` endpoint
|
|
4. Verify systemd services running:
|
|
|
|
```bash
|
|
sudo systemctl status church-music-backend
|
|
sudo systemctl status church-music-frontend
|
|
```
|