398 lines
15 KiB
Markdown
398 lines
15 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 | 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.
|