docs: fold shipped specs into the architecture docs and delete them
A spec was a promise; sixteen of them had become descriptions of code that already shipped, sitting beside four that describe work still outstanding, with nothing in the file telling the two apart. Half the statuses were also wrong — audio-equalizer read "Accepted" with the EQ live on both platforms, the native video spec said the flag stays off after the default was flipped on. The shipped designs move into docs/architecture, which is the maintained description of the build, and the spec files go. Git history keeps the originals; what a future change still needs is carried across: - 01-rust-backend: favourites rewritten (the old section named a file that no longer exists and called shipped buttons "planned"), domain vocabulary owned by Rust (SearchScope, exclusions, the bitrate ladder), background workers - 02-svelte-frontend: app shell and chrome, library mosaic, series/episode navigation, downloaded browse, safe-area insets, native-video store, logging - 03-data-flow: locally-indexed search - 05-platform-backends: audio settings on ExoPlayer, the equalizer's band vocabulary, native video compositing, the background-audio handoff - 06-downloads-and-offline: one storage model, offline catalog visibility - 09-security: path confinement and input binding docs/specs/README.md now says what the directory is for and where each shipped design went. Deferred work the specs recorded is kept beside the code it concerns rather than lost: season-bounded autoplay, the two dead search commands, why indexing is a full crawl. requirements.md had fourteen stale statuses — Android audio parity still read "Linux only", DR-150 still said the native-video default was off, DR-190 was Proposed after DR-196 implemented it, and five tooling requirements were Proposed after landing. Three unbuilt specs suggested requirement ids that have since been allocated to other work; each now carries a warning.
This commit is contained in:
@@ -49,6 +49,61 @@ sequenceDiagram
|
||||
- Background cache updates (planned)
|
||||
- **Connectivity side-effect**: each server request feeds the `ConnectivityMonitor`, which is the source of truth for the offline/online banner (see [07-connectivity.md](07-connectivity.md)). A server-answered error (401/404/5xx) still counts as *reachable* — only network failures, sustained past a debounce window, flip the app to offline.
|
||||
|
||||
## Search Flow (Locally Indexed)
|
||||
|
||||
**TRACES**: UR-065 | DR-108 … DR-111, IR-030
|
||||
|
||||
Search does not depend on a per-keystroke round trip to Jellyfin. The instant leg
|
||||
reads the **local SQLite catalog**, which is already synced and already
|
||||
FTS5-indexed, so results appear as fast as SQLite can answer — online or offline.
|
||||
The server query stays, demoted to a background reconciliation that merges in
|
||||
late results.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as Search UI
|
||||
participant Rust as repository_search
|
||||
participant Cache as Local catalog (FTS5)
|
||||
participant Server as Jellyfin
|
||||
participant Indexer as spawn_catalog_indexer
|
||||
|
||||
UI->>Rust: search(query, scope)
|
||||
Rust->>Cache: FTS5 query, scope expanded by SearchScope::item_types()
|
||||
Cache-->>UI: instant results
|
||||
Rust->>Server: reconciliation query (background)
|
||||
Server-->>UI: search-event with late/merged results
|
||||
Note over Indexer,Cache: Independent of any query:<br/>scheduled crawl keeps the index fresh,<br/>prunes items deleted on the server
|
||||
```
|
||||
|
||||
**Key points:**
|
||||
|
||||
- The **scope is opaque on the wire**. The frontend sends a `SearchScope`
|
||||
variant; Rust expands it to item types
|
||||
([01-rust-backend.md](01-rust-backend.md#search-scope-and-the-taxonomy-boundary)).
|
||||
- **Index freshness is a Rust policy**, not a frontend startup call — a scheduled
|
||||
background pass, not "whatever was synced when the app last launched"
|
||||
(DR-109). See
|
||||
[Background workers](01-rust-backend.md#background-workers).
|
||||
- **Index hygiene matters as much as freshness**: the catalog save path uses
|
||||
`INSERT OR REPLACE` and the crawl prunes rows for content deleted on the
|
||||
server, or search keeps returning items that no longer exist (DR-110).
|
||||
- The index covers **exactly the types the result groups render** (DR-111) —
|
||||
including Artists, which the crawl must reach or the Artists group is silently
|
||||
always empty.
|
||||
|
||||
**Deliberately not done, with reasons:**
|
||||
|
||||
- **Incremental indexing** (Jellyfin's `MinDateLastSaved`). A *full* crawl is
|
||||
what makes the deletion sweep sound — it yields the authoritative id set per
|
||||
library, and an incremental pass cannot detect deletions. Worth revisiting if
|
||||
full crawls prove slow on large libraries; measure first.
|
||||
- **Removing the server leg.** The reconciliation query stays.
|
||||
|
||||
> ⚠️ Two dead search implementations still exist: `storage_search_items`
|
||||
> (`commands/storage/mod.rs`) and `offline_search` (`commands/offline.rs`). Both
|
||||
> are registered in `lib.rs` and exported to `bindings.ts`; neither is called
|
||||
> from the frontend. Deleting them is correct and unclaimed.
|
||||
|
||||
## Playback Initiation Flow
|
||||
|
||||
```mermaid
|
||||
|
||||
Reference in New Issue
Block a user