# Mello v3 — Komplette Roadmap bis Launch (Server-Quality-First)

**Datum:** 2026-08-19  
**Status:** Brainstorming ✓ → Design ✓ → Execution  
**Ziel:** Musik-App mit Navidrome-Server + lokaler Fallback, konkurrenzfähig zu Spotify/Apple Music  
**Strategie:** Server-Quality-First (Musikserver perfekt machen, dann lokale Features)

---

## 🎯 Übersicht: Was wird gebaut?

### Hauptfeature
- **Navidrome/Subsonic-Server** (musik.baka-net.de o.ä.) — Streaming, Caching, Offline-Mode
- **Lokale Fallback** — lokale Musik-Dateien wenn Server Down

### Nicht im Scope (Abo/Werbung)
- ❌ Premium vs. Free Tiers
- ❌ Werbung
- ❌ In-App Purchases
- ❌ Tracking/Telemetry

---

## 📋 Phase-Roadmap (Detailliert)

### **PHASE 1: MVP — Musikserver-Player (Aktuell / 2-3 Wochen)**

**Ziel:** Funktionsfähiger Musikserver-Streaming-Player

#### P0 — KRITISCH (muss rein)
| Feature | Beschreibung | Tech | Priorität |
|---------|-------------|------|-----------|
| Server-Verbindung | Login zu Navidrome, Credentials speichern | NavidromeService | P0 |
| Album-Browser | Alben vom Server laden, durchstöbern | UI + Service | P0 |
| Play/Pause/Skip | Basic Player Controls | just_audio | P0 |
| Seek/Volume | Fortschritt, Lautstärke regeln | just_audio | P0 |
| Now Playing Screen | Großes Cover, aktuelle Song-Info | UI | P0 |
| Favoriten (Server) | ❤️-Button, Server-Favoriten sync | Service + DB | P0 |
| Queue Management | Nächste Lieder sehen, Skip | AudioHandler | P0 |
| Offline-Cache (Basic) | Lied beim Spielen cachen | File-System | P0 |

#### P1 — WICHTIG (sollte rein, nicht kritisch)
| Feature | Beschreibung | Priorität |
|---------|-------------|-----------|
| Artists Browse | Nach Künstler filtern | P1 |
| Playlisten vom Server | Server-Playlisten laden | P1 |
| Recently Added | Neue Alben zuerst | P1 |
| Suche | Global Search im Server | P1 |
| History/Resume | Wo war ich beim letzten Song? | P1 |

#### P2 — NICE-TO-HAVE
| Feature | Beschreibung | Priorität |
|---------|-------------|-----------|
| Dark/Light Mode Toggle | Nur Dark im MVP | P2 |
| Settings UI | Grundeinstellungen | P2 |

#### 🚀 MVP-Launch Checklist
- ✅ Server-Streaming funktioniert stabil
- ✅ Play/Pause/Skip/Seek robust
- ✅ Basic Caching (keine abgebrochene Lieder)
- ✅ 5-Tab UI fertig (Player, Library, Playlists, Search, Settings)
- ✅ 70+ Tests grün
- ✅ Keine Major Bugs

**Geschätzt:** 2-3 Wochen (läuft parallel mit diesem Plan)

---

### **PHASE 2: Server-Stabilität & Offline (1-2 Monate)**

**Ziel:** Musikserver zuverlässig, funktioniert auch offline

#### P0 — KRITISCH
| Feature | Beschreibung | Impact | Aufwand |
|---------|-------------|--------|---------|
| **Intelligentes Caching** | Smart Cache (recent, favorited, pinned) | Offline funktioniert besser | Hoch |
| **Offline-Mode Toggle** | "Nur gecachte Songs abspielen" | Daten sparen | Mittel |
| **Buffering & Streaming** | Progressive Download, Retry-Logic | Stabil streamen | Hoch |
| **Error Handling** | Server Down → Graceful Fallback | App crasht nicht | Mittel |
| **Lock Screen Controls** | Musik vom Lock Screen steuern | QoL für User | Mittel |
| **Multi-Device Sync** | Favoriten/History über Devices sync | Continuity | Hoch |
| **Queue Persistence** | Queue speichern zwischen Sessions | UX | Gering |

