feat(backend): model albums in the domain

Album is abstract with UserAlbum as its first table-per-type child, the same
split Track already uses, so the YouTube albums can join later without moving
anything. Tracks are linked through AlbumHasTrack rather than a column on the
track itself: an external track is shared between users and the same song
shows up in more than one album.

backend/Musify.Application/Contracts/IDatabase.cs

@@ -9,6 +9,12 @@ namespace Musify.Application.Contracts
 
         DbSet<PlayList> PlayLists { get; }
 
+        DbSet<Album> Albums { get; }
+
+        DbSet<UserAlbum> UserAlbums { get; }
+
+        DbSet<AlbumHasTrack> AlbumHasTracks { get; }
+
         DbSet<Track> Tracks { get; }
 
         DbSet<LocalTrack> LocalTracks { get; }

backend/Musify.Domain/Entities/Album.cs

@@ -0,0 +1,39 @@
+using System.ComponentModel.DataAnnotations;
+using Musify.Domain.Abstractions;
+using Musify.Domain.ValueObjects;
+
+namespace Musify.Domain.Entities
+{
+#pragma warning disable CS8618
+    public abstract class Album : IAuditable
+    {
+        [Key]
+        public Guid Id { get; set; } = Guid.NewGuid();
+
+        [Required]
+        [MaxLength(200)]
+        public required string Title { get; set; }
+
+        [Required]
+        [MaxLength(200)]
+        public required string NormalizedTitle { get; set; }
+
+        [MaxLength(256)]
+        public string? Description { get; set; }
+
+        public int? ReleaseYear { get; set; }
+
+        public AlbumPictures? Pictures { get; set; }
+
+        [Required]
+        public LifeCycleStatus LifeCycleStatus { get; set; } = LifeCycleStatus.Active;
+
+        [Required]
+        public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
+
+        [Required]
+        public DateTime UpdatedAt { get; set; } = DateTime.UtcNow;
+
+        public ICollection<AlbumHasTrack> AlbumTracks { get; set; } = new List<AlbumHasTrack>();
+    }
+}

backend/Musify.Domain/Entities/AlbumHasTrack.cs

@@ -0,0 +1,30 @@
+using System.ComponentModel.DataAnnotations;
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Musify.Domain.Entities
+{
+#pragma warning disable CS8618
+    [Table("AlbumHasTrack")]
+    public class AlbumHasTrack
+    {
+        public Guid Id { get; set; } = Guid.NewGuid();
+
+        [Required]
+        public required Guid AlbumId { get; set; }
+
+        [Required]
+        public required Guid TrackId { get; set; }
+
+        [Required]
+        public int TrackNumber { get; set; } = 1;
+
+        [Required]
+        public DateTime AddedAt { get; set; } = DateTime.UtcNow;
+
+        [ForeignKey(nameof(AlbumId))]
+        public Album Album { get; set; }
+
+        [ForeignKey(nameof(TrackId))]
+        public Track Track { get; set; }
+    }
+}

backend/Musify.Domain/Entities/Track.cs

@@ -38,6 +38,8 @@ namespace Musify.Domain.Entities
 
         public ICollection<PlayListHasTrack> PlayListTracks { get; set; } = new List<PlayListHasTrack>();
 
+        public ICollection<AlbumHasTrack> AlbumTracks { get; set; } = new List<AlbumHasTrack>();
+
         public ICollection<ListeningHistory> ListeningHistories { get; set; } = new List<ListeningHistory>();
     }
 }

backend/Musify.Domain/Entities/UserAlbum.cs

@@ -0,0 +1,15 @@
+using System.ComponentModel.DataAnnotations;
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Musify.Domain.Entities
+{
+#pragma warning disable CS8618
+    public class UserAlbum : Album
+    {
+        [Required]
+        public required long OwnerUserId { get; set; }
+
+        [ForeignKey(nameof(OwnerUserId))]
+        public User Owner { get; set; }
+    }
+}

backend/Musify.Domain/ValueObjects/AlbumPictures.cs

@@ -0,0 +1,13 @@
+namespace Musify.Domain.ValueObjects
+{
+    public class AlbumPictures
+    {
+        public string? OriginalName { get; set; }
+
+        public string? SmallName { get; set; }
+
+        public string? MediumName { get; set; }
+
+        public string? LargeName { get; set; }
+    }
+}

backend/Musify.Infrastructure/Persistence/Database.cs

