Initial commit - Church Music Database

legacy-site/documentation/md-files/MONGODB_QUICK_REFERENCE.md

@@ -0,0 +1,228 @@
+# 🚀 MongoDB System - Quick Reference
+
+## ✅ System Status
+
+**Database:** MongoDB Community Server (Local)  
+**Backend:** Flask + PyMongo  
+**Status:** ✅ OPERATIONAL  
+
+**Data:**
+
+- 39 Songs
+- 5 Profiles  
+- Cross-device access enabled
+
+---
+
+## 🌐 Access URLs
+
+### PC/Desktop
+
+- **Frontend:** <http://localhost:3000>
+- **Backend API:** <http://localhost:5000>
+
+### Mobile/Tablet (Same WiFi)
+
+- **Frontend:** <http://192.168.10.178:3000>
+- **Backend API:** <http://192.168.10.178:5000>
+
+---
+
+## ⚡ Quick Commands
+
+### Start Backend
+
+```powershell
+cd "E:\Documents\Website Projects\Church_SongLyric\backend"
+.\venv\Scripts\python.exe app.py
+```
+
+### Check MongoDB Service
+
+```powershell
+Get-Service MongoDB
+```
+
+### Start MongoDB (if stopped)
+
+```powershell
+Start-Service MongoDB
+```
+
+### Test API
+
+```powershell
+Invoke-RestMethod http://localhost:5000/api/health
+```
+
+### Check Data Count
+
+```powershell
+cd backend
+.\venv\Scripts\python.exe check_mongo_data.py
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### Frontend shows "Offline"
+
+Open browser console (F12) and run:
+
+```javascript
+localStorage.setItem("api_settings", JSON.stringify({
+  protocol: "http",
+  hostname: "localhost",  // or "192.168.10.178" for mobile
+  port: "5000",
+  useLocalStorage: false
+}));
+location.reload(true);
+```
+
+### Backend not responding
+
+```powershell
+# Check if backend is running
+Get-Process python -ErrorAction SilentlyContinue
+
+# Restart backend
+cd "E:\Documents\Website Projects\Church_SongLyric\backend"
+.\venv\Scripts\python.exe app.py
+```
+
+### MongoDB not running
+
+```powershell
+# Check service
+Get-Service MongoDB
+
+# Start if stopped
+Start-Service MongoDB
+
+# If service doesn't exist, reinstall MongoDB Community Server
+```
+
+### Data missing
+
+```powershell
+# Re-run migration (safe, skips duplicates)
+cd "E:\Documents\Website Projects\Church_SongLyric\backend"
+.\venv\Scripts\python.exe migrate_to_mongodb.py
+```
+
+---
+
+## 📁 Important Files
+
+### Configuration
+
+- `backend/.env` - Database connection settings
+- `backend/mongodb_models.py` - Database schema
+
+### Backups (in `backend/._archived_sqlite/`)
+
+- `app.db` - Original SQLite database
+- `models.py` - Old SQLAlchemy models
+- `app_sqlite_backup.py` - Pre-migration backend
+
+### Documentation
+
+- `MONGODB_MIGRATION_COMPLETE.md` - Full migration details
+- `MONGODB_ATLAS_SETUP.md` - Cloud setup guide (future)
+
+---
+
+## 🎯 Key Features
+
+✅ **Cross-Device Sync** - All devices use same database  
+✅ **Real-Time Updates** - Changes visible immediately  
+✅ **Connection Pooling** - Handles multiple devices  
+✅ **Automatic Indexes** - Fast song search  
+✅ **Data Safety** - Old SQLite backed up  
+
+---
+
+## 📊 API Endpoints
+
+All endpoints working with MongoDB:
+
+| Endpoint | Methods | Purpose |
+|----------|---------|---------|
+| `/api/health` | GET | Health check |
+| `/api/profiles` | GET, POST | List/create profiles |
+| `/api/profiles/<id>` | PUT, DELETE | Edit/delete profile |
+| `/api/songs` | GET, POST | List/create songs (search with ?q=) |
+| `/api/songs/<id>` | GET, PUT, DELETE | View/edit/delete song |
+| `/api/plans` | GET, POST | List/create plans |
+| `/api/profiles/<id>/songs` | GET, POST | Profile song library |
+| `/api/search_external` | GET | Search ChartLyrics |
+
+---
+
+## 🔄 If You Need to Rollback
+
+**(Only if something goes wrong - not recommended)**
+
+```powershell
+cd "E:\Documents\Website Projects\Church_SongLyric\backend"
+
+# Stop current backend (Ctrl+C or close window)
+
+# Restore old files
+Copy-Item "._archived_sqlite\app.db" "app.db" -Force
+Copy-Item "._archived_sqlite\app_sqlite_backup.py" "app.py" -Force
+Copy-Item "._archived_sqlite\models.py" "models.py" -Force
+
+# Restart backend with SQLite
+.\venv\Scripts\python.exe app.py
+```
+
+**Note:** Rollback will lose any data added after migration!
+
+---
+
+## 💡 Tips
+
+1. **Keep MongoDB Service Running**
+   - Set to start automatically (already configured)
+   - Don't stop MongoDB service
+
+2. **Backend Must Run for Access**
+   - PC must have backend running
+   - Mobile/tablet connect to PC's backend
+
+3. **Same WiFi Required**
+   - All devices need same network
+   - Use 192.168.10.178 for LAN access
+
+4. **Future: Migrate to Cloud**
+   - Follow `MONGODB_ATLAS_SETUP.md`
+   - Enables access without PC running
+   - Works from anywhere with internet
+
+---
+
+## 📞 Need Help?
+
+Check these in order:
+
+1. Is MongoDB service running? `Get-Service MongoDB`
+2. Is backend running? `Get-Process python`
+3. Can you access API? `Invoke-RestMethod http://localhost:5000/api/health`
+4. Check browser console (F12) for errors
+5. Review `MONGODB_MIGRATION_COMPLETE.md` for detailed info
+
+---
+
+## ✅ Success Checklist
+
+- [x] MongoDB installed and running
+- [x] 39 songs in database
+- [x] 5 profiles in database
+- [x] Backend API working
+- [x] Old files archived safely
+- [ ] Frontend tested (check now!)
+- [ ] Mobile tested (try on phone)
+
+**Your MongoDB migration is complete and operational!** 🎉