#### P1 — WICHTIG
| Feature | Beschreibung | Impact | Aufwand |
|---------|-------------|--------|---------|
| Home Widget | Now Playing Widget | Convenience | Mittel |
| Bluetooth Controls | Bluetooth-Kopfhörer steuern | Hardware Support | Mittel |
| Playlisten lokal erstellen | Lokal Playlisten bauen | Offline-Mode | Mittel |
| Backup/Restore | Playlisten exportieren | Data Safety | Gering |

#### P2 — NICE
| Feature | Beschreibung | Aufwand |
|---------|-------------|---------|
| Download Manager | Sehen was cached ist, löschen | Gering |
| Bandwidth Limiter | "Nur WiFi cachen" | Mittel |
| Sync Status | Zeige Sync-Fortschritt | Gering |

**Impact:** Nutzer können App überall nutzen, auch offline  
**Geschätzt:** 4-6 Wochen

---

### **PHASE 3: Audio-Quality & Lokalmusik (1-2 Monate)**

**Ziel:** Audio klingt professionell + lokale Musik funktioniert

#### P0 — KRITISCH (Audio-Kern!)
| Feature | Beschreibung | Impact | Aufwand |
|---------|-------------|--------|---------|
| **Gapless Playback** | Keine Stille zwischen Liedern | Album-Sound | Mittel |
| **Loudness Normalization** | Alle Lieder gleich laut (LUFS) | Komfort (kein Volumen-Jumpen) | Mittel |
| **Crossfade** | 2-5s Übergang zwischen Songs | Smooth | Gering |
| **Equalizer (5-Band)** | Bass/Mids/Treble anpassen | Audio-Kontrolle | Mittel |
| **Local Music Import** | Dateien vom Handy hinzufügen | Fallback Feature | Mittel |
| **Metadata Editor** | ID3-Tags bearbeiten (Title, Artist) | Falsche Daten fixen | Mittel |
| **Duplicate Detection** | Warne vor doppelten Liedern | Data Hygiene | Mittel |

#### P1 — WICHTIG
| Feature | Beschreibung | Impact | Aufwand |
|---------|-------------|--------|---------|
| Stream Quality Selection | Wähle Bitrate (128/192/320kbps) | Bandwidth Control | Gering |
| Visualizer | Einfacher Musikvisualizer | Ästhetik | Mittel |
| Playlist Shuffle (Smart) | Nicht nur random | Better UX | Gering |
| Repeat Modes | Repeat One/All | Playback Control | Gering |

#### P2 — NICE
| Feature | Beschreibung | Aufwand |
|---------|-------------|--------|---------|
| Waveform Display | Visueller Fortschrittsbalken | Gering |
| Speed Control | 0.8x-2.0x Playback Speed | Mittel |
| Folder Browsing | Explore Ordner-Struktur | Mittel |

**Impact:** Audio klingt professionell, lokale Musik funktioniert als echte Fallback  
**Geschätzt:** 4-6 Wochen

---

### **PHASE 4: UX-Polish & Entertainment (1-2 Monate)**

**Ziel:** App fühlt sich poliert an, macht Spaß zu nutzen

#### P0 — WICHTIG
| Feature | Beschreibung | Impact | Aufwand |
|---------|-------------|--------|---------|
| **Lyrics Display** | Song-Lyrics anzeigen + sync | Entertainment | Mittel |
| **Sleep Timer** | "Stop nach 30 Minuten" | Daily UX | Gering |
| **Now Playing Animations** | Smooth Übergänge, Polish | Feel | Mittel |
| **Search History** | Suchverlauf speichern | Convenience | Gering |
| **Better Browse** | Genres, Decades, Mood | Discovery | Mittel |