@@ -98,6 +98,41 @@ namespace Musify.Infrastructure.Persistence
                 });
             modelBuilder.Entity<PlayList>().Navigation(playList => playList.Pictures).IsRequired(false);
 
+            modelBuilder.Entity<Album>()
+                .OwnsOne(album => album.Pictures, pictures =>
+                {
+                    pictures.Property(p => p.OriginalName).HasColumnName("OriginalPictureName").HasMaxLength(64);
+                    pictures.Property(p => p.SmallName).HasColumnName("SmallPictureName").HasMaxLength(64);
+                    pictures.Property(p => p.MediumName).HasColumnName("MediumPictureName").HasMaxLength(64);
+                    pictures.Property(p => p.LargeName).HasColumnName("LargePictureName").HasMaxLength(64);
+                });
+            modelBuilder.Entity<Album>().Navigation(album => album.Pictures).IsRequired(false);
+
+            modelBuilder.Entity<UserAlbum>()
+                .ToTable("UserAlbums");
+
+            modelBuilder.Entity<UserAlbum>()
+                .HasOne(album => album.Owner)
+                .WithMany()
+                .HasForeignKey(album => album.OwnerUserId)
+                .OnDelete(DeleteBehavior.Restrict);
+
+            modelBuilder.Entity<AlbumHasTrack>()
+                .HasOne(albumTrack => albumTrack.Album)
+                .WithMany(album => album.AlbumTracks)
+                .HasForeignKey(albumTrack => albumTrack.AlbumId)
+                .OnDelete(DeleteBehavior.Cascade);
+
+            modelBuilder.Entity<AlbumHasTrack>()
+                .HasOne(albumTrack => albumTrack.Track)
+                .WithMany(track => track.AlbumTracks)
+                .HasForeignKey(albumTrack => albumTrack.TrackId)
+                .OnDelete(DeleteBehavior.Cascade);
+
+            modelBuilder.Entity<AlbumHasTrack>()
+                .HasIndex(albumTrack => new { albumTrack.AlbumId, albumTrack.TrackId })
+                .IsUnique();
+
             var playListProcessing = modelBuilder.Entity<PlayListProcessingState>();
             playListProcessing.HasKey(state => state.CorrelationId);
             playListProcessing.Property(state => state.CorrelationId).ValueGeneratedNever();
@@ -118,6 +153,12 @@ namespace Musify.Infrastructure.Persistence
 
         public DbSet<PlayList> PlayLists => Set<PlayList>();
 
+        public DbSet<Album> Albums => Set<Album>();
+
+        public DbSet<UserAlbum> UserAlbums => Set<UserAlbum>();
+
+        public DbSet<AlbumHasTrack> AlbumHasTracks => Set<AlbumHasTrack>();
+
         public DbSet<UserHasTrack> UserHasTracks => Set<UserHasTrack>();
 
         public DbSet<PlayListHasTrack> PlayListHasTracks => Set<PlayListHasTrack>();

backend/Musify.Infrastructure/Persistence/Migrations/20260720180747_AddAlbums.cs

