@startuml MonitorAlbum - Torrent Client Failures
skinparam sequenceMessageAlign center
skinparam responseMessageBelowArrow true
title MonitorAlbum Error: Torrent Client Failures

actor Client
participant "MusicAgregatorService" as Service
participant "TorrentClient\n(qBittorrent)" as QBit
database "PostgreSQL" as DB

note over Service: Metadata fetched, indexer searched,\nbest release selected.

== Case 1: qBittorrent unreachable ==

Service -> QBit: Find(hash)
QBit --> Service: error (connection refused)
note right: Find() fails → skip existence check

Service -> QBit: AddMagnet(uri)
QBit --> Service: error (connection refused)
Service --> Client: error
note right #salmon: Album is persisted & monitored.\nNo torrent added.\nNo download record created.

== Case 2: Torrent already exists in qBit ==

Service -> QBit: Find(hash)
QBit --> Service: [TorrentInfo{state: stalledUP}]
note right #lightgreen: Torrent found.\nSkip AddMagnet/AddTorrent.

Service -> DB: torrents.Create (upsert)
Service -> DB: torrents.GetByInfoHash
DB --> Service: savedTorrent

Service -> DB: downloads.GetActiveByTorrentID(torrent_id)
DB --> Service: Download{state: completed}
note right #lightgreen: Active download exists.\nSkip duplicate insert.

Service --> Client: MonitorAlbumResponse
note right: Returns album + artist + release.\nNo duplicate download created.\nNo error.

== Case 3: AddTorrent fails (no torrent data) ==

Service -> QBit: Find(hash)
QBit --> Service: not found

note right: best.torrentData is nil\n(magnet resolve failed,\nfell back to title parse)

Service -> Service: len(best.torrentData) == 0
Service --> Client: error "no torrent data available"
note right #salmon: Magnet link but no\ntorrent data resolved.\nCannot add to client.

== Case 4: Torrent persists, but download insert fails ==

Service -> QBit: AddMagnet(uri)
QBit --> Service: OK

Service -> DB: torrents.Create (upsert)
Service -> DB: torrents.GetByInfoHash
DB --> Service: savedTorrent

Service -> DB: downloads.GetActiveByTorrentID
DB --> Service: not found

Service -> DB: downloads.Create(download)
DB --> Service: error (constraint violation)
note right #salmon: Logged as error.\nTorrent is in qBit but\nno download record.\nResponse still returned\n(non-fatal within saveTorrentAndDownload).\nNo poll job scheduled.

Service --> Client: MonitorAlbumResponse
note right #orange: Response includes release info.\nDownload info may be missing.\nTorrent is downloading in qBit\nbut untracked in DB.

@enduml