#### P1 — WICHTIG
| Feature | Beschreibung | Impact | Aufwand |
|---------|-------------|--------|---------|
| Mini-Player | Kompakter Player während Browse | QoL | Mittel |
| Gesture Controls | Swipe = Skip, Double-Tap = Fav | iPhone-Feeling | Mittel |
| Haptic Feedback | Vibration auf Interaktionen | Feedback | Gering |
| Smart Playlists | Auto-playlists (Recently Added, Most Played) | Organization | Mittel |
| Playlist Collaboration | Share Playlists (Link) | Social | Mittel |

#### P2 — NICE
| Feature | Beschreibung | Aufwand |
|---------|-------------|--------|---------|
| Theme Variants | AMOLED Mode, True Black | Gering |
| Keyboard Shortcuts | Space = Play, Arrow = Skip | Mittel |
| Export Playlist | m3u, pls Format | Gering |

**Impact:** App fühlt sich wie Profi-App an, nicht Beta  
**Geschätzt:** 3-4 Wochen

---

### **PHASE 5+: Advanced Features (Optional)**

**Ziel:** Features die Spotify/Apple Music haben, aber nicht kritisch

#### P1 — SOLLTE REIN
| Feature | Beschreibung | Impact | Aufwand |
|---------|-------------|--------|---------|
| Tags/Labels | Zusätzlich zu Playlisten | Organization | Mittel |
| Scrobbling (Last.fm) | Track Listening History | Personal Stats | Gering |
| Auto-Recommendations | KNN-basierte Vorschläge | Discovery | Hoch |
| Podcast Support | Variable Speed, Skip Intro | Format Support | Hoch |

#### P2 — NICE-TO-HAVE
| Feature | Beschreibung | Aufwand |
|---------|-------------|--------|---------|
| Weekly Recaps | "Your Top 10 This Week" | Entertainment | Mittel |
| Mood/Activity Playlists | "Working", "Chill", "Party" | Curation | Mittel |
| Shared Playlists (Collab) | Real-time Playlist Collaboration | Social | Hoch |
| Mobile App → Web/Desktop | Sync to Browser | Platform | Hoch |

**Impact:** Feature-Parity mit Spotify/Apple Music  
**Geschätzt:** 2-3 Monate (can be parallel)

---

## 📊 Feature-Priorisierungs-Matrix

```
MUSS (P0)               SOLLTE (P1)              NICE (P2)
─────────────────────────────────────────────────────────
Phase 1:
- Server-Stream         - Artists Browse         - Settings UI
- Play/Pause/Skip       - Playlisten vom Server  - Dark/Light
- Favoriten             - Suche
- Queue                 - History/Resume

Phase 2:
- Smart Caching         - Home Widget            - Download Manager
- Offline-Mode          - Bluetooth              - Bandwidth Limiter
- Multi-Device Sync     - Local Playlisten       - Sync Status
- Lock Screen           - Backup/Restore

Phase 3:
- Gapless/Loudness      - Visualizer             - Waveform
- Crossfade             - Smart Shuffle          - Speed Control
- Equalizer             - Stream Quality         - Folder Browsing
- Local Import          - Repeat Modes
- Metadata Editor       
- Duplicate Detection

Phase 4:
- Lyrics                - Mini-Player            - Theme Variants
- Sleep Timer           - Gesture Controls       - Shortcuts
- Animations            - Smart Playlists        - Export
- Search History        - Collaboration
- Better Browse
```

---

## ⏱️ Timeline & Aufwand

| Phase | Focus | Dauer | Team-Größe | Cumulative |
|-------|-------|-------|-----------|-----------|
| **1** | Server MVP | 2-3 W | 1-2 | 2-3 W |
| **2** | Offline + Sync | 4-6 W | 2-3 | 6-9 W |
| **3** | Audio + Local | 4-6 W | 2 | 10-15 W |
| **4** | UX Polish | 3-4 W | 2 | 13-19 W |
| **5+** | Advanced | 2-3 M | 1-2 | 3-5 M |

