Treat the app as a durable media catalog, not a transient file scan.
If a local file disappears because the user deleted it, moved it, or freed disk space, that should not erase:
- watch history
- playback history
- metadata
- content hashes
- torrent identity
- the fact that this media item existed in the catalog
The catalog should outlive any one scan result.
- Stable local IDs for routing and UI
- Per-device playback history stored as separate facts
- Sync that copies facts between devices instead of reconciling mutable rows
- Scan behavior that marks items missing instead of deleting them
- TMDB as enhancement only, never a requirement for the app to function
- A design that is easy to test in isolation
We do not need backwards compatibility for this phase. It is acceptable to reset IndexedDB and rebuild on a cleaner schema.
Phases 1 through 7 are now implemented in the codebase.
What exists today:
catalogis the durable media table- scan reconciles into
catalogand marks unseen items asmissing playbackstores local per-device playback stateremotePlaybackcaches playback facts pulled from other devicescatalogAliasesstores every known cross-device identity for a catalog rowpendingHandoffsretains download-to-resume intent until media is playable- sync pushes local
playbackfacts and does not merge remote state into local media rows - player resume/save behavior uses
catalogId -> canonicalPlaybackKey -> playback - catalog, movie, and TV pages derive local progress from
catalog + playback - the old
librarytable has been removed
Previously one LibraryEntry row tried to serve too many roles at once:
- scan result
- local playback state
- remote sync merge target
- metadata container
- torrent state container
- UI view model
That makes the row fragile. Multiple writers update it for unrelated reasons, and scan currently deletes and recreates rows while manually preserving fields from the old row.
This creates a brittle system:
- scan must know which playback fields to preserve
- sync must know which local fields it is allowed to overwrite
- UI reads depend on fields whose ownership is unclear
- a new field can be lost unless every write path preserves it correctly
The real issue is not just “missing a field during rescan.” The issue is that storage ownership is unclear.
We need two identities, not one:
catalogId: stable local identity for routes, UI, and local joinsplaybackKey: cross-device identity for relating playback facts across devices
These should not be the same thing.
catalogId should be stable once created. It does not need to mean anything outside the local database.
playbackKey is only for cross-device playback matching. It can be best-effort, and it can improve over time as stronger identity becomes available.
Each table should have a clear owner:
- scan owns catalog presence and file attributes
- metadata enrichment owns metadata fields
- player owns local playback events
- sync owns copying playback facts between devices
No writer should need to preserve another writer's fields.
A normal rescan should not remove catalog rows just because a file is absent.
Instead:
- present locally: mark available
- not found locally: mark missing
That preserves history and metadata. Actual deletion should be an explicit product decision, not an incidental side effect of scan.
The app must still work if TMDB is disabled, rate-limited, or never configured.
That means:
- local cataloging must work without TMDB
- local playback must work without TMDB
- local routing must work without TMDB
- cross-device playback matching should still have a non-TMDB fallback
TMDB can improve identity and presentation, but it cannot be foundational to basic behavior.
The durable local media catalog.
One row represents one locally known media item. This row persists even if the local file later disappears.
Suggested fields:
| Field | Purpose |
|---|---|
id |
stable local primary key |
createdAt |
when this catalog row was first created |
updatedAt |
last catalog-level update |
name |
display/file name |
path |
most recent known path |
directoryId |
last known directory source |
size |
most recent known size |
lastModified |
most recent known mtime |
availability |
present or missing |
lastSeenAt |
last successful scan that saw this item |
firstMissingAt |
when it first became missing |
detectedMediaType |
local parser output |
parsedTitle, parsedYear |
local parser output |
seasonNumber, episodeNumber, endingEpisodeNumber |
local parser output |
seriesMetadataKey, movieMetadataKey |
metadata enrichment output |
contentHash |
stronger local identity when available |
torrentInfoHash, torrentFileIndex, torrentMagnetUrl, torrentComplete |
torrent identity/state |
canonicalPlaybackKey |
persisted current best playback key |
Important properties:
idis for local stability only- scan updates rows in place when it can match them
- rows are not removed during ordinary rescans
- metadata and hashes remain attached even after files are missing
- this is the long-term replacement for
library
Per-device playback facts.
This table stores only the local device's playback state.
Suggested fields:
| Field | Purpose |
|---|---|
playbackKey |
cross-device identity |
deviceId |
local device id |
positionSec |
last known position |
durationSec |
last known duration |
watchState |
unwatched, in-progress, watched |
lastPlayedAt |
last playback event timestamp |
updatedAt |
row update timestamp |
Primary key can be [deviceId+playbackKey].
This table does not care whether the media is currently present locally.
Cached playback facts from other devices.
Suggested fields:
| Field | Purpose |
|---|---|
playbackKey |
cross-device identity |
deviceId |
remote device id |
deviceLabel |
display label |
deviceLastSyncedAt |
source device freshness |
positionSec |
remote last known position |
durationSec |
remote duration |
watchState |
remote watch state |
lastPlayedAt |
remote playback timestamp |
title |
display fallback from sync doc |
seasonNumber, episodeNumber |
grouping/display fallback |
contentHash |
local resolution locator |
torrentInfoHash, torrentFileIndex, torrentMagnetUrl, torrentComplete |
torrent resolution and recovery |
tmdbId, tmdbMediaType |
optional grouping/resolution locator |
updatedAt |
when cache was refreshed |
This is read-only from the app's perspective except for sync refreshes.
library is now a temporary compatibility table only.
It is scheduled for removal.
It should not gain new responsibilities.
It should not be treated as durable truth.
It should remain, at most, a short-lived projection while the remaining read paths move to catalog.
Key upgrades are explicit rather than destructive. The alias table stores:
| Field | Purpose |
|---|---|
catalogId |
local catalog row |
playbackKey |
known key for this catalog item |
source |
file, hash, torrent, tmdb |
createdAt |
first seen |
This lets one catalog item accumulate multiple known identities over time without rewriting playback rows. Scan reconciliation and resolver startup backfill aliases for existing catalog rows.
Durable resume intent created before a torrent protocol handoff.
| Field | Purpose |
|---|---|
id |
stable torrent/file or playback identity used for deduplication |
sourceDeviceId, sourceDeviceLabel, sourcePlaybackKey |
provenance |
positionSec, durationSec, watchState |
intended resume state |
contentHash, torrentInfoHash, torrentFileIndex, magnetUrl |
local reconciliation locators |
status |
waiting-for-media, ready, consumed, or expired |
targetCatalogId, localPlaybackKey |
resolved local target when ready |
createdAt, updatedAt, expiresAt, readyAt, consumedAt |
lifecycle timestamps |
Waiting entries expire after 30 days; consumed entries are retained for 7 days. Repeated actions for the same torrent/file identity update one row. Scans mark a matching locally playable target ready, and the player marks it consumed only after engine initialization succeeds.
The local app should route by catalogId.
Examples:
/play/:catalogId- sidebar links
- local joins between catalog and UI state
This gives us stable local behavior even if cross-device identity is weak or unavailable.
If we later add shareable or cross-device locator URLs, they should be alternate resolver entrypoints that map to a local catalog row. They should not replace catalogId as the primary local route.
playbackKey should be persisted, not recomputed ad hoc in every read path.
Priority can still be:
- torrent identity
- content hash
- TMDB identity
- weak file fallback
But this must be treated carefully:
- weak keys are best-effort only
- TMDB-based upgrades should not break local routing
- changes to duration or metadata should not silently orphan playback state
That means the current fallback strategy is too fragile if it includes mutable fields like duration.
A better rule is:
- compute a candidate key
- persist it onto the catalog row as
canonicalPlaybackKey - if a stronger key becomes available later, migrate deliberately or add an alias
Do not make cross-device identity depend on volatile playback-derived fields.
Scan should update catalog presence, not rebuild the world.
If a scanned file matches an existing catalog row:
- keep the same
catalogId - update path/size/mtime/availability
- update parsed media fields if needed
- preserve metadata, hashes, and history
If no catalog row matches:
- create a new row
- assign new
catalogId - mark
availability = present
If an existing catalog row is not seen in the latest scan:
- do not delete it
- mark
availability = missing - set
firstMissingAtif not already set
This supports the product model where watched items remain in the catalog after local deletion.
Matching should be explicit and tested. Likely priority:
- torrent identity
- content hash
- exact path match
- file fingerprint fallback like
name + size + lastModified
This is separate from cross-device playback identity. It is local scan matching.
The player writes only to local playback.
It does not write into catalog except possibly for harmless catalog facts like cached duration if we decide that belongs there.
Sync push reads local playback rows for thisDevice and uploads them as that device's playback facts.
If display metadata is needed in the sync doc, push can join playback back to catalog by playbackKey or alias.
Sync pull reads all device docs and writes them into remotePlayback.
It does not merge remote state into local playback.
It does not overwrite catalog.
Resume is a UI policy built on top of facts:
- check local
playbackfor this device - optionally inspect
remotePlaybackfor other devices - choose most recent or prompt the user
This keeps sync deterministic:
- sync copies facts
- UI chooses behavior
“Deletion propagation” would mean a file disappearing from one device or one scan causes that media item to be deleted or hidden globally.
That does not match the desired product behavior.
In this app:
- file presence is local
- playback history is global per device
- metadata is durable
- absence from a scan is not a global delete event
So ordinary scans should never produce cross-device deletion semantics.
If we ever want true delete behavior later, it should be explicit and user-driven, like:
- remove this catalog item permanently
- clear playback history
- forget metadata
That is a different feature from scan.
Since we are fine with wiping old IndexedDB state, the cleanest path is not a compatibility migration. It is a schema reset and code simplification.
Create clean Dexie tables for:
catalogplaybackremotePlayback- optionally
catalogAliases
Also introduce explicit types for:
- catalog row
- playback row
- remote playback row
- scan match result
- playback key candidate
Do this before changing UI code.
Move core logic into pure modules with no Dexie calls:
catalog-match.tsplayback-key.tsresume-policy.tssync-device-doc.ts
These modules should operate on plain objects only.
This is the main step that makes the design testable and predictable.
Replace delete-and-recreate scan flow with:
- load existing catalog state
- match scanned files to existing rows
- update matched rows in place
- insert unmatched rows
- mark unseen rows as missing
No playback logic should exist in scan.
Make the player read and write only playback.
Player startup:
- load catalog row by
catalogId - resolve its
canonicalPlaybackKey - read local playback row for
(deviceId, playbackKey) - apply resume policy
Player save:
- write playback row
- optionally trigger sync
Push:
- local
playbackfor this device -> Firestore device doc
Pull:
- Firestore device docs ->
remotePlayback
No merge into local playback. No writes into catalog.
Examples:
- sidebar: latest local playback joined to catalog
- library grid: catalog rows with joined local playback
- devices page: grouped
remotePlayback - player links: always local
catalogId
After the compatibility reads are gone:
- move grouping and browse pages fully to
catalog - move file access helpers to accept
CatalogEntryor a narrower file-source type - remove legacy playback fields from
LibraryEntry - delete the
librarytable entirely
The desired end state is:
catalogis the only durable media tableplaybackis the only local playback tableremotePlaybackis the only remote playback cache- “present locally” is derived from
catalog.availability, not from a second media table
The implementation should be built from pure logic tests upward.
Test scan matching independently.
Examples:
- exact same file rescanned keeps same
catalogId - renamed file with same hash matches existing row
- torrent-backed item matches by torrent identity
- absent file becomes
missing, not deleted
Test playback key generation independently.
Examples:
- torrent key wins over hash
- hash wins over TMDB
- TMDB key works when metadata exists
- fallback works without TMDB
- mutable fields do not change the fallback key unexpectedly
Test resume choice as a pure function.
Examples:
- local playback beats remote when newer
- remote suggestion appears when local history is absent
- watched item starts over unless user chooses resume
Test conversion between local playback rows and Firestore docs.
Examples:
- push includes only this device's rows
- pull produces one cached row per
(deviceId, playbackKey) - no remote pull mutates local playback
Use Dexie-backed tests only after pure matching logic is solid.
Examples:
- initial scan creates catalog
- rescan updates rows in place
- missing files remain queryable
Keep UI data shaping out of components when possible.
Test selectors like:
getNowPlayinggetLibraryEntriesWithPlaybackgetResumeCandidate
These should mostly be joins over plain rows.
- Stop thinking of scan as the source of truth for whether a catalog row deserves to exist
- Make catalog durability the default and deletion the exception
- Keep local routing on stable
catalogId - Keep cross-device playback identity separate from local identity
- Persist identity decisions instead of recomputing them everywhere
- Build the new system by testing pure functions before Dexie integration
- Remove
libraryrather than letting it harden into a second source of truth
The smallest useful clean-slate implementation is:
- create
catalog,playback, andremotePlayback - route player by
catalogId - rewrite scan to mark missing instead of deleting
- rewrite player to store playback separately
- rewrite sync to copy playback facts only
That gets us most of the architectural benefit without needing to solve every identity refinement on day one.
TMDB can remain purely additive.