music-agregator/docs/erd.puml

@startuml Music Aggregator ERD

skinparam linetype ortho
skinparam ranksep 60
skinparam nodesep 40

skinparam entity {
    BackgroundColor White
    BorderColor #333333
}

skinparam package {
    BackgroundColor #FAFAFA
    BorderColor #DDDDDD
}

title Music Aggregator - Database Structure

' ══════════════════════════════════════════════════════════════
' CORE MUSIC ENTITIES
' ══════════════════════════════════════════════════════════════

package "Core Music Entities" #E3F2FD {
    entity "artist_metadata" {
        * id : UUID <<PK>>
        --
        foreign_artist_id : TEXT <<UNIQUE>>
        name : TEXT
        sort_name : TEXT
        disambiguation : TEXT
        artist_type : TEXT
        status : TEXT
        overview : TEXT
        images : JSONB
        links : JSONB
        genres : JSONB
        --
        created_at : TIMESTAMPTZ
        updated_at : TIMESTAMPTZ
    }

    entity "artists" {
        * id : UUID <<PK>>
        --
        metadata_id : UUID <<FK>>
        quality_profile_id : UUID <<FK>>
        metadata_profile_id : UUID <<FK>>
        root_folder_id : UUID <<FK>>
        --
        path : TEXT
        monitored : BOOLEAN
        monitor_new_items : TEXT
        --
        last_info_sync : TIMESTAMPTZ
        added_at : TIMESTAMPTZ
    }

    entity "albums" {
        * id : UUID <<PK>>
        --
        artist_metadata_id : UUID <<FK>>
        --
        foreign_album_id : TEXT <<UNIQUE>>
        title : TEXT
        clean_title : TEXT
        disambiguation : TEXT
        overview : TEXT
        album_type : TEXT
        release_date : DATE
        images : JSONB
        genres : JSONB
        --
        monitored : BOOLEAN
        added_at : TIMESTAMPTZ
    }

    entity "album_releases" {
        * id : UUID <<PK>>
        --
        album_id : UUID <<FK>>
        --
        foreign_release_id : TEXT <<UNIQUE>>
        title : TEXT
        status : TEXT
        duration_ms : INT
        release_date : DATE
        country : TEXT[]
        label : TEXT[]
        format : TEXT
        track_count : INT
        --
        monitored : BOOLEAN
    }

    entity "tracks" {
        * id : UUID <<PK>>
        --
        album_release_id : UUID <<FK>>
        artist_metadata_id : UUID <<FK>>
        track_file_id : UUID <<FK NULL>>
        --
        foreign_track_id : TEXT <<UNIQUE>>
        title : TEXT
        track_number : INT
        disc_number : INT
        duration_ms : INT
        explicit : BOOLEAN
    }

    entity "track_files" {
        * id : UUID <<PK>>
        --
        album_id : UUID <<FK>>
        --
        path : TEXT
        relative_path : TEXT
        size : BIGINT
        --
        file_hash : TEXT
        audio_hash : TEXT
        --
        quality : JSONB
        media_info : JSONB
        --
        scene_name : TEXT
        release_group : TEXT
        --
        date_added : TIMESTAMPTZ
    }
}

' ══════════════════════════════════════════════════════════════
' CONFIGURATION
' ══════════════════════════════════════════════════════════════

package "Configuration" #FFF3E0 {
    entity "quality_profiles" {
        * id : UUID <<PK>>
        --
        name : TEXT <<UNIQUE>>
        cutoff : INT
        items : JSONB
        upgrade_allowed : BOOLEAN
    }

    entity "metadata_profiles" {
        * id : UUID <<PK>>
        --
        name : TEXT <<UNIQUE>>
        primary_album_types : JSONB
        secondary_album_types : JSONB
        release_statuses : JSONB
    }

    entity "root_folders" {
        * id : UUID <<PK>>
        --
        name : TEXT
        path : TEXT <<UNIQUE>>
        default_quality_profile_id : UUID <<FK>>
        default_metadata_profile_id : UUID <<FK>>
    }

    entity "indexers" {
        * id : UUID <<PK>>
        --
        name : TEXT
        implementation : TEXT
        settings : JSONB
        enable_rss : BOOLEAN
        enable_search : BOOLEAN
        priority : INT
    }

    entity "download_clients" {
        * id : UUID <<PK>>
        --
        name : TEXT
        implementation : TEXT
        settings : JSONB
        protocol : TEXT
        priority : INT
        enabled : BOOLEAN
    }
}

' ══════════════════════════════════════════════════════════════
' DOWNLOAD TRACKING
' ══════════════════════════════════════════════════════════════

package "Download Tracking" #E8F5E9 {
    entity "wanted_albums" {
        * id : UUID <<PK>>
        --
        album_id : UUID <<FK>> <<UNIQUE>>
        --
        priority : INT
        search_count : INT
        last_searched_at : TIMESTAMPTZ
        added_at : TIMESTAMPTZ
    }

    entity "download_queue" {
        * id : UUID <<PK>>
        --
        artist_id : UUID <<FK>>
        album_id : UUID <<FK>>
        --
        download_id : TEXT
        title : TEXT
        size : BIGINT
        size_left : BIGINT
        --
        status : TEXT
        progress : REAL
        error_message : TEXT
        --
        protocol : TEXT
        indexer : TEXT
        download_client : TEXT
        torrent_hash : TEXT
        output_path : TEXT
        --
        added_at : TIMESTAMPTZ
        completed_at : TIMESTAMPTZ
    }

    entity "blocklist" {
        * id : UUID <<PK>>
        --
        artist_id : UUID <<FK>>
        album_id : UUID <<FK>>
        --
        source_title : TEXT
        quality : JSONB
        size : BIGINT
        protocol : TEXT
        indexer : TEXT
        message : TEXT
        torrent_hash : TEXT
        --
        date : TIMESTAMPTZ
    }
}

' ══════════════════════════════════════════════════════════════
' RELATIONSHIPS
' ══════════════════════════════════════════════════════════════

' Core music relationships
artist_metadata ||--|| artists : "has config"
artist_metadata ||--o{ albums : "released"
albums ||--o{ album_releases : "has releases"
album_releases ||--o{ tracks : "contains"
tracks }o--o| track_files : "stored in"
track_files }o--|| albums : "belongs to"

' Artist config relationships
artists }o--|| quality_profiles : "uses"
artists }o--o| metadata_profiles : "uses"
artists }o--o| root_folders : "stored in"

' Root folder defaults
root_folders }o--o| quality_profiles : "default"
root_folders }o--o| metadata_profiles : "default"

' Download tracking relationships
wanted_albums ||--|| albums : "targets"
download_queue }o--o| artists : "for"
download_queue }o--o| albums : "for"
blocklist }o--|| artists : "for"
blocklist }o--o| albums : "for"

@enduml