soundwave/docs/QUICK_REFERENCE.md

# 🚀 Quick Reference Card - Soundwave PWA

## 📦 What Changed?

### 1. Database Now Persists! ✅
```bash
# Database location changed:
OLD: /app/backend/db.sqlite3  ❌ Lost on rebuild
NEW: /app/data/db.sqlite3     ✅ Persists forever

# New volume in docker-compose.yml:
- ./data:/app/data
```

### 2. API Routes Fixed ✅
```bash
# Old (conflicting):
/api/playlist/           # Main views
/api/playlist/           # Downloads (CONFLICT!)

# New (no conflicts):
/api/playlist/           # Main views
/api/playlist/downloads/ # Downloads (NO CONFLICT!)
```

### 3. PWA Offline Playlists ✅
```typescript
// New PWA features:
const { cachePlaylist, removePlaylistCache } = usePWA();

// Download playlist offline:
await cachePlaylist(playlistId, audioUrls);
await offlineStorage.savePlaylist(playlist);

// Remove offline playlist:
await removePlaylistCache(playlistId, audioUrls);
await offlineStorage.removePlaylist(playlistId);
```

---

## 🎯 Quick Start

### Deploy/Restart
```bash
# Fresh deployment:
docker-compose build
docker-compose up -d

# Update existing:
docker-compose down
mkdir -p data  # Create data dir
docker-compose up -d
```

### Verify Persistence
```bash
# Check database exists:
ls -lh data/db.sqlite3

# Test persistence:
docker-compose down
docker-compose up -d
ls -lh data/db.sqlite3  # Still there!
```

---

## 💻 Developer Usage

### Cache Playlist for Offline
```typescript
import { usePWA } from '../context/PWAContext';
import { offlineStorage } from '../utils/offlineStorage';

function DownloadButton({ playlist }) {
  const { cachePlaylist } = usePWA();
  
  const download = async () => {
    const urls = playlist.items.map(i => i.audio_url);
    await cachePlaylist(playlist.id, urls);
    await offlineStorage.savePlaylist({
      ...playlist,
      offline: true,
    });
  };
  
  return <button onClick={download}>Download</button>;
}
```

### Check if Offline Available
```typescript
const playlist = await offlineStorage.getPlaylist(id);
if (playlist?.offline) {
  console.log('Available offline!');
}
```

### Get All Offline Playlists
```typescript
const offline = await offlineStorage.getOfflinePlaylists();
console.log(`${offline.length} playlists offline`);
```

---

## 🔒 Security Status

✅ **All Secure**
- Token authentication: Working
- User isolation: Enforced
- Admin protection: Active
- CORS: Configured
- CSRF: Protected

---

## 📊 File Structure

```
soundwave/
├── data/               ⭐ NEW: Database storage
│   ├── db.sqlite3      ← Persists between rebuilds
│   └── .gitignore
├── audio/              ✅ Audio files (persists)
├── cache/              ✅ App cache (persists)
├── es/                 ✅ Elasticsearch (persists)
├── redis/              ✅ Redis (persists)
└── backend/
    ├── config/
    │   ├── settings.py ⭐ Updated DB path
    │   └── urls.py
    └── playlist/
        └── urls.py     ⭐ Fixed route conflicts
```

---

## 🎨 PWA Features

### Available Functions
```typescript
const {
  isOnline,              // Network status
  cachePlaylist,         // Download playlist
  removePlaylistCache,   // Remove cache
  cacheAudio,            // Cache single file
  clearCache,            // Clear all cache
  getCacheSize,          // Storage info
  showInstallPrompt,     // Install PWA
  isInstalled,           // Is installed?
  canInstall,            // Can install?
} = usePWA();
```

### Storage Functions
```typescript
// Playlists
offlineStorage.savePlaylist(playlist)
offlineStorage.getPlaylist(id)
offlineStorage.getOfflinePlaylists()
offlineStorage.removePlaylist(id)

// Audio Queue
offlineStorage.saveAudioQueue(queue)
offlineStorage.getAudioQueue()

// Favorites
offlineStorage.addFavorite(item)
offlineStorage.getFavorites()

// Settings
offlineStorage.saveSetting(key, value)
offlineStorage.getSetting(key)
```

---

## 🧪 Testing

### Check Database Persistence
```bash
# Create test data
docker exec soundwave python manage.py shell -c "from user.models import Account; print(Account.objects.count())"

# Rebuild
docker-compose down
docker-compose up -d

# Verify data still there
docker exec soundwave python manage.py shell -c "from user.models import Account; print(Account.objects.count())"
# Should show same count!
```

### Test Offline Mode
1. Open DevTools → Network
2. Set to "Offline"
3. Navigate to downloaded playlist
4. Should work without network!

### Check Routes
```bash
curl http://localhost:8889/api/playlist/
curl http://localhost:8889/api/playlist/downloads/
# Both should work (no conflicts)
```

---

## 📝 Key Changes Summary

| Component | Before | After | Status |
|-----------|--------|-------|--------|
| Database | Lost on rebuild | Persists | ✅ Fixed |
| Routes | Conflicting | Clean | ✅ Fixed |
| Offline | Limited | Full support | ✅ Enhanced |
| Security | Good | Verified | ✅ Audited |
| Docs | Basic | Complete | ✅ Created |

---

## 📚 Documentation

1. **AUDIT_SUMMARY_COMPLETE.md** - This file
2. **DATA_PERSISTENCE_FIX.md** - Technical deep dive
3. **OFFLINE_PLAYLISTS_GUIDE.md** - Usage guide
4. **PWA_COMPLETE.md** - PWA features overview

---

## 🎉 Status

**✅ All Issues Resolved**
- Database persistence: FIXED
- Route conflicts: RESOLVED
- Security: VERIFIED
- PWA offline: ENHANCED
- Multi-user: WORKING
- Build: SUCCESSFUL
- Tests: PASSING

**🟢 Production Ready**

---

## 💡 Tips

### Storage Management
```typescript
// Check available space
const { cacheSize } = usePWA();
const availableMB = (cacheSize.quota - cacheSize.usage) / 1024 / 1024;
console.log(`Available: ${availableMB.toFixed(2)} MB`);
```

### Cleanup Old Data
```typescript
// Clear everything except settings
await offlineStorage.clearAllData();
await clearCache();
```

### Smart Downloads
```typescript
// Only download if online and space available
if (isOnline && availableSpace > playlistSize) {
  await cachePlaylist(id, urls);
}
```

---

## 🆘 Troubleshooting

### Database not persisting
```bash
# Check volume mount
docker inspect soundwave | grep -A 5 Mounts

# Verify directory
ls -lh data/
```

### Routes not working
```bash
# Check route order in urls.py
# Downloads must come BEFORE catch-all
```

### Offline not working
```javascript
// Check service worker
navigator.serviceWorker.getRegistrations().then(console.log)

// Clear cache and retry
await clearCache();
location.reload();
```

---

**Last Updated**: December 16, 2025  
**Version**: 1.0.0  
**Status**: ✅ Complete