513 lines
19 KiB
Markdown
513 lines
19 KiB
Markdown
# 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 | Completed |
|
|
| 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 |
|
|
| 11 | Accounts | Completed |
|
|
| 11.1 | Account Foundation Audit | Completed |
|
|
| 11.2 | Account Schema + Namespace Foundation | Completed |
|
|
| 11.3 | Device Linking Foundation | Completed |
|
|
| 11.4 | Legacy Owner Claim & Transfer | Completed |
|
|
| 11.5 | OAuth Identity Providers | Completed |
|
|
| 11.6 | Device Management & Recovery | Completed |
|
|
| 11.7 | Authentication Runtime Foundation | Completed |
|
|
| 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**
|
|
Completed
|
|
|
|
**Completion notes**
|
|
All milestones `10.1` through `10.6` are complete.
|
|
Offline resilience program is production-ready and closed.
|
|
|
|
Completed coverage:
|
|
|
|
- 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
|
|
|
|
## 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**
|
|
Completed
|
|
|
|
**Completion notes**
|
|
Completed.
|
|
Added E2E resilience validation for relaunch, outages, offline playback, artwork replacement, asset replacement, deletion handling, and sync cursor recovery.
|
|
Milestone `10` is fully complete.
|
|
|
|
## 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**
|
|
Completed
|
|
|
|
**Completion notes**
|
|
All milestones `11.1` through `11.6` are complete.
|
|
|
|
The account foundation program is now closed. Velody now has internal foundations for account schema, device linking, legacy ownership transfer, OAuth identity mapping, and account-scoped device management/recovery while preserving the existing device-token music system.
|
|
|
|
## Milestone 11.1 Account Foundation Audit
|
|
|
|
**Current status**
|
|
Completed
|
|
|
|
**Completion notes**
|
|
Completed
|
|
|
|
## Milestone 11.2 Account Schema + Namespace Foundation
|
|
|
|
**Current status**
|
|
Completed
|
|
|
|
**Completion notes**
|
|
Completed
|
|
|
|
## Milestone 11.3 Device Linking Foundation
|
|
|
|
**Current status**
|
|
Completed
|
|
|
|
**Completion notes**
|
|
Completed.
|
|
|
|
This milestone added the internal device-linking foundation without exposing public linking routes, signup, login, OAuth, or UI. It added `linkedAt` and `relinkedAt` device fields, an internal `DeviceLinkingService`, device token rotation during linking, `DeviceLinkHistory` persistence, and safe sync cursor reset behavior when device ownership changes.
|
|
|
|
## Milestone 11.4 Legacy Owner Claim & Transfer
|
|
|
|
**Current status**
|
|
Completed
|
|
|
|
**Completion notes**
|
|
Completed.
|
|
|
|
This milestone added the internal ownership transfer foundation with COPY-only behavior, ownership transfer audit records, target-side asset/artwork deduplication, source-owner preservation, and target-user library event generation.
|
|
|
|
## Milestone 11.5 OAuth Identity Providers
|
|
|
|
**Current status**
|
|
Completed
|
|
|
|
**Completion notes**
|
|
Completed.
|
|
|
|
This milestone added the internal OAuth identity foundation for GOOGLE, APPLE, and GITHUB provider identities without exposing public OAuth routes, callbacks, sessions, or UI.
|
|
|
|
## Milestone 11.6 Device Management & Recovery
|
|
|
|
**Current status**
|
|
Completed
|
|
|
|
**Completion notes**
|
|
Completed.
|
|
|
|
This milestone added internal account-scoped device management and recovery foundations, including safe device listing, device revocation, recovery token rotation, ownership validation, and DeviceLinkHistory audit records.
|
|
|
|
## Milestone 11.7 Authentication Runtime Foundation
|
|
|
|
**Goal**
|
|
Add the runtime authentication foundation needed before monetization, without changing the existing device-token music system.
|
|
|
|
**Major features**
|
|
|
|
* Internal account session management.
|
|
* JWT access token foundation.
|
|
* Opaque refresh token foundation with secure rotation.
|
|
* Authentication runtime orchestration.
|
|
* Internal account authentication guard.
|
|
* Current authenticated account context.
|
|
* Authentication runtime validation and testing.
|
|
|
|
Current status
|
|
Completed
|
|
|
|
Completion notes
|
|
Completed.
|
|
|
|
All milestones 11.7.1 through 11.7.5 are complete.
|
|
|
|
Completed coverage:
|
|
|
|
* Internal Session Foundation
|
|
* Access Token Foundation
|
|
* Refresh Token Foundation
|
|
* Authentication Runtime Pipeline
|
|
* Authentication Guards Foundation
|
|
|
|
The backend now includes a complete internal account authentication runtime consisting of account sessions, JWT access tokens, opaque refresh tokens with secure rotation, runtime authentication orchestration, account authentication guards, and authenticated account context while preserving the existing device-token authentication system.
|
|
|
|
No public login, signup, logout, refresh endpoint, OAuth runtime, or frontend authentication flows have been exposed yet. The runtime foundation is complete and ready for future public authentication APIs.
|
|
|
|
## 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.
|