# Velody Roadmap

This document is the permanent roadmap and milestone status source of truth for Velody.
When milestone scope, sequencing, or status changes, update this file first.

## Status Summary

| Milestone | Name | Status |
| --- | --- | --- |
| 1 | Foundation | Completed |
| 2 | Device Registration | Completed |
| 3 | Local Library Discovery | Completed |
| 4 | Local Catalog Ownership | Completed |
| 5 | Playback Engine | Completed |
| 6 | Upload Pipeline | Completed |
| 7 | iPhone Sync Foundation | Completed |
| 8 | iPhone User Experience | Completed |
| 9 | Ownership & Security | Completed |
| 10 | Offline Resilience Program | In Progress |
| 10.1 | Multi-device Identity Foundation | Completed |
| 10.2 | Incremental Sync Cursors | Completed |
| 10.3 | Offline Recovery | Completed |
| 10.4 | iPhone Playback Controls | Completed |
| 10.5 | Offline Sync Polish Audit | Completed |
| 10.6 | Offline Resilience E2E | Completed |
  Completed:
- Relaunch resilience tests
- Backend unavailable tests
- Cached remote library survival
- Favorite/download/artwork persistence during outage
- Offline playback after relaunch
- Artwork replacement coverage
- Asset replacement coverage
- Track deletion handling
- Sync cursor recovery across backend failure
| 11 | Accounts | Planned |
| 12 | Monetization | Planned |
| 13 | Pro Features | Planned |

## Milestone 1 Foundation

**Goal**  
Establish the project structure, backend foundation, Apple workspace, and core architectural decisions for a private personal music system.

**Major features**

- Monorepo structure for Apple apps, shared Swift packages, backend services, infrastructure, and docs.
- NestJS backend scaffold with Prisma, configuration, health checks, and local Docker support.
- Apple workspace setup for `macOS` and `iPhone` targets plus shared package wiring.
- Initial project architecture documented in `docs/PROJECT_ENVIRONMENT_ARCHITECTURE.md`.

**Current status**  
Completed

**Completion notes**  
The repository now has a stable implementation base, local development environment, and shared architectural direction. Later milestones build on this structure rather than replacing it.

## Milestone 2 Device Registration

**Goal**  
Give each client a recognized device identity so the backend can authenticate and track trusted app installs.

**Major features**

- Device registration endpoint with generated device access tokens and bootstrap tokens.
- Stored device metadata including platform, device name, app version, and last seen timestamps.
- Heartbeat flow for refreshing device activity.
- Keychain-backed device credential persistence in the Apple clients.

**Current status**  
Completed

**Completion notes**  
Velody can now register trusted devices, persist credentials locally, and use those identities for authenticated backend requests.

## Milestone 3 Local Library Discovery

**Goal**  
Discover music on `macOS` from a user-selected folder and extract enough metadata to build a usable local library.

**Major features**

- Folder selection and restoration for the local music source.
- Recursive `MP3` scanning on `macOS`.
- Metadata extraction for title, artist, album, duration, and embedded artwork.
- File hashing and file modification capture for later deduplication and upload work.

**Current status**  
Completed

**Completion notes**  
The Mac app can scan a local folder, recognize supported music files, and produce structured local track data ready for cataloging and upload.

## Milestone 4 Local Catalog Ownership

**Goal**  
Turn local discovery into a durable app-owned catalog instead of a transient scan result.

**Major features**

- Persistent local track repository and library store.
- Catalog reconciliation that inserts, updates, reactivates, merges, and soft-deletes scanned tracks.
- Deduplication based on stable keys rather than raw file paths alone.
- Local track state that keeps upload status, artwork, remote linkage, and scan timestamps.

**Current status**  
Completed

**Completion notes**  
Repeated scans now update a single durable local catalog. Missing files are marked deleted, returning files can be reactivated, and duplicate scan results are merged into canonical records.

## Milestone 5 Playback Engine

**Goal**  
Provide a shared playback core for Apple clients so library items can be played locally with standard transport behavior.

**Major features**

- Shared `VelodyPlayback` package backed by `AVFoundation`.
- Play, pause, stop, seek, next, and previous controls.
- Queue management with shuffle and repeat support.
- Playback session persistence and restore across launches.
- Playback error handling for empty queues, missing files, and engine failures.

**Current status**  
Completed

**Completion notes**  
Velody now has a reusable playback engine shared across clients, which reduces duplicated platform logic and enables richer playback experiences in later milestones.