@@ -0,0 +1,117 @@
+using System;
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace Musify.Infrastructure.Persistence.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddAlbums : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.CreateTable(
+                name: "Albums",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "uuid", nullable: false),
+                    Title = table.Column<string>(type: "character varying(200)", maxLength: 200, nullable: false),
+                    NormalizedTitle = table.Column<string>(type: "character varying(200)", maxLength: 200, nullable: false),
+                    Description = table.Column<string>(type: "character varying(256)", maxLength: 256, nullable: true),
+                    ReleaseYear = table.Column<int>(type: "integer", nullable: true),
+                    OriginalPictureName = table.Column<string>(type: "character varying(64)", maxLength: 64, nullable: true),
+                    SmallPictureName = table.Column<string>(type: "character varying(64)", maxLength: 64, nullable: true),
+                    MediumPictureName = table.Column<string>(type: "character varying(64)", maxLength: 64, nullable: true),
+                    LargePictureName = table.Column<string>(type: "character varying(64)", maxLength: 64, nullable: true),
+                    LifeCycleStatus = table.Column<int>(type: "integer", nullable: false),
+                    CreatedAt = table.Column<DateTime>(type: "timestamp with time zone", nullable: false),
+                    UpdatedAt = table.Column<DateTime>(type: "timestamp with time zone", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_Albums", x => x.Id);
+                });
+
+            migrationBuilder.CreateTable(
+                name: "AlbumHasTrack",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "uuid", nullable: false),
+                    AlbumId = table.Column<Guid>(type: "uuid", nullable: false),
+                    TrackId = table.Column<Guid>(type: "uuid", nullable: false),
+                    TrackNumber = table.Column<int>(type: "integer", nullable: false),
+                    AddedAt = table.Column<DateTime>(type: "timestamp with time zone", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_AlbumHasTrack", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_AlbumHasTrack_Albums_AlbumId",
+                        column: x => x.AlbumId,
+                        principalTable: "Albums",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                    table.ForeignKey(
+                        name: "FK_AlbumHasTrack_Tracks_TrackId",
+                        column: x => x.TrackId,
+                        principalTable: "Tracks",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                });
+
+            migrationBuilder.CreateTable(
+                name: "UserAlbums",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "uuid", nullable: false),
+                    OwnerUserId = table.Column<long>(type: "bigint", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_UserAlbums", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_UserAlbums_Albums_Id",
+                        column: x => x.Id,
+                        principalTable: "Albums",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                    table.ForeignKey(
+                        name: "FK_UserAlbums_User_OwnerUserId",
+                        column: x => x.OwnerUserId,
+                        principalTable: "User",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                });
+
+            migrationBuilder.CreateIndex(
+                name: "IX_AlbumHasTrack_AlbumId_TrackId",
+                table: "AlbumHasTrack",
+                columns: new[] { "AlbumId", "TrackId" },
+                unique: true);
+
+            migrationBuilder.CreateIndex(
+                name: "IX_AlbumHasTrack_TrackId",
+                table: "AlbumHasTrack",
+                column: "TrackId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_UserAlbums_OwnerUserId",
+                table: "UserAlbums",
+                column: "OwnerUserId");
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropTable(
+                name: "AlbumHasTrack");
+
+            migrationBuilder.DropTable(
+                name: "UserAlbums");
+
+            migrationBuilder.DropTable(
+                name: "Albums");
+        }
+    }
+}

backend/Musify.Infrastructure/Persistence/Migrations/DatabaseModelSnapshot.cs

@@ -190,6 +190,73 @@ namespace Musify.Infrastructure.Persistence.Migrations
                     b.ToTable("OutboxState");
                 });
 
+            modelBuilder.Entity("Musify.Domain.Entities.Album", b =>
+                {
+                    b.Property<Guid>("Id")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("uuid");
+
+                    b.Property<DateTime>("CreatedAt")
+                        .HasColumnType("timestamp with time zone");
+
+                    b.Property<string>("Description")
+                        .HasMaxLength(256)
+                        .HasColumnType("character varying(256)");
+
+                    b.Property<int>("LifeCycleStatus")
+                        .HasColumnType("integer");
+
+                    b.Property<string>("NormalizedTitle")
+                        .IsRequired()
+                        .HasMaxLength(200)
+                        .HasColumnType("character varying(200)");
+
+                    b.Property<int?>("ReleaseYear")
+                        .HasColumnType("integer");
+
+                    b.Property<string>("Title")
+                        .IsRequired()
+                        .HasMaxLength(200)
+                        .HasColumnType("character varying(200)");
+
+                    b.Property<DateTime>("UpdatedAt")
+                        .HasColumnType("timestamp with time zone");
+
+                    b.HasKey("Id");
+
+                    b.ToTable("Albums");
+
+                    b.UseTptMappingStrategy();
+                });
+
+            modelBuilder.Entity("Musify.Domain.Entities.AlbumHasTrack", b =>
+                {
+                    b.Property<Guid>("Id")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("uuid");
+
+                    b.Property<DateTime>("AddedAt")
+                        .HasColumnType("timestamp with time zone");
+
+                    b.Property<Guid>("AlbumId")
+                        .HasColumnType("uuid");
+
+                    b.Property<Guid>("TrackId")
+                        .HasColumnType("uuid");
+
+                    b.Property<int>("TrackNumber")
+                        .HasColumnType("integer");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("TrackId");
+
+                    b.HasIndex("AlbumId", "TrackId")
+                        .IsUnique();
+
+                    b.ToTable("AlbumHasTrack");
+                });
+
             modelBuilder.Entity("Musify.Domain.Entities.Artist", b =>
                 {
                     b.Property<Guid>("Id")
@@ -571,6 +638,18 @@ namespace Musify.Infrastructure.Persistence.Migrations
                     b.ToTable("TrackProcessingState");
                 });
 
