docs(design): add the download surface as §9.8

This commit is contained in:
Miguel Palhas
2026-08-26 12:12:37 +01:00
parent adb61dda3b
commit 54438bb6ad
+29 -1
View File
@@ -603,7 +603,8 @@ retry counts, dead-lettering and reconciliation against Transmission anyway,
because Transmission is an external system that changes underneath the app.
Transient state — a search in flight, download progress — is in memory and
rebuilt from Transmission on startup.
rebuilt from Transmission on startup. Where that state is ever seen is §9.8:
inline on the row that owns the item, never persisted.
Ticks are staggered: reconcile every 30 s, RSS every 10 min, metadata refresh
daily, reaper every 5 min.
@@ -754,6 +755,33 @@ is healthy survives the move and no navigation is needed to get it.
lamp and wordmark, a warning mark only while queues need attention, the centred
search, the version readout and the settings cog.
### 9.8 Downloads on the row
§8 keeps download progress as transient state; nothing in §9 so far says where
it is seen. Without a rule here, a season pack downloading and one that never
started look identical.
**Progress is inline, on the row that owns the item** — a movie row, a season
row for its pack, an episode row. There is no downloads page and no count in
the rail: a download is an attribute of the thing being downloaded, not a place
to visit.
Alongside progress the same row carries the other states a torrent can be in:
**seeding** under §7.3's obligation, **stalled**, **errored**.
**A torrent arr did not grab is never shown.** §2 already rules the service
knows only what it put on disk; Transmission's own UI lists the rest.
Nothing is persisted — no progress column, no new table. The snapshot comes
from Transmission and dies with the process (§8), refreshed by the UI's normal
polling cadence at roughly 15 s rather than SSE.
At phone width only active-grab progress survives; seeding and stalled shed
with the row's other secondary chips.
Out of scope here: any change to what the reconcile loop does, and any new
state machine — §7.3's two lifecycles stay as they are.
## 10. Persistence
SQLite via `sqlx`, compile-time-checked queries, migrations in `arr-db`.