**Gesamtschätzung bis Spotify-Parity: ~4-5 Monate** (mit 1-2 Entwickler)

---

## 🎯 Success Criteria pro Phase

### Phase 1 ✓
- Server-Streaming stabil (>95% uptime in Test)
- Keine Critical Crashes
- 50+ Tests grün
- Lokal 5 Lieder cachbar

### Phase 2
- Offline-Mode funktioniert komplett
- Multi-Device Sync zuverlässig
- Nutzer können 100+ Songs cachen
- Lock Screen Controls arbeiten

### Phase 3
- Gapless Playback funktioniert
- Loudness Normalization auf ±2dB
- Local Musik als echte Fallback
- Metadata Editor ohne Crashes

### Phase 4
- Lyrics Sync funktioniert
- Sleep Timer robust
- Mini-Player nie freezes
- App fühlt sich "Finished" an

### Phase 5+
- Tags funktionieren parallel zu Playlisten
- Auto-Recommendations mit >70% Accuracy
- Podcast Support stabil

---

## ⚠️ Risks & Mitigations

| Risk | Mitigation | Phase |
|------|-----------|-------|
| Server (Navidrome) Down → App broken | Offline-Mode, Local Fallback | 2 |
| Caching-Bugs verlieren User-Daten | Rigorous Testing, Backup/Restore | 2 |
| Gapless sehr schwer zu implementieren | Early Spike (just_audio support prüfen) | 3 |
| Audio-Quality-Probleme bei Stream | Quality Selection + Bitrate-Tests | 3 |
| Podcast Support braucht viel Code | Optional in Phase 5+, nicht kritisch | 5 |

---

## 🔄 Dependency Tree (Was muss zuerst done sein)

```
Phase 1: Server MVP (Foundation)
   ↓
Phase 2: Offline + Caching (Built on 1)
   ├─→ Phase 3: Audio Quality (Parallel)
   │    ↓
   ├─→ Phase 4: UX Polish (Built on 1-3)
   │    ↓
   └─→ Phase 5+: Advanced (Can be Parallel)
```

**Können parallel:** Phase 2 + 3 + 4 (nach Phase 1 MVP done)

---

## 📝 Nächste Schritte

1. ✅ **Brainstorming & Design** (dieses Dokument)
2. → **Implementation Planning** (invoke writing-plans skill)
3. → **Phase 1 Sprint** (2-3 Wochen)
4. → **Phase 2-4 Parallel** (10-12 Wochen)
5. → **Beta Launch** (nach Phase 4)
6. → **Phase 5+ Iterations** (Post-Launch)

---

## 🔒 Datenschutz-Backlog (Folge-Tasks)

- [ ] **Diagnose-Logging auf Opt-in umstellen** (Folge zu Branch
  `feature/log-datenschutz-scrubber`). Aktuell werden Logs standardmäßig an
  `logs.baka-net.de` gesendet (jetzt zwar bereinigt, aber ohne Einwilligung).
  Nötig:
  - Consent-Flag in `SharedPreferences` (Default: **aus**), im Onboarding /
    in den Einstellungen abfragen.
  - `LoggerService._uploadLogs()` respektiert das Flag (kein Upload ohne
    Einwilligung; lokaler `debugPrint`/Puffer bleibt).
  - Optional: „Logs jetzt senden"-Button + Hinweistext (was wird gesendet).
  - Priorität: P1 (rechtlich relevant vor öffentlichem Launch).

---

## 📚 Referenzen

- Design-Decisions: `/home/dustin/.claude/projects/-home-dustin-mello-dev/memory/project_mello-v3-design.md`
- Feature-Candidates: `/home/dustin/.claude/projects/-home-dustin-mello-dev/memory/project_mello-feature-candidates.md`
- App-Repo: `/home/dustin/mello-dev/app`
- Navidrome-Docs: https://www.navidrome.org/docs/

---

**Geschrieben:** 2026-08-19 | **Status:** Ready for Implementation Planning