## Milestone 6 Upload Pipeline

**Goal**  
Move trusted local music from the Mac catalog into the backend library with validation, storage, and change tracking.

**Major features**

- Upload prepare, transfer, status, and finalize backend endpoints.
- File validation for size, type, and `SHA-256` integrity.
- Audio asset deduplication by owner and hash.
- Track, audio asset, and artwork asset persistence during finalize.
- Library event generation so downstream sync clients can observe changes.
- Mac upload actions for selected tracks and bulk upload flow with progress states.

**Current status**  
Completed

**Completion notes**  
Uploads now complete the full ingest loop: prepare, validate, store, finalize, attach metadata, and emit sync-visible library events.

## Milestone 7 iPhone Sync Foundation

**Goal**  
Give the `iPhone` app a working path to consume the remote Velody library and cache it locally.

**Major features**

- `iPhone` networking client for Velody API access.
- Remote library bootstrap sync flow.
- Local persistence for cached remote tracks, download states, audio files, and artwork.
- Sync service and repository abstractions for remote library updates and asset downloads.
- Device self-registration flow on `iPhone` using persisted credentials.

**Current status**  
Completed

**Completion notes**  
The phone can now identify itself, fetch the remote library, cache it locally, and download assets needed for offline listening.

## Milestone 8 iPhone User Experience

**Goal**  
Turn sync and download capabilities into a usable browsing experience on `iPhone`.

**Major features**

- Remote library and available offline sections.
- Search and filtering across cached library data.
- Download actions and per-track download state display.
- Empty, loading, and connection-failure states with user-facing copy.
- Favorites persistence and now playing presentation groundwork.

**Current status**  
Completed

**Completion notes**  
The `iPhone` experience now supports real library browsing instead of raw data plumbing, including search, download workflows, and clearer feedback when the app is empty or offline.

## Milestone 9 Ownership & Security

**Goal**  
Enforce library ownership boundaries and require authenticated device access for protected backend operations.

**Major features**

- Owner context resolution for the single-owner bootstrap model.
- Bearer device access tokens with hashing, validation, and last-used tracking.
- Owner-scoped queries for devices, library records, uploads, audio assets, and artwork assets.
- Middleware and guards for protected device-authenticated routes.
- Tests that reject cross-owner access and foreign-device access patterns.

**Current status**  
Completed

**Completion notes**  
Velody now consistently treats the library as owner-scoped data. Backend operations no longer rely on trust alone and instead enforce device and owner boundaries at the service layer.

## Milestone 10 Offline Resilience Program

**Goal**  
Harden the multi-device sync and offline playback experience so it survives real-world interruptions, stale state, and repeated client restarts.

**Major features**

- Stable per-device identity across Apple clients.
- Incremental sync with persisted cursors and bootstrap fallback.
- Offline recovery for interrupted downloads and missing local files.
- Richer `iPhone` playback controls and session continuity.
- UX and behavior polish across sync, playback, favorites, and download states.
- Final end-to-end resilience coverage.

**Current status**  
In Progress

**Completion notes**  
Milestones `10.1` through `10.5` are complete. Milestone `10.6` is still planned, so the umbrella milestone remains open.

## Milestone 10.1 Multi-device Identity Foundation

**Goal**  
Make device identity stable enough to support repeated sync and download activity across more than one trusted client.

**Major features**

- Durable storage of device identifiers and access tokens in Apple clients.
- Backend device records tied to a specific owner, platform, and app version.
- Restore flows that reuse device identity instead of creating duplicate devices on every launch.
- Shared identity assumptions across `macOS`, `iPhone`, and backend services.

**Current status**  
Completed

**Completion notes**  
Velody devices can now come back as the same logical device across app launches, which is a prerequisite for reliable sync cursors, download ownership, and activity tracking.

## Milestone 10.2 Incremental Sync Cursors

**Goal**  
Avoid reloading the entire library for every sync by moving to cursor-driven incremental updates.

**Major features**

- Append-only `library_events` change log.
- `sync/changes` endpoint with paging and `hasMore` handling.
- Persisted client-side sync cursor storage.
- Server-side per-device sync cursor tracking.
- Bootstrap fallback when a client cursor is too old to recover incrementally.

**Current status**  
Completed

**Completion notes**  
The `iPhone` sync path now applies deltas when possible and automatically falls back to bootstrap when retained events are no longer sufficient.

## Milestone 10.3 Offline Recovery