+            modelBuilder.Entity("Musify.Domain.Entities.UserAlbum", b =>
+                {
+                    b.HasBaseType("Musify.Domain.Entities.Album");
+
+                    b.Property<long>("OwnerUserId")
+                        .HasColumnType("bigint");
+
+                    b.HasIndex("OwnerUserId");
+
+                    b.ToTable("UserAlbums", (string)null);
+                });
+
             modelBuilder.Entity("Musify.Domain.Entities.ExternalTrack", b =>
                 {
                     b.HasBaseType("Musify.Domain.Entities.Track");
@@ -613,6 +692,63 @@ namespace Musify.Infrastructure.Persistence.Migrations
                         .HasPrincipalKey("MessageId", "ConsumerId");
                 });
 
+            modelBuilder.Entity("Musify.Domain.Entities.Album", b =>
+                {
+                    b.OwnsOne("Musify.Domain.ValueObjects.AlbumPictures", "Pictures", b1 =>
+                        {
+                            b1.Property<Guid>("AlbumId")
+                                .HasColumnType("uuid");
+
+                            b1.Property<string>("LargeName")
+                                .HasMaxLength(64)
+                                .HasColumnType("character varying(64)")
+                                .HasColumnName("LargePictureName");
+
+                            b1.Property<string>("MediumName")
+                                .HasMaxLength(64)
+                                .HasColumnType("character varying(64)")
+                                .HasColumnName("MediumPictureName");
+
+                            b1.Property<string>("OriginalName")
+                                .HasMaxLength(64)
+                                .HasColumnType("character varying(64)")
+                                .HasColumnName("OriginalPictureName");
+
+                            b1.Property<string>("SmallName")
+                                .HasMaxLength(64)
+                                .HasColumnType("character varying(64)")
+                                .HasColumnName("SmallPictureName");
+
+                            b1.HasKey("AlbumId");
+
+                            b1.ToTable("Albums");
+
+                            b1.WithOwner()
+                                .HasForeignKey("AlbumId");
+                        });
+
+                    b.Navigation("Pictures");
+                });
+
+            modelBuilder.Entity("Musify.Domain.Entities.AlbumHasTrack", b =>
+                {
+                    b.HasOne("Musify.Domain.Entities.Album", "Album")
+                        .WithMany("AlbumTracks")
+                        .HasForeignKey("AlbumId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.HasOne("Musify.Domain.Entities.Track", "Track")
+                        .WithMany("AlbumTracks")
+                        .HasForeignKey("TrackId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.Navigation("Album");
+
+                    b.Navigation("Track");
+                });
+
             modelBuilder.Entity("Musify.Domain.Entities.ListeningHistory", b =>
                 {
                     b.HasOne("Musify.Domain.Entities.Track", "Track")
@@ -831,6 +967,23 @@ namespace Musify.Infrastructure.Persistence.Migrations
                     b.Navigation("User");
                 });
 
+            modelBuilder.Entity("Musify.Domain.Entities.UserAlbum", b =>
+                {
+                    b.HasOne("Musify.Domain.Entities.Album", null)
+                        .WithOne()
+                        .HasForeignKey("Musify.Domain.Entities.UserAlbum", "Id")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.HasOne("Musify.Domain.Entities.User", "Owner")
+                        .WithMany()
+                        .HasForeignKey("OwnerUserId")
+                        .OnDelete(DeleteBehavior.Restrict)
+                        .IsRequired();
+
+                    b.Navigation("Owner");
+                });
+
             modelBuilder.Entity("Musify.Domain.Entities.ExternalTrack", b =>
                 {
                     b.HasOne("Musify.Domain.Entities.Track", null)
@@ -857,6 +1010,11 @@ namespace Musify.Infrastructure.Persistence.Migrations
                     b.Navigation("Owner");
                 });
 
+            modelBuilder.Entity("Musify.Domain.Entities.Album", b =>
+                {
+                    b.Navigation("AlbumTracks");
+                });
+
             modelBuilder.Entity("Musify.Domain.Entities.Artist", b =>
                 {
                     b.Navigation("TrackArtists");
@@ -869,6 +1027,8 @@ namespace Musify.Infrastructure.Persistence.Migrations
 
             modelBuilder.Entity("Musify.Domain.Entities.Track", b =>
                 {
+                    b.Navigation("AlbumTracks");
+
                     b.Navigation("ListeningHistories");
 
                     b.Navigation("PlayListTracks");