@startuml MonitorAlbum - Metadata Fetch Failures
skinparam sequenceMessageAlign center
skinparam responseMessageBelowArrow true
title MonitorAlbum Error: Metadata Fetch Failures

actor Client
participant "MusicAgregatorService" as Service
participant "MetadataService" as Metadata
database "metadata-agregator\n(gRPC)" as MetaGRPC
database "PostgreSQL" as DB

== Case 1: metadata-agregator unreachable ==

Client -> Service: MonitorAlbum(album_id, quality)
Service -> Metadata: GetAlbum(album_id)
Metadata -> MetaGRPC: GetAlbum(id)
MetaGRPC --> Metadata: gRPC error (Unavailable)
Metadata --> Service: error: "fetching album: ..."
Service --> Client: error (Unavailable)
note right: Full stop.\nNo DB writes occur.\nNo indexer search.

== Case 2: Album not found in metadata ==

Client -> Service: MonitorAlbum(album_id, quality)
Service -> Metadata: GetAlbum(album_id)
Metadata -> MetaGRPC: GetAlbum(id)
MetaGRPC --> Metadata: gRPC error (NotFound)
Metadata --> Service: error: "fetching album: ..."
Service --> Client: error (NotFound)
note right: Full stop.\nInvalid album_id.\nNo side effects.

== Case 3: Album found, but artist persist fails ==

Client -> Service: MonitorAlbum(album_id, quality)
Service -> Metadata: GetAlbum(album_id)
Metadata -> MetaGRPC: GetAlbum(id)
MetaGRPC --> Metadata: Album

Metadata -> DB: albums.GetByExternalID()
DB --> Metadata: not found

Metadata -> DB: artists.Create()
DB --> Metadata: error (e.g. connection lost)
note right #salmon: Artist persist fails.\nLogged as warning.\nFlow continues.

Metadata -> DB: albums.Create()
note right #salmon: artistID is empty\n→ album persist skipped\n(no artist reference)

Metadata --> Service: Album (metadata only)

Service -> DB: albums.GetByExternalID()
DB --> Service: not found (album never persisted)
note right #salmon: dbAlbum is nil.\nMonitor state not set.\nOwnership check skipped.

Service -> Service: continues to indexer search...
note right: Flow proceeds but\ndownload persistence\nwill be skipped later\n(dbAlbum == nil)

@enduml