**Goal**  
Recover cleanly from interrupted downloads, stale file paths, and missing offline assets.

**Major features**

- Download state reconciliation on restore.
- Recovery from interrupted download states after relaunch.
- Asset-based local file path resolution when persisted paths go stale.
- Explicit missing-file detection and user-facing error states.
- Offline library snapshot rebuild based on cached remote tracks plus available local files.

**Current status**  
Completed

**Completion notes**  
The offline library can now restore itself more safely after app restarts and partial failures, and it surfaces missing or broken downloads as recoverable states instead of silent corruption.

## Milestone 10.4 iPhone Playback Controls

**Goal**  
Bring the `iPhone` player up to expected music-app behavior for offline listening.

**Major features**

- Previous, next, stop, and seek controls.
- Shuffle and repeat controls.
- Persisted playback queue and session restore.
- Richer now playing model with progress, duration, badges, and error messaging.
- Shared playback behavior with the underlying `VelodyPlayback` package.

**Current status**  
Completed

**Completion notes**  
Offline playback on `iPhone` now behaves like a real player rather than a minimal preview flow, with standard transport controls and state restoration.

## Milestone 10.5 Offline Sync Polish Audit

**Goal**  
Audit the end-user sync and offline experience and tighten rough edges before final end-to-end validation.

**Major features**

- Better cached-library restore behavior and status messaging.
- Connection-failure handling that preserves usable cached data.
- Artwork cache usage across remote and offline library views.
- Favorites restore and persistence flow cleanup.
- Additional targeted tests around playback, favorites, and sync behavior.

**Current status**  
Completed

**Completion notes**  
The product flow has been polished substantially, but Milestone `10` still requires a full resilience-oriented end-to-end pass before it can be marked complete.

## Milestone 10.6 Offline Resilience E2E

**Goal**  
Prove that the full Mac-to-backend-to-`iPhone` pipeline remains reliable across interruptions and recovery scenarios.

**Major features**

- End-to-end coverage for ingest, sync, download, relaunch, and offline playback.
- Regression scenarios for interrupted downloads and missing local files.
- Validation of stale-cursor bootstrap fallback behavior.
- Multi-device consistency checks for library state and cursor advancement.
- Final resilience sign-off criteria for closing Milestone `10`.

**Current status**  
Planned

**Completion notes**  
Not started yet. This milestone is the remaining gate for closing the broader offline resilience program.

## Milestone 11 Accounts

**Goal**  
Move beyond the current single-owner bootstrap model and introduce formal user accounts.

**Major features**

- Account creation, sign-in, and session management.
- Migration from bootstrap ownership to account-linked ownership.
- Device enrollment and recovery flows tied to a real account.
- Backend identity model changes needed to support account lifecycle operations.

**Current status**  
Planned

**Completion notes**  
Not started yet. The current codebase intentionally assumes a private single-owner system, so this milestone begins the transition to explicit account identity.

## Milestone 12 Monetization

**Goal**  
Introduce billing and entitlements once account identity exists and the core product flow is stable.

**Major features**

- Subscription plan and entitlement model.
- Billing provider integration and event handling.
- Upgrade, downgrade, renewal, and cancellation support.
- Plan-aware gating for server and client features.
- Basic internal reporting for billing state and entitlement debugging.

**Current status**  
Planned

**Completion notes**  
Not started yet. Monetization is intentionally deferred until core sync reliability and account identity are in place.

## Milestone 13 Pro Features

**Goal**  
Ship high-value premium capabilities on top of a stable paid Velody foundation.

**Major features**

- Advanced offline automation and smart download rules.
- Power-user library management and metadata tools.
- Premium playback and cross-device continuity improvements.
- Advanced diagnostics, backup, or admin-oriented controls.
- Feature rollout tied to entitlement checks.

**Current status**  
Planned

**Completion notes**  
Not started yet. The exact scope should be finalized only after Milestones `11` and `12` define the account and entitlement model.

## Future Ideas

The items below are intentionally outside the committed milestone plan above. They are good candidates for later evaluation after the current roadmap stabilizes.

- Background folder watching on `macOS` so manual rescans become optional.
- Background downloads and periodic refresh on `iPhone`.
- Support for formats beyond `MP3` once the current ingest path is fully hardened.
- Smart playlists, richer sorting, and advanced search filters.
- Lock screen, external control, and car-focused playback integrations.
- Library health tooling such as orphaned asset cleanup, re-hash verification, and storage audits.
- Backup and restore workflows for local offline state.