velody/docs/VELODY_ROADMAP.md

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	Planned
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.