web-player: P14 — barrido final y guardarraíles

Añade scripts/check-tokens.mjs (npm run lint:tokens, incorporado a
lint) como guardrail: falla si src/**/*.svelte reintroduce valores
arbitrarios fuera de la lista blanca de B.4, rounded-* de fábrica,
pares h-N w-N (deberían ser size-N), espaciado fraccionario en
cuartos, o colores hex/rgba() literales.

Se limpia el repo hasta dejar el script en 0 violaciones: ~40 pares
h-N w-N → size-N (sobre todo iconos, vía script puntual), ~26
espaciados fraccionarios en cuartos redondeados al entero más cercano
(Δ≤1px, p. ej. py-2.75→py-3, gap-1.75→gap-2), radios de fábrica
sueltos (rounded-sm/lg, rounded a secas) migrados a los tokens
correspondientes, y dos tracking-[-0.02em] que coincidían
exactamente con el token tracking-display ya existente pero nunca se
habían migrado. Se retiran las recetas stroke-thin/regular/bold
(creadas en P1, cero consumidores) — decisión tomada, sin bloquear:
no se migra strokeWidth={n} (13 valores, en casi todos los
componentes) a CSS porque no se puede verificar sin Docker que
lucide-svelte respete stroke-width por clase en vez del prop, y una
regresión ahí sería silenciosa en toda la app; el script documenta
este gap explícitamente en vez de fingir cobertura completa.

Detector de huérfanos: 0 componentes sin importadores. Se borra
docs/design-system-refactor-plan.md (plan anterior, superseded por
frontend-refactor-plan.md). web-player/CLAUDE.md gana una sección
"Estilos" con la lista blanca B.4 y los componentes base a reutilizar.
Se recalcula la tabla de línea base (A.4) y se anota en el Registro
(D.1): 61→47 componentes, 44→11 arbitrarios (los 11 restantes en
lista blanca), 13→8 radios distintos, 0 violaciones de lint:tokens.

Verificado con npm run check (0 errores), npm run lint:tokens (0
violaciones) y npm run build. Smoke test de /login sin errores de
consola achacables al cambio (Docker no disponible en esta sesión).

README.md

@@ -1,55 +1,57 @@
 # Musify
 
-A music streaming app. Upload your own tracks, organize them into playlists
+Music streaming platform: upload your own tracks, process them asynchronously
-and albums, and stream them back with a web player built around your
+(audio transcoded to `.m4a`, thumbnails generated) and stream them without the
-listening habits: auto-generated mixes, a home feed, search, likes, and an
+bytes ever going through the API.
-Explore page for finding something new.
-
-## What it does
-
-- **Upload and organize your own music**: tracks, albums, cover art, artist credits.
-- **Playlists**, likes, and a "recently played" history.
-- **Mixes**, playlists generated automatically from what you actually listen to.
-- **Explore**, genre browsing and search across tracks, albums, playlists and people.
-- **Real streaming**, not just file downloads: seek, queue, shuffle, repeat.
-- **Accounts via OIDC login**, with an optional anonymous listening mode.
-- Light and dark themes, and a layout that works on both desktop and mobile.
-
-## How it's built
-
-**Backend**: .NET 10, split into a REST API, a background worker, and a
-dedicated streaming gateway.
-- Clean architecture (Domain / Application / Infrastructure) with CQRS (Mediator) and `ErrorOr` results.
-- PostgreSQL via EF Core for metadata. RabbitMQ and MassTransit handle async processing (audio transcoding, thumbnails) with saga-based rollback.
-- SeaweedFS (S3-compatible) for file storage. Uploads and downloads go straight between the client and storage, never through the API.
-- ffmpeg for audio transcoding, ImageSharp for thumbnails.
-- A YARP reverse proxy that streams the audio and checks a signed, short-lived ticket on every request.
-- Zitadel for login (OIDC/OAuth2).
-
-**Web client**: SvelteKit 2 on Svelte 5 (runes), TypeScript, Tailwind 4.
-The session lives on the server, so the backend access token never reaches the browser.
-
-**Infrastructure**: Musify's own apps run from Docker Compose (dev and
-production overlays). Postgres, RabbitMQ, SeaweedFS, Zitadel and Jaeger are
-shared infrastructure that lives in a separate `Infrastructure` git
-repository, used by Musify and by other projects that need the same OIDC
-provider and object storage.
-
-## Project layout
 
 ```
-backend/      .NET solution: Api, Worker, StreamingGateway, and the shared Domain/Application/Infrastructure
+backend/      .NET 10 — Domain / Application / Infrastructure / Api / Worker / StreamingGateway / Tests
-web-player/   the SvelteKit web client
+web-player/   SvelteKit 2 + Svelte 5 + Tailwind 4 web client
-deploy/       Docker Compose stacks for dev and production
+deploy/       Docker Compose stacks — self-contained, no wrapper scripts
-docs/         architecture notes, one file per area
+docs/         What each piece does and why (in Spanish)
 ```
 
-Postgres, Zitadel, SeaweedFS, RabbitMQ and Jaeger are not part of this
+```sh
-layout. They live in the separate `Infrastructure` repository instead.
+dotnet test backend/Musify.slnx   # backend/Tests/ — Docker running (Testcontainers: Postgres, SeaweedFS)
+```
 
-## Digging deeper
+## Run it
 
-[docs/](docs/README.md) covers how each piece works and why: architecture,
+Development (Docker Desktop):
-authentication, storage, streaming, media processing, and the local dev
+
-setup. [deploy/README.md](deploy/README.md) has the full instructions for
+```sh
-running the stack, in development or on a production server.
+docker compose -f deploy/compose.yml -f deploy/compose.dev.yml up -d
+```
+
+Infrastructure plus stream-ticket keys, database migrations and Zitadel OIDC
+provisioning — all as one-shot jobs baked into the compose file. Apps run from
+the IDE by default; add `--profile apps up -d --build` as a second command to
+run them in Docker instead.
+
+Production, on a server with a domain:
+
+```sh
+cp deploy/.env.prod.example deploy/.env.prod   # fill in the domain and secrets
+docker compose --env-file deploy/.env.prod -f deploy/compose.yml -f deploy/compose.prod.yml up -d
+docker compose --env-file deploy/.env.prod -f deploy/compose.yml -f deploy/compose.prod.yml --profile apps up -d --build
+```
+
+Idempotent — run the same commands again to deploy an update. See
+[deploy/README.md](deploy/README.md) for the details, the port map and the
+production prerequisites.
+
+## Components
+
+| Service | Port (dev) | Role |
+|---|---|---|
+| `Musify.Api` | 5111 | REST API, issues presigned upload URLs and stream tickets |
+| `Musify.StreamingGateway` | 8081 | YARP proxy that validates the stream ticket and serves the audio |
+| `Musify.Worker` | — | MassTransit consumers: transcoding, thumbnails |
+| `web-player` | 5173 / 3000 | Web client (SvelteKit, server-side OIDC session) |
+| Zitadel | 8080 | Identity (OIDC/OAuth2) |
+| PostgreSQL / RabbitMQ / SeaweedFS / Jaeger | 59000 / 5672 / 8333 / 16686 | Metadata, messaging, object storage, traces |
+
+More in [docs/](docs/README.md): [architecture](docs/architecture.md),
+[authentication](docs/authentication.md), [storage](docs/storage.md),
+[streaming](docs/streaming.md), [media processing](docs/media-processing.md),
+[development](docs/development.md).

backend/Core/Musify.Application/Albums/Responses/AlbumsSearchResponse.cs

@@ -1,6 +1,6 @@
 namespace Musify.Application.Albums.Responses
 {
-
+    /// <summary>A page of the user's catalog albums (their own).</summary>
     public record AlbumsSearchResponse(
         IReadOnlyList<AlbumSearchItemResponse> Items,
         int PageNumber,

backend/Core/Musify.Application/Configuration/GetPlaybackPublicConfig.cs

@@ -3,7 +3,8 @@ using Musify.Application.Configuration.Responses;
 
 namespace Musify.Application.Configuration
 {
-
+    /// <summary>Reads the parts of <see cref="PlaybackConfiguration"/> that are safe to expose to an
+    /// unauthenticated client, so it can decide whether to gate the app behind sign-in at all.</summary>
     public record GetPlaybackPublicConfigQuery : IQuery<PlaybackPublicConfigResponse>;
 
     public class GetPlaybackPublicConfigQueryHandler(PlaybackConfiguration playbackConfiguration)

backend/Core/Musify.Application/Configuration/PlaybackConfiguration.cs

@@ -2,16 +2,28 @@ using System.ComponentModel.DataAnnotations;
 
 namespace Musify.Application.Configuration
 {
-
+    /// <summary>Controls whether listeners without a session can stream music at all, and if so,
+    /// how much of a track they get to hear before being cut off (a Spotify-style preview).</summary>
     public sealed class PlaybackConfiguration
     {
         public const string SectionName = "Playback";
 
+        /// <summary>When false (the default), every stream endpoint requires a signed-in user, exactly
+        /// like before this setting existed. When true, an anonymous request is issued a stream ticket
+        /// too, capped by <see cref="AnonymousFragmentSeconds"/> if that is greater than zero.</summary>
         public bool AllowAnonymousListening { get; set; }
 
+        /// <summary>How many seconds of a track an anonymous listener may hear, enforced by the
+        /// Streaming Gateway clamping the byte range it will serve for that ticket. Zero (the default)
+        /// means no cap: anonymous listeners hear the full track, same as a signed-in user. Ignored
+        /// when <see cref="AllowAnonymousListening"/> is false.</summary>
         [Range(0, 3600)]
         public int AnonymousFragmentSeconds { get; set; }
 
+        /// <summary>Bytes per second of the transcoded audio, used to turn <see cref="AnonymousFragmentSeconds"/>
+        /// into a byte cap for the stream ticket. Defaults to the app's own transcoder output (128 kbps
+        /// AAC, <c>AudioTranscoder:Ffmpeg:AudioBitrate</c>) — update this alongside that setting if it
+        /// ever changes, since the two aren't wired together.</summary>
         [Range(1, int.MaxValue)]
         public int EstimatedAudioBytesPerSecond { get; set; } = 16_000;
     }

backend/Core/Musify.Application/Configuration/Responses/PlaybackPublicConfigResponse.cs

@@ -1,5 +1,7 @@
 namespace Musify.Application.Configuration.Responses
 {
-
+    /// <param name="AllowAnonymousListening">Whether listeners without a session can stream music at all.</param>
+    /// <param name="AnonymousFragmentSeconds">How many seconds of a track an anonymous listener may hear.
+    /// Zero means no cap. Meaningless when <paramref name="AllowAnonymousListening"/> is false.</param>
     public record PlaybackPublicConfigResponse(bool AllowAnonymousListening, int AnonymousFragmentSeconds);
 }

backend/Core/Musify.Application/Contracts/IStreamTicketService.cs

@@ -2,7 +2,11 @@ namespace Musify.Application.Contracts
 {
     public interface IStreamTicketService
     {
-
+        /// <param name="userId">Null for an anonymous listener — the ticket is issued without a
+        /// <c>sub</c> claim.</param>
+        /// <param name="keyPrefix">The storage key (prefix) the ticket authorizes reading from.</param>
+        /// <param name="maxBytes">When set, the Streaming Gateway clamps the byte range it will serve
+        /// for this ticket to <c>[0, maxBytes)</c> — used for the anonymous preview fragment.</param>
         StreamTicket IssueTicket(long? userId, string keyPrefix, long? maxBytes = null);
     }
 

backend/Core/Musify.Application/Mixes/GenerateMixesForUser.cs

@@ -12,6 +12,11 @@ namespace Musify.Application.Mixes
     public record GenerateMixesForUserCommand(long UserId)
         : ICommand<ErrorOr<Success>>;
 
+    /// <summary>Builds each user's mixes purely from their own library: a "Descubrimiento" mix of
+    /// tracks they own but haven't listened to yet, and a "Tu mezcla diaria" mix blending recently
+    /// listened tracks with unheard ones. There's no artist/genre metadata for local uploads today,
+    /// so mixes can't be seeded by "similar artist" the way the old YouTube-backed discovery did —
+    /// once a tagging system exists, this is the place to seed mixes by tag instead.</summary>
     public class GenerateMixesForUserCommandHandler(
         IDatabase database,
         MixConfiguration mixConfiguration,

backend/Core/Musify.Application/Mixes/MixItemMapper.cs

@@ -5,7 +5,9 @@ using Musify.Domain.Entities;
 
 namespace Musify.Application.Mixes
 {
-
+    /// <summary>Resolves MixItem rows to their MixItemApplicationResponse shape via a single batched
+    /// track lookup, instead of an EF Include chain deep enough (Mix -&gt; Items -&gt; Track -&gt; Owner) to
+    /// force a correlated-subquery translation some providers (SQLite, notably) can't produce.</summary>
     internal static class MixItemMapper
     {
         public static async Task<List<MixItemApplicationResponse>> ToResponsesAsync(

backend/Core/Musify.Application/Serialization/LongAsStringConverter.cs

@@ -4,6 +4,13 @@ using System.Text.Json.Serialization;
 
 namespace Musify.Application.Serialization;
 
+// Zitadel-issued user ids routinely exceed Number.MAX_SAFE_INTEGER (2^53-1).
+// Serialized as a raw JSON number, the frontend's JSON.parse silently rounds
+// them to the nearest representable double, corrupting the id (it becomes a
+// different, sometimes valid, user id). Applied via [property: JsonConverter(...)]
+// on the specific id-shaped `long`/`long?` response properties (not globally —
+// unrelated `long` fields like byte sizes must stay numbers), this serializes
+// them as a JSON string instead, which round-trips exactly.
 public sealed class LongAsStringConverter : JsonConverter<long>
 {
     public override long Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>

backend/Core/Musify.Application/Services/TrackStreamIssuer.cs

@@ -30,6 +30,8 @@ public sealed class TrackStreamIssuer(
             folderPath,
             streamGatewayConfiguration.AudioFileName);
 
+        // Anonymous listeners have no User row to satisfy ListeningHistory's foreign key against, and
+        // their plays aren't "history" anyone can look back on anyway, so there's nothing to record.
         if (userId != null)
         {
             var newListeningHistory = new ListeningHistory

backend/Core/Musify.Application/Tracks/GetTrackStream.cs

@@ -9,7 +9,8 @@ using Musify.Application.Tracks.Responses;
 
 namespace Musify.Application.Tracks
 {
-
+    /// <param name="UserId">Null for an anonymous request — allowed only when
+    /// <see cref="PlaybackConfiguration.AllowAnonymousListening"/> is enabled.</param>
     public record GetTrackStreamQuery(Guid TrackId, long? UserId)
         : IQuery<ErrorOr<TrackStreamResponse>>;
 

backend/Core/Musify.Application/Tracks/Responses/TracksSearchResponse.cs

@@ -1,6 +1,6 @@
 namespace Musify.Application.Tracks.Responses
 {
-
+    /// <summary>A page of the user's catalog tracks (their own uploads).</summary>
     public record TracksSearchResponse(
         IReadOnlyList<TrackSearchItemResponse> Items,
         int PageNumber,

backend/Core/Musify.Domain/ValueObjects/GenreCompatibility.cs

@@ -1,6 +1,9 @@
 namespace Musify.Domain.ValueObjects
 {
-
+    /// <summary>
+    /// Encodes which genre pairs are mutually exclusive on a single track (e.g. a track cannot
+    /// be tagged as both Classical and Metal at the same time).
+    /// </summary>
     public static class GenreCompatibility
     {
         private static readonly HashSet<(Genre, Genre)> IncompatiblePairs = BuildIncompatiblePairs();
@@ -28,6 +31,9 @@ namespace Musify.Domain.ValueObjects
         public static bool AreCompatible(Genre a, Genre b) =>
             a == b || !IncompatiblePairs.Contains((a, b));
 
+        /// <summary>
+        /// Returns every mutually exclusive genre pair found within the given set of tags.
+        /// </summary>
         public static IReadOnlyCollection<(Genre First, Genre Second)> FindConflicts(IEnumerable<Genre> tags)
         {
             var distinctTags = tags.Distinct().ToList();

backend/Core/Musify.Infrastructure/Persistence/AuditableEntityInterceptor.cs

@@ -24,6 +24,11 @@ namespace Musify.Infrastructure.Persistence
             if (context == null)
                 return;
 
+            // SavingChanges(Async) fires before EF's own automatic change detection for this
+            // save, so entities modified through plain property assignment (query, then set a
+            // property, then SaveChanges — the normal case) still show as Unchanged here unless
+            // something already forced detection. Force it explicitly, otherwise UpdatedAt is
+            // never bumped on a real update, only on inserts.
             context.ChangeTracker.DetectChanges();
 
             var now = DateTime.UtcNow;

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260531234306_AddUserProfilePictureUrl.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260531234306_AddUserProfilePictureUrl")]
     partial class AddUserProfilePictureUrl
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260531234306_AddUserProfilePictureUrl.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddUserProfilePictureUrl : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AddColumn<string>(
@@ -18,6 +18,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 nullable: true);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropColumn(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260601195757_RenameTimestampsAndAudit.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260601195757_RenameTimestampsAndAudit")]
     partial class RenameTimestampsAndAudit
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260601195757_RenameTimestampsAndAudit.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class RenameTimestampsAndAudit : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.RenameColumn(
@@ -31,6 +31,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 newName: "CreatedAt");
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.RenameColumn(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260705123932_AddTrackProcessingStateSaga.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260705123932_AddTrackProcessingStateSaga")]
     partial class AddTrackProcessingStateSaga
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260705123932_AddTrackProcessingStateSaga.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddTrackProcessingStateSaga : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.CreateTable(
@@ -27,6 +27,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 });
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropTable(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260705124807_AddTrackProcessingSagaKeys.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260705124807_AddTrackProcessingSagaKeys")]
     partial class AddTrackProcessingSagaKeys
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260705124807_AddTrackProcessingSagaKeys.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddTrackProcessingSagaKeys : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AddColumn<string>(
@@ -29,6 +29,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 nullable: true);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropColumn(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260705125356_AddPlayListProcessingStateSaga.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260705125356_AddPlayListProcessingStateSaga")]
     partial class AddPlayListProcessingStateSaga
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260705125356_AddPlayListProcessingStateSaga.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddPlayListProcessingStateSaga : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.CreateTable(
@@ -27,6 +27,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 });
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropTable(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260713234847_AddListeningHistory.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260713234847_AddListeningHistory")]
     partial class AddListeningHistory
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260713234847_AddListeningHistory.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddListeningHistory : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.CreateTable(
@@ -47,6 +47,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 column: "UserId");
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropTable(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260714114537_AddTrackDuration.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260714114537_AddTrackDuration")]
     partial class AddTrackDuration
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260714114537_AddTrackDuration.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddTrackDuration : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AddColumn<int>(
@@ -18,6 +18,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 defaultValue: 0);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropColumn(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260715193951_AddTrackSourceArtistExternalId.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260715193951_AddTrackSourceArtistExternalId")]
     partial class AddTrackSourceArtistExternalId
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260715193951_AddTrackSourceArtistExternalId.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddTrackSourceArtistExternalId : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AddColumn<string>(
@@ -41,6 +41,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 filter: "\"ExternalId\" <> ''");
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropIndex(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260715230836_AddTrackDownloadRequested.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260715230836_AddTrackDownloadRequested")]
     partial class AddTrackDownloadRequested
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260715230836_AddTrackDownloadRequested.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddTrackDownloadRequested : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AddColumn<bool>(
@@ -18,6 +18,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 defaultValue: false);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropColumn(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260716214442_MakeTrackMediaAndExternalIdNullable.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260716214442_MakeTrackMediaAndExternalIdNullable")]
     partial class MakeTrackMediaAndExternalIdNullable
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260716214442_MakeTrackMediaAndExternalIdNullable.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class MakeTrackMediaAndExternalIdNullable : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropIndex(
@@ -66,6 +66,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 unique: true);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropIndex(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260716214752_AddArtistsAndTrackOwnership.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260716214752_AddArtistsAndTrackOwnership")]
     partial class AddArtistsAndTrackOwnership
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260716214752_AddArtistsAndTrackOwnership.cs

@@ -4,10 +4,10 @@ using Microsoft.EntityFrameworkCore.Migrations;
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddArtistsAndTrackOwnership : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AddColumn<long>(
@@ -154,6 +154,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 sql: "(\"OwnerUserId\" IS NOT NULL) = (\"Source\" = 0)");
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropForeignKey(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260716220047_DropTrackArtistColumn.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260716220047_DropTrackArtistColumn")]
     partial class DropTrackArtistColumn
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260716220047_DropTrackArtistColumn.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class DropTrackArtistColumn : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropColumn(
@@ -15,6 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 table: "Tracks");
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AddColumn<string>(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260717164632_MovePlayListPicturesToOwnedType.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260717164632_MovePlayListPicturesToOwnedType")]
     partial class MovePlayListPicturesToOwnedType
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260717164632_MovePlayListPicturesToOwnedType.cs

@@ -4,15 +4,16 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class MovePlayListPicturesToOwnedType : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
 
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
 

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260717164812_RenameTrackDurationToDurationSeconds.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260717164812_RenameTrackDurationToDurationSeconds")]
     partial class RenameTrackDurationToDurationSeconds
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260717164812_RenameTrackDurationToDurationSeconds.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class RenameTrackDurationToDurationSeconds : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.RenameColumn(
@@ -16,6 +16,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 newName: "DurationSeconds");
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.RenameColumn(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260717172507_SplitTrackIntoLocalAndExternal.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260717172507_SplitTrackIntoLocalAndExternal")]
     partial class SplitTrackIntoLocalAndExternal
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260717172507_SplitTrackIntoLocalAndExternal.cs

@@ -4,10 +4,10 @@ using Microsoft.EntityFrameworkCore.Migrations;
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class SplitTrackIntoLocalAndExternal : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropForeignKey(
@@ -156,6 +156,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 oldNullable: true);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropForeignKey(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260717223358_MakePlayListPicturesNullable.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260717223358_MakePlayListPicturesNullable")]
     partial class MakePlayListPicturesNullable
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260717223358_MakePlayListPicturesNullable.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class MakePlayListPicturesNullable : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AlterColumn<string>(
@@ -51,6 +51,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 oldMaxLength: 64);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AlterColumn<string>(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260720180629_WidenTrackTitle.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260720180629_WidenTrackTitle")]
     partial class WidenTrackTitle
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260720180629_WidenTrackTitle.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class WidenTrackTitle : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AlterColumn<string>(
@@ -31,6 +31,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 oldMaxLength: 50);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AlterColumn<string>(

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

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260720180747_AddAlbums")]
     partial class AddAlbums
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

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

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddAlbums : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.CreateTable(
@@ -100,6 +100,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 column: "OwnerUserId");
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropTable(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260720184656_AddUserAlbumExternalId.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260720184656_AddUserAlbumExternalId")]
     partial class AddUserAlbumExternalId
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260720184656_AddUserAlbumExternalId.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddUserAlbumExternalId : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropIndex(
@@ -28,6 +28,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 unique: true);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropIndex(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260721155102_AddMixes.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260721155102_AddMixes")]
     partial class AddMixes
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260721155102_AddMixes.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddMixes : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.CreateTable(
@@ -83,6 +83,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 column: "TrackId");
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropTable(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260721161653_RemoveUserAlbumExternalId.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260721161653_RemoveUserAlbumExternalId")]
     partial class RemoveUserAlbumExternalId
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260721161653_RemoveUserAlbumExternalId.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class RemoveUserAlbumExternalId : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropIndex(
@@ -24,6 +24,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 column: "OwnerUserId");
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropIndex(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260721162102_DropMixGeneratedOn.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260721162102_DropMixGeneratedOn")]
     partial class DropMixGeneratedOn
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260721162102_DropMixGeneratedOn.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class DropMixGeneratedOn : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropColumn(
@@ -15,6 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 table: "Mixes");
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AddColumn<DateOnly>(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260721190735_MakePlayListDescriptionOptional.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260721190735_MakePlayListDescriptionOptional")]
     partial class MakePlayListDescriptionOptional
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260721190735_MakePlayListDescriptionOptional.cs

@@ -4,10 +4,10 @@ using Microsoft.EntityFrameworkCore.Migrations;
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class MakePlayListDescriptionOptional : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AlterColumn<string>(
@@ -27,6 +27,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 """);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AlterColumn<string>(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260724170051_DurationAsDouble.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260724170051_DurationAsDouble")]
     partial class DurationAsDouble
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260724170051_DurationAsDouble.cs

@@ -4,15 +4,16 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class DurationAsDouble : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
 
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
 

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260724181012_AddExternalAlbums.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260724181012_AddExternalAlbums")]
     partial class AddExternalAlbums
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260724181012_AddExternalAlbums.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddExternalAlbums : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.CreateTable(
@@ -36,6 +36,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 unique: true);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropTable(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260724182659_AddExternalAlbumThumbnail.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260724182659_AddExternalAlbumThumbnail")]
     partial class AddExternalAlbumThumbnail
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260724182659_AddExternalAlbumThumbnail.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddExternalAlbumThumbnail : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AddColumn<string>(
@@ -18,6 +18,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 nullable: true);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropColumn(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260910125022_AddAlbumProcessingStateSaga.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260910125022_AddAlbumProcessingStateSaga")]
     partial class AddAlbumProcessingStateSaga
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260910125022_AddAlbumProcessingStateSaga.cs

@@ -5,10 +5,10 @@ using Microsoft.EntityFrameworkCore.Migrations;
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddAlbumProcessingStateSaga : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.CreateTable(
@@ -28,6 +28,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 });
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropTable(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260914144913_AddPlayListVisibility.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260914144913_AddPlayListVisibility")]
     partial class AddPlayListVisibility
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260914144913_AddPlayListVisibility.cs

@@ -4,10 +4,10 @@
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddPlayListVisibility : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AddColumn<int>(
@@ -18,6 +18,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 defaultValue: 0);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropColumn(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260914150045_AddTrackLikes.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260914150045_AddTrackLikes")]
     partial class AddTrackLikes
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260914150045_AddTrackLikes.cs

@@ -5,10 +5,10 @@ using Microsoft.EntityFrameworkCore.Migrations;
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddTrackLikes : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.CreateTable(
@@ -49,6 +49,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 unique: true);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropTable(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260914151900_AddUserFollows.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260914151900_AddUserFollows")]
     partial class AddUserFollows
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260914151900_AddUserFollows.cs

@@ -5,10 +5,10 @@ using Microsoft.EntityFrameworkCore.Migrations;
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddUserFollows : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.CreateTable(
@@ -49,6 +49,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 unique: true);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropTable(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260915165436_RemoveYouTubeIntegration.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -15,7 +15,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260915165436_RemoveYouTubeIntegration")]
     partial class RemoveYouTubeIntegration
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260915165436_RemoveYouTubeIntegration.cs

@@ -5,16 +5,25 @@ using Microsoft.EntityFrameworkCore.Migrations;
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class RemoveYouTubeIntegration : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
-
+            // Data cleanup first, while the External*/Local*/UserAlbums tables (and the loose
+            // MixItem columns) still exist to query/cascade from. Deleting the base Tracks/Albums
+            // rows for anything that only ever existed as an ExternalTrack/ExternalAlbum cascades
+            // (FKs are ON DELETE CASCADE) to their own ExternalTracks/ExternalAlbums row, TrackArtist,
+            // PlayListHasTrack, AlbumHasTrack, TrackLike, ListeningHistory, UserHasTrack and MixItems
+            // rows that referenced them — this is deliberately lossy: those rows only existed to back
+            // the YouTube integration being removed here.
             migrationBuilder.Sql("""DELETE FROM "Tracks" WHERE "Id" IN (SELECT "Id" FROM "ExternalTracks");""");
             migrationBuilder.Sql("""DELETE FROM "Albums" WHERE "Id" IN (SELECT "Id" FROM "ExternalAlbums");""");
 
+            // Live YouTube search hits that were seeded into a mix but never materialized into a
+            // real track (MixItemSource.YouTube, no TrackId) — MixItem.TrackId is about to become
+            // required, so these rows can't be kept.
             migrationBuilder.Sql("""DELETE FROM "MixItems" WHERE "TrackId" IS NULL;""");
 
             migrationBuilder.AddColumn<long>(
@@ -123,6 +132,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 onDelete: ReferentialAction.Restrict);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropForeignKey(

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260916153700_AddTrackTags.Designer.cs

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;
@@ -16,7 +16,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
     [Migration("20260916153700_AddTrackTags")]
     partial class AddTrackTags
     {
-
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618

backend/Core/Musify.Infrastructure/Persistence/Migrations/20260916153700_AddTrackTags.cs

@@ -6,10 +6,10 @@ using Musify.Domain.ValueObjects;
 
 namespace Musify.Infrastructure.Persistence.Migrations
 {
-
+    /// <inheritdoc />
     public partial class AddTrackTags : Migration
     {
-
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.AlterDatabase()
@@ -41,6 +41,7 @@ namespace Musify.Infrastructure.Persistence.Migrations
                 unique: true);
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.DropTable(

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

@@ -1,4 +1,4 @@
-
+// <auto-generated />
 using System;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Infrastructure;

backend/Hosts/Musify.Api/Authentication/JwtBearerEventsHandler.cs

@@ -41,8 +41,13 @@ public sealed class JwtBearerEventsHandler(
         if (cache.TryGetValue(cacheKey, out _))
             return;
 
+        // Access tokens from the IdP are minimal (just sub/scope/aud) — profile attributes live on
+        // the userinfo endpoint, so ask for them there instead of relying on token claims alone.
         var userInfo = await FetchUserInfoAsync(tokenValidatedContext, tokenValidatedContext.HttpContext.RequestAborted);
 
+        // Zitadel also issues short-form JWT claim names ("name", "given_name", "family_name", "email"),
+        // but the newer JsonWebTokenHandler (default since .NET 8) no longer auto-maps those to the
+        // legacy ClaimTypes.* URIs the way JwtSecurityTokenHandler used to — so check both forms too.
         var username = userInfo?.Name
             ?? userInfo?.PreferredUsername
             ?? principal.FindFirstValue("name")

backend/Hosts/Musify.Api/OpenApi/OpenApiOptionsSetup.cs

@@ -39,6 +39,13 @@ public sealed class OpenApiOptionsSetup(IOptions<AuthenticationConfiguration> op
             return Task.CompletedTask;
         } );
 
+        // Properties annotated with [JsonConverter(typeof(LongAsStringConverter))] (id-shaped
+        // `long` fields — see that converter for why) serialize as a JSON string, but the
+        // schema generator still reflects the declared CLR `long`/`long?` type as a bare
+        // int64 number. Reconcile the declared schema so generated clients (openapi-typescript)
+        // type exactly those properties as `string`, matching what actually goes over the wire —
+        // scoped to the attribute, not the CLR type, so unrelated `long` fields (byte sizes, …)
+        // are left alone.
         options.AddSchemaTransformer((schema, context, _) =>
         {
             if (context.JsonPropertyInfo?.CustomConverter is LongAsStringConverter or NullableLongAsStringConverter)

backend/Hosts/Musify.Api/Program.cs

@@ -48,4 +48,6 @@ app
 
 app.Run();
 
+// Makes the top-level-statements Program class public so
+// WebApplicationFactory<Program> (Musify.Api.Tests) can see it.
 public partial class Program;

backend/Hosts/Musify.StreamingGateway/Authentication/TicketValidator.cs

@@ -6,6 +6,10 @@ using Musify.StreamingGateway.Configuration;
 
 namespace Musify.StreamingGateway.Authentication;
 
+/// <param name="Prefix">The storage key prefix the ticket authorizes reading from. Empty means the
+/// ticket was missing, malformed, expired, or otherwise invalid.</param>
+/// <param name="MaxBytes">When set, the caller is limited to the first <c>MaxBytes</c> bytes of the
+/// object — the anonymous preview fragment cap carried by the <c>maxBytes</c> claim.</param>
 public sealed record TicketValidationResult(string Prefix, long? MaxBytes)
 {
     public static readonly TicketValidationResult Invalid = new(string.Empty, null);

backend/Hosts/Musify.StreamingGateway/Middleware/TicketValidationMiddleware.cs

@@ -72,6 +72,12 @@ public sealed class TicketValidationMiddleware(
         await next(context);
     }
 
+    /// <summary>Rewrites the request's <c>Range</c> header so nothing past <paramref name="maxBytes"/>
+    /// is ever asked of the filer — this is what actually enforces the anonymous preview length,
+    /// downstream of the ticket carrying that cap. A request with no <c>Range</c> header (a plain,
+    /// whole-file GET) gets one synthesized, so the filer always responds with a bounded 206 instead of
+    /// streaming the full object. Returns false when the requested range starts at or past the cap, in
+    /// which case the caller should answer 416 directly instead of proxying anything.</summary>
     private static bool TryClampRange(HttpContext context, long maxBytes)
     {
         var rangeHeader = context.Request.Headers.Range;

backend/Hosts/Musify.Worker/Program.cs

@@ -7,6 +7,11 @@ using Musify.Infrastructure.Services;
 
 var builder = Host.CreateApplicationBuilder();
 
+// Registering Mediator pulls in every handler in Musify.Application, including ones
+// (e.g. CreatePlayList, CreateTrack) that depend on IEventBus, which the Worker never
+// registers because it only consumes events, it never publishes them. Only the handlers
+// this process actually dispatches (GenerateMixesForUserCommand) are ever constructed,
+// so the default eager validate-on-build check is too strict for this host.
 builder.ConfigureContainer(new DefaultServiceProviderFactory(new ServiceProviderOptions
 {
     ValidateOnBuild = false,

deploy/.env.example

@@ -1,39 +1,39 @@
 # Development configuration for deploy/compose.yml + compose.dev.yml.
-# Copy to deploy/.env and adjust.
+# Copy to deploy/.env and adjust. Not versioned.
 #
 #   cp deploy/.env.example deploy/.env
-#
-# Requires ../../../Infrastructure running first (Postgres, Zitadel,
-# SeaweedFS, RabbitMQ, Jaeger). See ../../../Infrastructure/README.md.
-# Everything marked "must match Infrastructure's .env" below has to be the
-# same value as the one in that file.
 
 DOTNET_ENVIRONMENT=Development
 
 # --- Public URLs -------------------------------------------------------------
 # How each service is reached from *outside* Docker. `host.docker.internal`
-# resolves to the same address from the browser, from apps running on the
+# resolves to the same address from the browser, from apps running on the host
-# host and from inside the containers, which is what makes the OIDC issuer
+# and from inside the containers, which is what makes the OIDC issuer and the
-# and the presigned S3 URLs valid in both run modes.
+# presigned S3 URLs valid in both run modes.
 PUBLIC_WEB_URL=http://localhost:3000
 PUBLIC_API_URL=http://localhost:5111
 PUBLIC_STREAM_URL=http://localhost:8081
 PUBLIC_AUTH_URL=http://host.docker.internal:8080
 
-# --- PostgreSQL (Infrastructure's shared instance, Musify's own database) ---
+# --- PostgreSQL (shared by Musify and Zitadel) -------------------------------
-# POSTGRES_USER / POSTGRES_PASSWORD must match Infrastructure's .env.
-POSTGRES_HOST=host.docker.internal
 POSTGRES_USER=postgres
 POSTGRES_PASSWORD=postgres
 POSTGRES_DB=musify_db
+POSTGRES_HOST_PORT=59000
 
-# --- Zitadel (OIDC, shared instance) -----------------------------------------
+# --- Zitadel (OIDC) ----------------------------------------------------------
-# Path to the admin service-account PAT Infrastructure's Zitadel writes on
+# The masterkey MUST be exactly 32 characters. The external domain/port form
-# init. Adjust if your Infrastructure checkout lives somewhere else relative
+# the token issuer, so they have to match PUBLIC_AUTH_URL. Changing them needs
-# to this one.
+# a re-init: docker compose -f deploy/compose.yml -f deploy/compose.dev.yml down -v
-ZITADEL_ADMIN_PAT_DIR=../../../Infrastructure/zitadel/.output
+ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters
-# Allows the OIDC apps this project creates to use plain-http redirect URIs
+ZITADEL_EXTERNAL_DOMAIN=host.docker.internal
-# (dev only).
+ZITADEL_EXTERNAL_PORT=8080
+ZITADEL_EXTERNAL_SECURE=false
+ZITADEL_DATABASE_PASSWORD=zitadel
+# Console login: <username>@zitadel.<external domain>
+ZITADEL_ADMIN_USERNAME=admin
+ZITADEL_ADMIN_PASSWORD=Password1!
+# Allows the OIDC apps to use plain-http redirect URIs (dev only).
 ZITADEL_DEV_MODE=true
 
 # OIDC clients: the zitadel-init one-shot service (see compose.yml) fills
@@ -42,25 +42,17 @@ AUTH_CLIENT_ID=
 WEB_CLIENT_ID=
 WEB_CLIENT_SECRET=
 
-# --- RabbitMQ (shared instance, MassTransit) --------------------------------
+# --- RabbitMQ (MassTransit) --------------------------------------------------
-# Must match Infrastructure's .env.
-RABBITMQ_HOST=host.docker.internal
 RABBITMQ_DEFAULT_USER=guest
 RABBITMQ_DEFAULT_PASS=guest
 
-# --- SeaweedFS (S3, shared instance, Musify's own bucket) --------------------
+# --- SeaweedFS (S3) ----------------------------------------------------------
-# S3_ACCESS_KEY / S3_SECRET_KEY must match Infrastructure's .env.
-SEAWEEDFS_HOST=host.docker.internal
 S3_ACCESS_KEY=admin_access_key
 S3_SECRET_KEY=admin_secret_key
 S3_BUCKET=webapi-storage
 S3_PUBLIC_URL=http://host.docker.internal:8333
-S3_INTERNAL_URL=http://host.docker.internal:8333
 S3_USE_HTTP=true
 
-# --- Jaeger (shared instance, tracing) ---------------------------------------
-JAEGER_HOST=host.docker.internal
-
 # --- Web player --------------------------------------------------------------
 # Key material for the encrypted session cookie: any long random string.
 SESSION_SECRET=dev-session-secret-change-me-0123456789abcdef
@@ -69,3 +61,6 @@ AUTH_ALLOW_INSECURE_HTTP=true
 
 # --- Misc --------------------------------------------------------------------
 AUTH_REQUIRE_HTTPS=false
+PGADMIN_DEFAULT_EMAIL=admin@musify.dev
+PGADMIN_DEFAULT_PASSWORD=admin
+PGADMIN_HOST_PORT=5050

deploy/.env.prod.example

@@ -3,14 +3,11 @@
 #
 #   1. replace every `example.com` with your domain,
 #   2. replace every CHANGE_ME with a strong random value
-#      (`openssl rand -hex 24`),
+#      (`openssl rand -hex 24`; the Zitadel masterkey needs exactly 32 chars),
 #   3. point these DNS records at the server, all proxied/TLS-terminated the
 #      same way: example.com, www, api, auth, stream, s3.
 #
-# Requires ../../../Infrastructure running first, on the same Docker host,
+# Not versioned. Keep it readable only by the deploy user (chmod 600).
-# with its own `infra-net` network already created. See
-# ../../../Infrastructure/README.md. Not versioned. Keep it readable only by
-# the deploy user (chmod 600).
 
 DOTNET_ENVIRONMENT=Production
 
@@ -23,15 +20,22 @@ PUBLIC_STREAM_URL=https://stream.example.com
 PUBLIC_AUTH_URL=https://auth.example.com
 S3_PUBLIC_URL=https://s3.example.com
 
-# --- PostgreSQL (Infrastructure's shared instance, Musify's own database) ---
+# --- PostgreSQL (shared by Musify and Zitadel) -------------------------------
-# POSTGRES_USER / POSTGRES_PASSWORD must match Infrastructure's .env.prod.
-POSTGRES_HOST=postgres
 POSTGRES_USER=postgres
 POSTGRES_PASSWORD=CHANGE_ME
 POSTGRES_DB=musify_db
 
-# --- Zitadel (OIDC, shared instance) -----------------------------------------
+# --- Zitadel (OIDC) ----------------------------------------------------------
-ZITADEL_ADMIN_PAT_DIR=../../../Infrastructure/zitadel/.output
+# The masterkey MUST be exactly 32 characters and can never be rotated in place.
+ZITADEL_MASTERKEY=CHANGE_ME_32_CHARACTERS_EXACTLY_
+ZITADEL_EXTERNAL_DOMAIN=auth.example.com
+ZITADEL_EXTERNAL_PORT=443
+ZITADEL_EXTERNAL_SECURE=true
+ZITADEL_DATABASE_PASSWORD=CHANGE_ME
+# Console login: <username>@zitadel.<external domain>
+ZITADEL_ADMIN_USERNAME=admin
+ZITADEL_ADMIN_PASSWORD=CHANGE_ME
+# Keep OIDC apps strict about https redirect URIs in production.
 ZITADEL_DEV_MODE=false
 
 # OIDC clients: the zitadel-init one-shot service (see compose.yml) fills
@@ -40,22 +44,16 @@ AUTH_CLIENT_ID=
 WEB_CLIENT_ID=
 WEB_CLIENT_SECRET=
 
-# --- RabbitMQ (shared instance, MassTransit) --------------------------------
+# --- RabbitMQ (MassTransit) --------------------------------------------------
-RABBITMQ_HOST=rabbitmq
 RABBITMQ_DEFAULT_USER=musify
 RABBITMQ_DEFAULT_PASS=CHANGE_ME
 
-# --- SeaweedFS (S3, shared instance, Musify's own bucket) --------------------
+# --- SeaweedFS (S3) ----------------------------------------------------------
-SEAWEEDFS_HOST=seaweedfs
 S3_ACCESS_KEY=CHANGE_ME
 S3_SECRET_KEY=CHANGE_ME
 S3_BUCKET=webapi-storage
-S3_INTERNAL_URL=http://seaweedfs:8333
 S3_USE_HTTP=false
 
-# --- Jaeger (shared instance, tracing) ---------------------------------------
-JAEGER_HOST=jaeger
-
 # --- Web player --------------------------------------------------------------
 # Key material for the encrypted session cookie. Rotating it logs everyone out.
 SESSION_SECRET=CHANGE_ME

deploy/README.md

@@ -1,65 +1,51 @@
 # Deploy
 
-Everything needed to run Musify itself, in development and in production,
+Everything needed to run Musify, in development and in production, from the
-from the same set of compose files, no wrapper scripts, just `docker
+same set of compose files — no wrapper scripts, just `docker compose`.
-compose`. Postgres, Zitadel, SeaweedFS, RabbitMQ and Jaeger are **not**
-started here: they're shared infrastructure that lives in the separate
-`Infrastructure` repository and has to already be running (see its own
-README). `../../Infrastructure` below is just an example path, assuming
-that repo happens to be checked out as a sibling of this one. Adjust it to
-wherever you actually cloned it.
 
 | File | Role |
 |---|---|
-| `compose.yml` | Musify's own services, including the one-shot bootstrap jobs. No published ports, no domains, no environment-specific values. |
+| `compose.yml` | Every service, including the one-shot bootstrap jobs. No published ports, no domains, no environment-specific values. |
-| `compose.dev.yml` | Development overlay: publishes Musify's ports to the host. |
+| `compose.dev.yml` | Development overlay: publishes the ports to the host, adds pgAdmin. |
-| `compose.prod.yml` | Production overlay: adds the nginx edge and joins Infrastructure's `infra-net` network. |
+| `compose.prod.yml` | Production overlay: adds the nginx edge. |
 | `.env` / `.env.prod` | The values compose interpolates. Not versioned; templates in `.env.example` / `.env.prod.example`. |
 
-The four applications (`api`, `worker`, `gateway`, `web-player`) sit behind
+The four applications (`api`, `worker`, `gateway`, `web-player`) sit behind the
-the `apps` compose profile, so a plain `up` starts only the one-shot
+`apps` compose profile, so a plain `up` starts infrastructure only — the usual
-bootstrap jobs, the usual development setup, with the apps running from the
+development setup, with the apps running from the IDE.
-IDE.
 
 ### The one-shot bootstrap jobs
 
-Four services in `compose.yml` run once and exit, so a plain `docker compose
+Three services in `compose.yml` run once and exit, so a plain `docker compose
 up -d` leaves the stack fully ready with no manual steps:
 
 | Service | Does |
 |---|---|
-| `wait-for-postgres` | Waits for Infrastructure's Postgres to accept connections. Replaces an in-file health-check `depends_on`, which only works within the same compose file. |
 | `keys-init` | Generates the RS256 stream-ticket key pair in `./keys`, if it is not there already. |
 | `migrate` | Applies the EF Core migrations (built from `backend/Musify.Migrator.Dockerfile`). |
-| `seaweedfs-init` | Creates Musify's own bucket on the shared SeaweedFS, if it doesn't exist yet. |
+| `zitadel-init` | Creates the Musify project and its two OIDC apps in Zitadel (or reuses them), then writes `AUTH_CLIENT_ID` / `WEB_CLIENT_ID` / `WEB_CLIENT_SECRET` into the env file. |
-| `zitadel-init` | Creates the Musify project and its OIDC apps in the shared Zitadel (or reuses them), then writes `AUTH_CLIENT_ID` / `WEB_CLIENT_ID` / `WEB_CLIENT_SECRET` / `NATIVE_CLIENT_ID` into the env file. |
 
-`api` and `worker` wait for `migrate`; `api` waits for `keys-init`
+`api` and `worker` wait for `migrate`; `api` and `gateway` wait for
-(`depends_on: condition: service_completed_successfully`). Nothing waits on
+`keys-init` (`depends_on: condition: service_completed_successfully`). They do
-`zitadel-init`, `seaweedfs-init` or the shared infrastructure services
+**not** wait for `zitadel-init` — compose interpolates `${AUTH_CLIENT_ID}` once,
-directly. Compose interpolates `${AUTH_CLIENT_ID}` once, when a command
+when a command starts, so a container that starts in the *same* `up` as
-starts, so a container that started in the *same* `up` as `zitadel-init`
+`zitadel-init` would still get the empty value it had before provisioning ran.
-would still get the empty value it had before provisioning ran. That's why
+That's why bringing up the apps is a second command: by the time you run it,
-bringing up the apps is a second command: by the time you run it,
 `zitadel-init` has already finished and the env file has real values.
 
 ---
 
 ## Development
 
-Start the separate `Infrastructure` repository first, from wherever you
-cloned it (see its own README for the exact command). Then, from this
-repository's root:
-
 ```sh
 docker compose -f deploy/compose.yml -f deploy/compose.dev.yml up -d
 docker compose -f deploy/compose.yml -f deploy/compose.dev.yml --profile apps up -d --build
 ```
 
-The first command starts Musify's own bootstrap jobs (Postgres wait, keys,
+The first command starts the infrastructure and runs the bootstrap jobs
-migrations, the bucket, the Zitadel project/apps). The second builds and runs
+(keys, migrations, Zitadel project/apps). The second builds and runs `api`,
-`api`, `worker`, `gateway` and `web-player` in Docker too. Skip it to run the
+`worker`, `gateway` and `web-player` in Docker too — skip it to run the apps
-apps from the IDE instead (the usual dev loop):
+from the IDE instead (the usual dev loop):
 
 ```sh
 dotnet run --project backend/Hosts/Musify.Api               # :5111
@@ -69,55 +55,53 @@ npm --prefix web-player run dev                              # :5173
 ```
 
 When running the apps from the IDE, `Musify.Api` reads `Authentication:*`
-from user-secrets and `web-player` reads its own `web-player/.env`, neither
+from user-secrets and `web-player` reads its own `web-player/.env` — neither
-looks at `deploy/.env`. Copy the four values `zitadel-init` wrote
+looks at `deploy/.env`. Copy the three values `zitadel-init` wrote
-(`AUTH_CLIENT_ID`, `WEB_CLIENT_ID`, `WEB_CLIENT_SECRET`, `NATIVE_CLIENT_ID`)
+(`AUTH_CLIENT_ID`, `WEB_CLIENT_ID`, `WEB_CLIENT_SECRET`) into
-into `dotnet user-secrets set Authentication:ClientId <value> --project
+`dotnet user-secrets set Authentication:ClientId <value> --project
-backend/Hosts/Musify.Api` and into `web-player/.env` once. They stay valid
+backend/Hosts/Musify.Api` and into `web-player/.env` once; they stay valid
-until Infrastructure's Zitadel volume is wiped.
+until you wipe the Zitadel volume.
+
+Add `--profile tools` to also start pgAdmin.
 
 ### Ports
 
 | Service | Port | Used by |
 |---|---|---|
-| Musify.Api | `5111` | `/scalar/v1`, `/openapi/v1.json` |
+| PostgreSQL | `59000` → 5432 | API + Worker (EF Core) and Zitadel |
-| Musify.StreamingGateway | `8081` | `/health`, `/media/...` |
+| Zitadel | `8080` | OIDC/OAuth2, console at `/ui/console` |
-| web-player | `5173` (`npm run dev`) or `3000` (container) | |
+| RabbitMQ | `5672` / `15672` | MassTransit / management UI |
+| SeaweedFS | `8333` / `8888` / `9333` | S3 / filer (→ gateway) / master |
+| Jaeger | `16686` / `4317` / `4318` | traces UI / OTLP gRPC / OTLP HTTP |
+| pgAdmin (`--profile tools`) | `5050` | Postgres UI |
+| API, gateway, web player (`--profile apps`) | `5111` / `8081` / `3000` | |
 
-Postgres, Zitadel, SeaweedFS, RabbitMQ and Jaeger ports come from
+Host requirements: .NET 10 SDK, Node 22, Docker Desktop. (ffmpeg is only
-Infrastructure. See its own README for that table.
+needed on the host if you run the Worker outside Docker — inside Docker its
-
+image already has it.)
-Host requirements: .NET 10 SDK, Node 22, Docker Desktop. ffmpeg is only
-needed on the host if you run the Worker outside Docker; inside Docker its
-image already has it.
 
 ### Why `host.docker.internal`
 
 `PUBLIC_AUTH_URL` and `S3_PUBLIC_URL` point at `host.docker.internal`, which
 resolves to the same address from the browser, from apps running on the host
 and from inside the containers. That keeps the OIDC token issuer and the
-presigned S3 URLs valid whichever way the apps are running, and is the same
+presigned S3 URLs valid whichever way the apps are running. Zitadel routes by
-address Infrastructure's own dev ports are published on.
+the `Host` header, so the domain has to be identical everywhere; changing it
+requires wiping the Postgres/Zitadel volumes and starting over (`docker
+compose -f compose.yml -f compose.dev.yml down -v`, then `up -d` again).
 
 ### Resetting
 
 ```sh
 docker compose -f deploy/compose.yml -f deploy/compose.dev.yml down          # stop, keep data
-docker compose -f deploy/compose.yml -f deploy/compose.dev.yml down -v       # stop, wipe Musify's own volumes
+docker compose -f deploy/compose.yml -f deploy/compose.dev.yml down -v       # stop, wipe volumes
 ```
 
-This only touches Musify's own containers and volumes. Resetting Zitadel or
-SeaweedFS is done from the `Infrastructure` repo instead.
-
 ---
 
 ## Production
 
-On a server with a domain:
+On a server with a domain, from the repository root:
-
-1. Bring up the `Infrastructure` repo first, with its own `.env.prod` filled
-   in. It creates the `infra-net` network this stack joins.
-2. From this repository's root:
 
 ```sh
 cp deploy/.env.prod.example deploy/.env.prod
@@ -126,29 +110,31 @@ cp deploy/.env.prod.example deploy/.env.prod
 Fill it in:
 
 1. Replace every `example.com` with your domain and every `CHANGE_ME` with a
-   random value (`openssl rand -hex 24`). `chmod 600 deploy/.env.prod`.
+   random value (`openssl rand -hex 24`; the Zitadel masterkey needs exactly
-2. Drop **`deploy/nginx/certs/origin.pem` and `origin.key`**, the origin
+   32 characters). `chmod 600 deploy/.env.prod`.
+2. Drop **`deploy/nginx/certs/origin.pem` and `origin.key`** — the origin
    certificate nginx serves. The stack assumes Cloudflare in *Full (strict)*
    mode in front of it, so a Cloudflare Origin Certificate is enough; any
    certificate valid for the five hostnames works.
 3. Point `example.com`, `www`, `api`, `auth`, `stream` and `s3` at the server,
-   proxied and TLS-terminated the same way.
+   proxied/TLS-terminated the same way.
 
-Then:
+Then, same two commands as development, with the prod env file and overlay:
 
 ```sh
 docker compose --env-file deploy/.env.prod -f deploy/compose.yml -f deploy/compose.prod.yml up -d
 docker compose --env-file deploy/.env.prod -f deploy/compose.yml -f deploy/compose.prod.yml --profile apps up -d --build
 ```
 
-The first command starts Musify's bootstrap jobs and the nginx edge; the
+The first command starts the infrastructure, the nginx edge and the bootstrap
-second builds and starts the applications, already wired to the OIDC client
+jobs; the second builds and starts the applications, already wired to the
-ids the first one produced. Both are idempotent, so running them again
+OIDC client ids the first one produced. Both are idempotent — run them again
-deploys a new version (`... --profile apps up -d --build` alone is enough for
+to deploy a new version (`docker compose ... --profile apps up -d --build`
-an update once the stack already exists).
+alone is enough for an update once the stack already exists; it reuses the
+infra containers and only rebuilds and restarts the apps).
 
-Only nginx publishes ports (80/443). Every other Musify service, and all of
+Only nginx publishes ports (80/443); everything else is reachable only on the
-Infrastructure's, is reachable only on the internal `infra-net` network.
+internal compose network.
 
 ---
 
@@ -156,16 +142,17 @@ Infrastructure's, is reachable only on the internal `infra-net` network.
 
 ```
 deploy/
-├─ compose.yml                     # Musify's own services: wait-for-postgres, keys-init,
+├─ compose.yml                     # all services, incl. keys-init / migrate / zitadel-init
-│                                   #   migrate, seaweedfs-init, zitadel-init, api/worker/gateway/web-player
+├─ compose.dev.yml                 # dev overlay: host ports, pgAdmin
-├─ compose.dev.yml                 # dev overlay: host ports
+├─ compose.prod.yml                # prod overlay: nginx edge
-├─ compose.prod.yml                # prod overlay: nginx edge, joins infra-net
 ├─ .env.example / .env.prod.example
 ├─ keys/                           # RS256 stream-ticket key pair (generated)
-└─ nginx/
+├─ nginx/
-   ├─ templates/default.conf.template # vhosts, rendered with the domain by envsubst
+│  ├─ templates/default.conf.template # vhosts, rendered with the domain by envsubst
-   ├─ snippets/proxy.conf             # proxy headers shared by every vhost
+│  ├─ snippets/proxy.conf             # proxy headers shared by every vhost
-   └─ certs/                          # origin.pem + origin.key (not versioned)
+│  └─ certs/                          # origin.pem + origin.key (not versioned)
+└─ zitadel/
+   └─ .output/                    # PAT written by Zitadel on init (not versioned)
 ```
 
 The application images are built from `backend/Musify.*.Dockerfile` (build
@@ -174,15 +161,18 @@ and `web-player/Dockerfile`.
 
 ## Notes
 
-- **S3 credentials, the Postgres admin user, the RabbitMQ user and the
+- **S3 credentials** are rendered into the SeaweedFS identity file from
-  Zitadel masterkey** all live in Infrastructure's own `.env`/`.env.prod` now.
+  `S3_ACCESS_KEY` / `S3_SECRET_KEY` when the container starts, so they cannot
-  This project's env files only duplicate the values that have to match (see
+  drift from the ones the apps are given.
-  the comments in `.env.example`).
 - **Zitadel** runs `start-from-init`, which is idempotent: the same command
   works on an empty volume and on an existing one.
+- **`latest` Zitadel images** require the standalone Login UI v2 container,
+  which this stack does not run. `zitadel-init` turns that requirement off so
+  the built-in `/ui/login` is used.
 - **`AppSettings*.json` are PascalCase** in `Musify.Api` and `Musify.Worker`;
   on case-sensitive Linux the host looks for `appsettings*.json`, so their
   Dockerfiles create lowercase copies at publish time.
-- **Re-running `zitadel-init`, `seaweedfs-init` or `migrate`** is safe: they
+- **Re-running `zitadel-init` or `migrate`** is safe: the former reuses the
-  reuse the existing project/apps/bucket by name, and `migrate` is a normal
+  existing project/apps by name (regenerating the web app's secret only if it
-  `dotnet ef database update`, a no-op once the schema is current.
+  is missing from the env file), the latter is a normal `dotnet ef database
+  update`, a no-op once the schema is current.

deploy/compose.dev.yml

@@ -1,36 +1,67 @@
 name: musify-dev
 
-# Development overlay: publishes Musify's own ports to the host so the .NET
+# Development overlay: publishes the infrastructure ports to the host so the
-# apps and the web player can run from the IDE.
+# .NET apps and the web player can run from the IDE, and adds pgAdmin.
 #
 #   docker compose -f deploy/compose.yml -f deploy/compose.dev.yml up -d
 #   docker compose -f deploy/compose.yml -f deploy/compose.dev.yml --profile apps up -d --build
 #
-# Postgres/Zitadel/SeaweedFS/RabbitMQ/Jaeger ports come from Infrastructure's
+# `host.docker.internal` (see ZITADEL_EXTERNAL_DOMAIN / *_PUBLIC_URL in .env)
-# own compose.dev.yml, not from here. See ../../../Infrastructure/README.md.
+# resolves to the same address from the browser, from apps on the host and from
-# `host.docker.internal` resolves to the same address from the browser, from
+# inside the containers, so the OIDC issuer and the presigned S3 URLs are valid
-# apps on the host and from inside these containers, which is what makes the
+# in both modes. `extra_hosts` gives Linux containers that same name.
-# OIDC issuer and the presigned S3 URLs valid in both run modes. `extra_hosts`
-# gives Linux containers that same name.
 
 x-host-alias: &host-alias
-  - "host.docker.internal:host-gateway"
+  - "${ZITADEL_EXTERNAL_DOMAIN}:host-gateway"
 
 services:
-  wait-for-postgres:
+  postgres:
-    extra_hosts: *host-alias
+    ports:
+      - "${POSTGRES_HOST_PORT}:5432"
 
-  seaweedfs-init:
+  zitadel:
-    extra_hosts: *host-alias
+    ports:
+      - "${ZITADEL_EXTERNAL_PORT}:8080"
+
+  rabbitmq:
+    ports:
+      - "5672:5672"     # AMQP -> MassTransit
+      - "15672:15672"   # management UI
+
+  seaweedfs:
+    ports:
+      - "9333:9333"   # master / admin UI
+      - "8888:8888"   # filer      -> StreamingGateway
+      - "8333:8333"   # S3 API     -> API, Worker and presigned uploads
+
+  jaeger:
+    ports:
+      - "16686:16686"   # UI
+      - "4317:4317"     # OTLP gRPC
+      - "4318:4318"     # OTLP HTTP
 
   # zitadel-init (compose.yml) edits whichever env file is mounted here.
   zitadel-init:
-    extra_hosts: *host-alias
     volumes:
       - ./.env:/workspace/.env
 
-  migrate:
+  # Optional Postgres UI: docker compose ... --profile tools up -d
-    extra_hosts: *host-alias
+  pgadmin:
+    profiles: [tools]
+    image: dpage/pgadmin4:latest
+    container_name: musify-pgadmin
+    environment:
+      PGADMIN_DEFAULT_EMAIL: ${PGADMIN_DEFAULT_EMAIL}
+      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_DEFAULT_PASSWORD}
+      PGADMIN_CONFIG_SERVER_MODE: "False"
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports:
+      - "${PGADMIN_HOST_PORT}:80"
+    volumes:
+      - pgadmin_data:/var/lib/pgadmin
+    restart: unless-stopped
 
   api:
     ports:
@@ -49,3 +80,6 @@ services:
     ports:
       - "3000:3000"
     extra_hosts: *host-alias
+
+volumes:
+  pgadmin_data:

deploy/compose.prod.yml

@@ -1,19 +1,16 @@
 name: musify-prod
 
-# Production overlay: adds the nginx edge and joins Infrastructure's shared
+# Production overlay: adds the nginx edge and the host-mounted secrets.
-# `infra-net` network so this project's containers can reach Postgres,
+# Nothing but nginx publishes a port; every other service is reachable only on
-# Zitadel, SeaweedFS, RabbitMQ and Jaeger by container name. None of them
+# the internal `musify-prod_default` network.
-# run as part of this compose project anymore (see
-# ../../../Infrastructure/README.md, which must already be up). Nothing but
-# nginx publishes a port; every other service is reachable only on infra-net.
 #
 #   docker compose --env-file deploy/.env.prod -f deploy/compose.yml -f deploy/compose.prod.yml up -d
 #   docker compose --env-file deploy/.env.prod -f deploy/compose.yml -f deploy/compose.prod.yml --profile apps up -d --build
-
+#
-networks:
+# The first command starts the infrastructure, the nginx edge and the
-  default:
+# one-shot bootstrap jobs (stream keys, migrations, Zitadel project/apps); the
-    name: infra-net
+# second builds and starts the applications, picking up the OIDC client ids
-    external: true
+# the first command just wrote into deploy/.env.prod. See deploy/README.md.
 
 services:
   # zitadel-init (compose.yml) edits whichever env file is mounted here.
@@ -23,13 +20,16 @@ services:
 
   # Every vhost proxies through `set $upstream ...; proxy_pass $upstream;`
   # with the embedded Docker DNS resolver (see nginx/templates), so nginx
-  # does not need api/gateway/web-player to exist at its own startup, only
+  # does not need api/gateway/web-player to exist at its own startup — only
   # at request time. That is what lets it start in the FIRST command
   # (profile-gated services aren't part of that invocation yet) and still be
   # reachable at the auth domain for zitadel-init to provision through.
   nginx:
     image: nginx:1.27-alpine
     container_name: musify-nginx
+    depends_on:
+      zitadel:
+        condition: service_started
     environment:
       # The entrypoint renders /etc/nginx/templates/*.template with envsubst.
       # The filter keeps it from eating nginx's own $host / $remote_addr.

deploy/compose.yml

@@ -1,32 +1,33 @@
-# Musify: base stack, shared by development and production.
+# Musify — base stack, shared by development and production.
 #
-# Postgres, Zitadel, SeaweedFS, RabbitMQ and Jaeger are NOT part of this
+# This file publishes no host ports and hardcodes no domain: everything that
-# file. They're shared infrastructure that lives in ../../../Infrastructure
+# differs between environments comes from the .env file (see .env.example) or
-# and must already be running (see Infrastructure/README.md). This file only
+# from the overlay that is merged on top of it.
-# has what's specific to Musify: its own database, its own OIDC apps and
-# storage bucket (created against the shared instances below), and its own
-# apps.
 #
 #   dev   docker compose -f deploy/compose.yml -f deploy/compose.dev.yml up -d
 #   prod  docker compose --env-file deploy/.env.prod -f deploy/compose.yml -f deploy/compose.prod.yml up -d
 #
-# The four application services sit behind the `apps` profile, so a plain
+# The four application services sit behind the `apps` profile, so a plain `up`
-# `up` runs only the one-shot bootstrap jobs (stream-ticket keys, database
+# starts the infrastructure plus the one-shot bootstrap jobs (stream-ticket
-# migrations, Zitadel project/apps, the storage bucket) and stops there. That's
+# keys, database migrations, Zitadel project/apps) and stops there — the usual
-# the usual dev setup, with the apps running from the IDE. Add `--profile apps
+# dev setup, with the apps running from the IDE. Add `--profile apps up -d
-# up -d --build` as a SECOND command to also build and run them in Docker: by
+# --build` as a SECOND command to also build and run them in Docker: by then
-# then zitadel-init has already written the OIDC client ids into the env
+# zitadel-init has already written the OIDC client ids into the env file, so
-# file, so the apps start with real values. See deploy/README.md.
+# the apps start with real values. See deploy/README.md.
+
+x-app-depends: &app-depends
+  postgres:
+    condition: service_healthy
+  rabbitmq:
+    condition: service_healthy
+  seaweedfs:
+    condition: service_healthy
 
 # Backend settings that are identical for the API and the Worker. ASP.NET Core
 # maps `__` to `:`, so these override the matching AppSettings.json sections.
-# POSTGRES_HOST / RABBITMQ_HOST / JAEGER_HOST differ between environments
-# (host.docker.internal in dev, the container name over infra-net in prod,
-# see .env.example / .env.prod.example), same as PUBLIC_AUTH_URL/S3_PUBLIC_URL
-# already do.
 x-backend-env: &backend-env
-  Database__ConnectionString: "Host=${POSTGRES_HOST};Port=5432;Database=${POSTGRES_DB};Username=${POSTGRES_USER};Password=${POSTGRES_PASSWORD}"
+  Database__ConnectionString: "Host=postgres;Port=5432;Database=${POSTGRES_DB};Username=${POSTGRES_USER};Password=${POSTGRES_PASSWORD}"
-  MassTransit__Address: "rabbitmq://${RABBITMQ_HOST}:5672"
+  MassTransit__Address: "rabbitmq://rabbitmq:5672"
   MassTransit__Username: ${RABBITMQ_DEFAULT_USER}
   MassTransit__Password: ${RABBITMQ_DEFAULT_PASS}
   # The public S3 URL, not the internal one: the same address is used to sign
@@ -37,35 +38,128 @@ x-backend-env: &backend-env
   InfrastructureStorage__ForcePathStyle: "true"
   InfrastructureStorage__UseHttp: ${S3_USE_HTTP}
   ApplicationStorage__Bucket: ${S3_BUCKET}
-  OpenTelemetry__OtlpEndpoint: "http://${JAEGER_HOST}:4317"
+  OpenTelemetry__OtlpEndpoint: "http://jaeger:4317"
 
 services:
-  # --- Shared-infrastructure bootstrap ---------------------------------------
+  # --- Infrastructure -------------------------------------------------------
 
-  # Waits for Infrastructure's Postgres to accept connections before `migrate`
+  postgres:
-  # runs. This replaces a `depends_on: postgres: condition: service_healthy`:
-  # that only works within the same compose file, and Postgres now lives in a
-  # separate one (../../../Infrastructure).
-  wait-for-postgres:
     image: postgres:17-alpine
-    container_name: musify-wait-for-postgres
+    container_name: musify-postgres
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+  # OIDC provider. `start-from-init` runs init + setup (both idempotent) and
+  # then starts, so the same command works on a cold and on a warm volume.
+  # It reuses the Postgres above: the admin user creates the `zitadel` database
+  # and role on first start.
+  zitadel:
+    image: ghcr.io/zitadel/zitadel:latest
+    container_name: musify-zitadel
+    command: start-from-init --masterkeyFromEnv --tlsMode disabled
+    environment:
+      ZITADEL_MASTERKEY: ${ZITADEL_MASTERKEY}
+      # The external domain/port forms the token issuer and must be identical
+      # for the browser, the apps and the containers (Zitadel routes by Host).
+      ZITADEL_EXTERNALSECURE: ${ZITADEL_EXTERNAL_SECURE}
+      ZITADEL_EXTERNALDOMAIN: ${ZITADEL_EXTERNAL_DOMAIN}
+      ZITADEL_EXTERNALPORT: ${ZITADEL_EXTERNAL_PORT}
+      ZITADEL_TLS_ENABLED: "false"
+      ZITADEL_DATABASE_POSTGRES_HOST: postgres
+      ZITADEL_DATABASE_POSTGRES_PORT: 5432
+      ZITADEL_DATABASE_POSTGRES_DATABASE: zitadel
+      ZITADEL_DATABASE_POSTGRES_USER_USERNAME: zitadel
+      ZITADEL_DATABASE_POSTGRES_USER_PASSWORD: ${ZITADEL_DATABASE_PASSWORD}
+      ZITADEL_DATABASE_POSTGRES_USER_SSL_MODE: disable
+      ZITADEL_DATABASE_POSTGRES_ADMIN_USERNAME: ${POSTGRES_USER}
+      ZITADEL_DATABASE_POSTGRES_ADMIN_PASSWORD: ${POSTGRES_PASSWORD}
+      ZITADEL_DATABASE_POSTGRES_ADMIN_SSL_MODE: disable
+      # Initial console admin. Login: <username>@zitadel.<external domain>
+      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME: ${ZITADEL_ADMIN_USERNAME}
+      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: ${ZITADEL_ADMIN_PASSWORD}
+      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: "false"
+      # Service account + PAT written on init; the provisioning script uses it
+      # to create the Musify project and its OIDC apps.
+      ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME: zitadel-admin-sa
+      ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME: Admin Service Account
+      ZITADEL_FIRSTINSTANCE_ORG_MACHINE_PAT_EXPIRATIONDATE: "2099-01-01T00:00:00Z"
+      ZITADEL_FIRSTINSTANCE_PATPATH: /output/admin-sa.pat
+    depends_on:
+      postgres:
+        condition: service_healthy
+    volumes:
+      - ./zitadel/.output:/output
+    restart: unless-stopped
+
+  rabbitmq:
+    image: rabbitmq:4-management-alpine
+    container_name: musify-rabbitmq
+    environment:
+      RABBITMQ_DEFAULT_USER: ${RABBITMQ_DEFAULT_USER}
+      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_DEFAULT_PASS}
+    volumes:
+      - rabbitmq_data:/var/lib/rabbitmq
+    healthcheck:
+      test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+  # All-in-one object store: master + volume + filer + S3 gateway.
+  # The S3 identity file is rendered from the environment on start so the
+  # credentials can never drift from the ones handed to the apps.
+  seaweedfs:
+    image: chrislusf/seaweedfs:latest
+    container_name: musify-seaweedfs
     entrypoint: ["/bin/sh", "-c"]
     command:
       - |
-        set -e
+        cat > /tmp/s3.conf <<'JSON'
-        deadline=$$(( $$(date +%s) + 60 ))
+        {
-        until pg_isready -h ${POSTGRES_HOST} -p 5432 -U ${POSTGRES_USER} >/dev/null 2>&1; do
+          "identities": [
-          [ "$$(date +%s)" -lt "$$deadline" ] || { echo "postgres did not respond at ${POSTGRES_HOST}:5432. Is Infrastructure running?" >&2; exit 1; }
+            {
-          sleep 2
+              "name": "musify",
-        done
+              "credentials": [{ "accessKey": "${S3_ACCESS_KEY}", "secretKey": "${S3_SECRET_KEY}" }],
-    restart: "no"
+              "actions": ["Admin", "Read", "Write"]
+            }
+          ]
+        }
+        JSON
+        exec weed server \
+          -ip.bind=0.0.0.0 \
+          -dir=/data \
+          -master.volumeSizeLimitMB=1024 \
+          -volume.max=0 \
+          -filer \
+          -s3 \
+          -s3.config=/tmp/s3.conf
+    volumes:
+      - seaweedfs_data:/data
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "-", "http://localhost:9333/cluster/healthz"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
 
-  # One-shot: SeaweedFS does not auto-create buckets. `aws s3 ls` doubles as
+  # One-shot: SeaweedFS does not auto-create buckets.
-  # the readiness probe, since seaweedfs-init no longer has an in-file
-  # `depends_on: seaweedfs: condition: service_healthy` to wait for.
   seaweedfs-init:
     image: amazon/aws-cli:latest
     container_name: musify-seaweedfs-init
+    depends_on:
+      seaweedfs:
+        condition: service_healthy
     environment:
       AWS_ACCESS_KEY_ID: ${S3_ACCESS_KEY}
       AWS_SECRET_ACCESS_KEY: ${S3_SECRET_KEY}
@@ -73,19 +167,13 @@ services:
     entrypoint: ["/bin/sh", "-c"]
     command:
       - |
-        set -e
+        aws --endpoint-url http://seaweedfs:8333 s3 mb s3://${S3_BUCKET} 2>/dev/null || true
-        deadline=$$(( $$(date +%s) + 60 ))
+        aws --endpoint-url http://seaweedfs:8333 s3 ls
-        until aws --endpoint-url ${S3_PUBLIC_URL} s3 ls >/dev/null 2>&1; do
-          [ "$$(date +%s)" -lt "$$deadline" ] || { echo "seaweedfs did not respond at ${S3_PUBLIC_URL}. Is Infrastructure running?" >&2; exit 1; }
-          sleep 2
-        done
-        aws --endpoint-url ${S3_PUBLIC_URL} s3 mb s3://${S3_BUCKET} 2>/dev/null || true
-        aws --endpoint-url ${S3_PUBLIC_URL} s3 ls
     restart: "no"
 
   # One-shot: generates the RS256 key pair used to sign (API) and verify
   # (Gateway) stream tickets, if it is not already in ./keys. No host tools
-  # required, since openssl runs inside the container.
+  # required — openssl runs inside the container.
   keys-init:
     image: alpine:3.20
     container_name: musify-keys-init
@@ -115,27 +203,30 @@ services:
       dockerfile: Musify.Migrator.Dockerfile
     container_name: musify-migrate
     depends_on:
-      wait-for-postgres:
+      postgres:
-        condition: service_completed_successfully
+        condition: service_healthy
     environment:
-      Database__ConnectionString: "Host=${POSTGRES_HOST};Port=5432;Database=${POSTGRES_DB};Username=${POSTGRES_USER};Password=${POSTGRES_PASSWORD}"
+      Database__ConnectionString: "Host=postgres;Port=5432;Database=${POSTGRES_DB};Username=${POSTGRES_USER};Password=${POSTGRES_PASSWORD}"
     restart: "no"
 
-  # One-shot: creates the Musify project and its two OIDC apps in the shared
+  # One-shot: creates the Musify project and its two OIDC apps in Zitadel (or
-  # Zitadel (or reuses them if they already exist), then writes
+  # reuses them if they already exist), then writes AUTH_CLIENT_ID,
-  # AUTH_CLIENT_ID, WEB_CLIENT_ID and WEB_CLIENT_SECRET back into the env file
+  # WEB_CLIENT_ID and WEB_CLIENT_SECRET back into the env file mounted at
-  # mounted at /workspace/.env (see compose.dev.yml / compose.prod.yml), so a
+  # /workspace/.env (see compose.dev.yml / compose.prod.yml) — so a later
-  # later `--profile apps up` picks up real values instead of empty ones.
+  # `--profile apps up` picks up real values instead of empty ones.
   zitadel-init:
     image: alpine:3.20
     container_name: musify-zitadel-init
+    depends_on:
+      zitadel:
+        condition: service_started
     environment:
       PUBLIC_AUTH_URL: ${PUBLIC_AUTH_URL}
       PUBLIC_API_URL: ${PUBLIC_API_URL}
       PUBLIC_WEB_URL: ${PUBLIC_WEB_URL}
       ZITADEL_DEV_MODE: ${ZITADEL_DEV_MODE:-false}
     volumes:
-      - ${ZITADEL_ADMIN_PAT_DIR}:/output:ro
+      - ./zitadel/.output:/output:ro
     entrypoint: ["/bin/sh", "-c"]
     command:
       - |
@@ -149,7 +240,7 @@ services:
         fi
 
         # The env file may have CRLF line endings (edited on Windows), so
-        # strip \r on read and drop it on write, otherwise a "blank" value
+        # strip \r on read and drop it on write — otherwise a "blank" value
         # is actually a lone \r, and `[ -z ... ]` lies.
         env_get() { grep -E "^$$2=" "$$1" 2>/dev/null | tail -n1 | cut -d= -f2- | tr -d '\r'; }
         env_set() {
@@ -166,7 +257,7 @@ services:
         echo "==> waiting for the Zitadel service-account PAT"
         deadline=$$(( $$(date +%s) + 180 ))
         while [ ! -f /output/admin-sa.pat ]; do
-          [ "$$(date +%s)" -lt "$$deadline" ] || { echo "PAT not found under /output. Is Infrastructure's Zitadel running? Check 'docker logs infra-zitadel'." >&2; exit 1; }
+          [ "$$(date +%s)" -lt "$$deadline" ] || { echo "PAT not found, check 'docker logs musify-zitadel'" >&2; exit 1; }
           sleep 3
         done
         PAT=$$(tr -d '\r\n' </output/admin-sa.pat)
@@ -296,6 +387,14 @@ services:
         echo "==> wired into $$ENV_FILE"
     restart: "no"
 
+  # OTLP collector + trace UI (MassTransit / EF Core / HTTP spans).
+  jaeger:
+    image: jaegertracing/all-in-one:latest
+    container_name: musify-jaeger
+    environment:
+      COLLECTOR_OTLP_ENABLED: "true"
+    restart: unless-stopped
+
   # --- Applications (profile: apps) -----------------------------------------
 
   api:
@@ -305,6 +404,7 @@ services:
       dockerfile: Musify.Api.Dockerfile
     container_name: musify-api
     depends_on:
+      <<: *app-depends
       migrate:
         condition: service_completed_successfully
       keys-init:
@@ -339,6 +439,7 @@ services:
       dockerfile: Musify.Worker.Dockerfile
     container_name: musify-worker
     depends_on:
+      <<: *app-depends
       migrate:
         condition: service_completed_successfully
     environment:
@@ -357,13 +458,15 @@ services:
       dockerfile: Musify.StreamingGateway.Dockerfile
     container_name: musify-gateway
     depends_on:
+      seaweedfs:
+        condition: service_healthy
       keys-init:
         condition: service_completed_successfully
     environment:
       ASPNETCORE_ENVIRONMENT: ${DOTNET_ENVIRONMENT}
       ASPNETCORE_URLS: http://+:8081
       StreamTicket__PublicKeyPath: /keys/stream_public.pem
-      ReverseProxy__Clusters__seaweed-filer__Destinations__filer__Address: "http://${SEAWEEDFS_HOST}:8888/"
+      ReverseProxy__Clusters__seaweed-filer__Destinations__filer__Address: "http://seaweedfs:8888/"
       ReverseProxy__Routes__media__Transforms__0__PathPattern: "/buckets/${S3_BUCKET}/{**rest}"
       Cors__AllowedOrigins__0: ${PUBLIC_WEB_URL}
     volumes:
@@ -392,5 +495,10 @@ services:
       API_BASE_URL: http://api:5111
       # Presigned PUTs are signed for the public S3 host; the container sends
       # them straight to SeaweedFS instead of going back out through the edge.
-      S3_UPLOAD_ENDPOINT: ${S3_INTERNAL_URL}
+      S3_UPLOAD_ENDPOINT: http://seaweedfs:8333
     restart: unless-stopped
+
+volumes:
+  postgres_data:
+  rabbitmq_data:
+  seaweedfs_data:

docs/README.md

@@ -1,58 +1,47 @@
-# Musify documentation
+# Musify — Documentación
 
-Musify is a music streaming backend: upload tracks, process them (transcode
+Musify es un backend de streaming de música: subir pistas, procesarlas (transcodificar el audio a `.m4a` y generar miniaturas), organizarlas en playlists y reproducirlas en streaming sin que los bytes pasen por la API.
-the audio to `.m4a`, generate thumbnails), organize them into playlists, and
-stream them without the bytes ever passing through the API.
 
-This folder explains **what each piece does, its purpose, and why it's built
+Esta carpeta explica **qué hace cada pieza, su propósito y por qué está diseñada así**.
-this way**.
 
-## Index
+## Índice
 
-- [architecture.md](architecture.md): overview, components, how they fit together, and the main flows.
+- [architecture.md](architecture.md) — Visión global: componentes, cómo encajan y los flujos principales.
-- [projects.md](projects.md): what each project/solution is and what it's for.
+- [projects.md](projects.md) — Qué es y para qué sirve cada proyecto/solución.
-- [authentication.md](authentication.md): Zitadel (OIDC), JWT validation, user provisioning/sync.
+- [authentication.md](authentication.md) — Zitadel (OIDC), validación de JWT, provisioning/sync de usuarios.
-- [storage.md](storage.md): SeaweedFS (S3), key layout, presigned URLs, what's public vs. private.
+- [storage.md](storage.md) — SeaweedFS (S3), estructura de claves, URLs prefirmadas, qué es público y qué privado.
-- [streaming.md](streaming.md): audio streaming (`.m4a` over HTTP range) with stream tickets (RS256) and the reverse proxy (StreamingGateway).
+- [streaming.md](streaming.md) — Streaming del audio (`.m4a` por HTTP range) con stream-ticket (RS256) y el reverse proxy (StreamingGateway).
-- [media-processing.md](media-processing.md): the worker and its MassTransit workflows (audio transcoding, thumbnails).
+- [media-processing.md](media-processing.md) — El worker y los workflows de MassTransit (transcode de audio, miniaturas).
-- [development.md](development.md): running everything locally, containers, ports, commands.
+- [development.md](development.md) — Cómo levantar todo en local: contenedores, puertos y comandos.
-- [../deploy/README.md](../deploy/README.md): deployment in detail, compose, scripts, and production.
+- [../deploy/README.md](../deploy/README.md) — El deploy en detalle: compose, scripts y producción.
 
-## Component map (high level)
+## Mapa de componentes (alto nivel)
 
 ```
                  ┌─────────────────────────────────────────────┐
-   Client   ───► │ Musify.Api (:5111)  REST API + issues tickets│
+   Cliente  ───► │ Musify.Api (:5111)  API REST + emite tickets │
                  └─────────────────────────────────────────────┘
-                        │ EF Core          │ presigned (uploads)   │ MassTransit (events)
+                        │ EF Core          │ presigned (subidas)   │ MassTransit (eventos)
                         ▼                  ▼                       ▼
-                 PostgreSQL          SeaweedFS S3 (:8333)     RabbitMQ ──► Worker (processes)
+                 PostgreSQL          SeaweedFS S3 (:8333)     RabbitMQ ──► Worker (procesa)
-                 (metadata)          (objects)                            audio→.m4a, images
+                 (metadatos)         (objetos)                            audio→.m4a, imágenes
                                           ▲
-   Client   ───► StreamingGateway (:8081) ┘   serves .m4a audio (validates ticket, proxies to the filer)
+   Cliente  ───► StreamingGateway (:8081) ┘   sirve audio .m4a (valida ticket, proxy al filer)
 
-   Login: Client ◄──► Zitadel (:8080, OIDC)   →  Musify.Api validates the JWT
+   Login: Cliente ◄──► Zitadel (:8080, OIDC)   →  Musify.Api valida el JWT
 ```
 
-PostgreSQL, Zitadel, SeaweedFS and RabbitMQ are not run by this repository.
-They're shared infrastructure, provided by the separate `Infrastructure`
-repository, that this stack connects to the same way any other project
-does.
-
 ## Stack
 
 - **.NET 10**, C#. Minimal APIs (`Musify.Api`), Worker Service (`Musify.Worker`), ASP.NET + YARP (`Musify.StreamingGateway`).
-- **CQRS** with [Mediator] (source generator) and results via **ErrorOr**.
+- **CQRS** con [Mediator] (source-generator) y resultados con **ErrorOr**.
-- **EF Core 10** + **PostgreSQL** (metadata).
+- **EF Core 10** + **PostgreSQL** (metadatos).
-- **MassTransit 8** + **RabbitMQ** (async processing with routing slips/sagas).
+- **MassTransit 8** + **RabbitMQ** (procesado asíncrono con routing slips/sagas).
-- **SeaweedFS** (S3-compatible object storage, via AWSSDK.S3).
+- **SeaweedFS** (almacenamiento de objetos compatible con S3, vía AWSSDK.S3).
-- **ffmpeg** (audio transcoding to AAC/`.m4a`), **SixLabors.ImageSharp** (thumbnails).
+- **ffmpeg** (transcode de audio a AAC/`.m4a`), **SixLabors.ImageSharp** (miniaturas).
-- **Zitadel** (OIDC/OAuth2) for identity.
+- **Zitadel** (OIDC/OAuth2) para identidad.
 
-## Repository layout
+## Estructura del repositorio
 
-A single repo: `backend/` (the six .NET projects), `web-player/` (the
+Un solo repo: `backend/` (los seis proyectos .NET), `web-player/` (cliente web
-SvelteKit web client), `deploy/` (Docker Compose stacks and scripts), and
+SvelteKit), `deploy/` (stacks de Docker Compose y scripts) y `docs/`.
-`docs/`. The shared infrastructure (Postgres, Zitadel, SeaweedFS, RabbitMQ,
-Jaeger) lives in the separate `Infrastructure` repository, a sibling of this
-one, and is not part of this layout.

docs/architecture.md

@@ -1,55 +1,55 @@
-# Architecture
+# Arquitectura
 
-## Principles
+## Principios
 
-- **Clean architecture / layers** in `backend/`: the domain and application layers don't depend on infrastructure; infrastructure implements their interfaces (`Application/Contracts`).
+- **Clean architecture / capas** en `backend/`: el dominio y la aplicación no dependen de infraestructura; la infraestructura implementa las interfaces (`Application/Contracts`).
-- **CQRS**: every operation is a `Command` or `Query` with its own handler (Mediator). Handlers return `Ardalis.Result` (Ok/NotFound/Unauthorized/Conflict/Invalid…), which the API translates into HTTP status codes.
+- **CQRS**: cada operación es un `Command` o `Query` con su handler (Mediator). Los handlers devuelven `Ardalis.Result` (Ok/NotFound/Unauthorized/Conflict/Invalid…), que la API traduce a códigos HTTP.
-- **Heavy bytes never touch the API**: uploads use presigned URLs (client → S3) and playback goes through a dedicated reverse proxy (gateway → S3). The API only moves metadata and issues permissions.
+- **Los bytes pesados no pasan por la API**: subidas con URLs prefirmadas (cliente → S3) y reproducción vía un reverse proxy dedicado (gateway → S3). La API solo mueve metadatos y emite permisos.
-- **Async processing**: creating a track doesn't transcode it on the spot. It publishes an event, and a worker does the heavy lifting, with compensation (MassTransit sagas/routing slips).
+- **Procesado asíncrono**: crear una pista no transcodifica en caliente; publica un evento y un worker hace el trabajo pesado con compensación (sagas/routing slips de MassTransit).
 
-## Components
+## Componentes
 
-| Component | Responsibility | Why it's separate |
+| Componente | Responsabilidad | Por qué separado |
 |---|---|---|
-| **Musify.Api** | REST API (users, tracks, playlists), authorizes requests, issues presigned URLs and stream tickets | A thin entry point, it doesn't process media or serve bytes |
+| **Musify.Api** | API REST (usuarios, pistas, playlists), autoriza, emite presigned URLs y stream-tickets | Punto de entrada fino; no procesa medios ni sirve bytes |
-| **Domain/Application/Infrastructure** | Domain + use cases + shared infrastructure (EF, S3, MassTransit, ffmpeg) | Logic shared between the API and the Worker |
+| **Domain/Application/Infrastructure** | Dominio + casos de uso + infraestructura compartida (EF, S3, MassTransit, ffmpeg) | Lógica reutilizada por la API y el Worker |
-| **StreamingGateway** | Reverse proxy (YARP) that validates the ticket and serves the audio (`.m4a`) from SeaweedFS | Scales with byte traffic independently of the API, and keeps SeaweedFS private behind it |
+| **StreamingGateway** | Reverse proxy (YARP) que valida el ticket y sirve el audio (`.m4a`) desde SeaweedFS | Escala con el tráfico de bytes, independiente de la API; SeaweedFS queda privado detrás |
-| **Worker** | Consumes MassTransit events: transcodes audio to `.m4a` and generates thumbnails | Keeps CPU/IO-heavy work off the HTTP request path |
+| **Worker** | Consume eventos de MassTransit: transcodifica audio a `.m4a` y genera miniaturas | Trabajo CPU/IO intensivo fuera del request HTTP |
-| **PostgreSQL** *(shared, runs in the separate `Infrastructure` repo)* | Metadata (users, tracks, playlists, upload intents) | n/a |
+| **PostgreSQL** | Metadatos (usuarios, pistas, playlists, upload intents) | — |
-| **RabbitMQ** *(shared, runs in Infrastructure)* | Event queue + transactional outbox | Decouples creation from processing |
+| **RabbitMQ** | Cola de eventos + outbox transaccional | Desacopla creación de procesado |
-| **SeaweedFS** *(shared, runs in Infrastructure)* | Object storage (S3 + filer) | Stores originals and derivatives (`.m4a` audio, thumbnails) |
+| **SeaweedFS** | Almacenamiento de objetos (S3 + filer) | Guarda originales y derivados (audio `.m4a`, miniaturas) |
-| **Zitadel** *(shared, runs in Infrastructure)* | Identity (OIDC/OAuth2) | Login and JWT issuance |
+| **Zitadel** | Identidad (OIDC/OAuth2) | Login y emisión de JWT |
 
-## Main flows
+## Flujos principales
 
-### 1. Uploading a track
+### 1. Subida de una pista
-1. The client requests `POST /tracks/upload-urls`. The API creates **UploadIntents** (reservations) and returns **presigned PUT URLs** (image + audio).
+1. Cliente pide `POST /tracks/upload-urls` → la API crea **UploadIntents** (reservas) y devuelve **URLs prefirmadas PUT** (imagen + audio).
-2. The client uploads the files **directly to SeaweedFS** using those URLs (never through the API).
+2. Cliente sube los ficheros **directo a SeaweedFS** con esas URLs (no pasan por la API).
-3. The client calls `POST /tracks` with the `intentId`s. The API validates the intents, creates the `Track` (+ `UserHasTrack`), and publishes `CreateTrackResourcesEvent`.
+3. Cliente llama `POST /tracks` con los `intentId`s → la API valida los intents, crea el `Track` (+ `UserHasTrack`) y publica `CreateTrackResourcesEvent`.
-4. The **Worker** consumes the event: moves the originals into place, generates thumbnails, transcodes the audio to `.m4a`, and updates the track's status.
+4. El **Worker** consume el evento: mueve los originales a su sitio, genera miniaturas y transcodifica el audio a `.m4a`, y actualiza el estado del track.
 
-See [media-processing.md](media-processing.md) and [storage.md](storage.md) for details.
+Ver detalle en [media-processing.md](media-processing.md) y [storage.md](storage.md).
 
-### 2. Playback (streaming)
+### 2. Reproducción (streaming)
-1. The client requests `GET /tracks/{id}/stream` (authenticated). The API authorizes it and returns `{ manifestUrl, ticket }` (a URL to the `.m4a` plus an RS256 ticket scoped to that track's folder).
+1. Cliente pide `GET /tracks/{id}/stream` (autenticado) → la API autoriza y devuelve `{ manifestUrl, ticket }` (URL al `.m4a` + ticket RS256 acotado a la carpeta de esa pista).
-2. The player opens the audio URL with `?t=<ticket>` appended (or an `X-Stream-Ticket` header) and downloads it via HTTP range requests.
+2. El reproductor abre la URL del audio añadiendo `?t=<ticket>` (o cabecera `X-Stream-Ticket`) y descarga por HTTP range.
-3. The **StreamingGateway** validates the ticket and forwards the request to the SeaweedFS filer. The bytes flow storage → client.
+3. El **StreamingGateway** valida el ticket y reenvía al filer de SeaweedFS; los bytes van storage → cliente.
 
-See [streaming.md](streaming.md).
+Ver [streaming.md](streaming.md).
 
-### 3. Authentication
+### 3. Autenticación
-1. The client logs in via OIDC against **Zitadel** and gets an access token (JWT).
+1. Cliente hace login OIDC contra **Zitadel** y obtiene un access token (JWT).
-2. Musify.Api validates the JWT's signature, issuer and audience.
+2. La Musify.Api valida la firma/iss/aud del JWT.
-3. On every validated token, the local user is **synced** (name and picture created or updated). This is just-in-time provisioning.
+3. En cada token validado, se **sincroniza** el usuario local (crea/actualiza nombre y foto) — provisioning just-in-time.
 
-See [authentication.md](authentication.md).
+Ver [authentication.md](authentication.md).
 
-## Data model (entities)
+## Modelo de datos (entidades)
 
-- **User**: `Id` is Zitadel's numeric `sub` (`long`), plus a name and `ProfilePictureUrl`.
+- **User** — `Id` es el `sub` numérico de Zitadel (`long`), más nombre y `ProfilePictureUrl`.
-- **Track**: original/derivative file names, `AudioFolderName` (the transcoded `.m4a`'s folder), processing state (`ProcessingStatus`), `LifeCycleStatus`.
+- **Track** — pista: nombres de originales/derivados, `AudioFolderName` (carpeta del `.m4a` transcodificado), estados de procesado (`ProcessingStatus`), `LifeCycleStatus`.
-- **PlayList**: a user's playlist (`UserId`).
+- **PlayList** — lista del usuario (`UserId`).
-- **PlayListHasTrack**: the tracks inside a playlist (with `Position`).
+- **PlayListHasTrack** — pistas dentro de una playlist (con `Position`).
-- **UserHasTrack**: ownership, which user owns which track.
+- **UserHasTrack** — propiedad: qué usuario posee qué pista.
-- **UploadIntent**: an upload reservation (key, bucket, expected size, status, expiration) used for validation and quota.
+- **UploadIntent** — reserva de subida (clave, bucket, tamaño esperado, estado, expiración) para validar y aplicar cuota.
-- **Upload**: a record of objects uploaded or transferred to storage.
+- **Upload** — registro de objetos subidos/transferidos al storage.

docs/authentication.md

@@ -1,40 +1,40 @@
-# Authentication and identity
+# Autenticación e identidad
 
-## Provider: Zitadel (OIDC/OAuth2)
+## Proveedor: Zitadel (OIDC/OAuth2)
 
-Login and token issuance are handled by **Zitadel**, not the API. The API is a **resource server**: it only **validates** the access token (JWT) it receives in `Authorization: Bearer`.
+El login y la emisión de tokens los hace **Zitadel** (no la API). La API es un **resource server**: solo **valida** el access token (JWT) que le llega en `Authorization: Bearer`.
 
-- Configured under the `Authentication` section (`AuthenticationConfiguration`): metadata address, issuer, audience, client id, authorize/token endpoints, scopes.
+- Config en la sección `Authentication` (`AuthenticationConfiguration`): metadata address, issuer, audience, client id, endpoints de authorize/token, scopes.
-- `JwtBearerOptionsSetup` sets up validation (issuer, audience, keys via OIDC metadata).
+- `JwtBearerOptionsSetup` configura la validación (issuer, audience, claves vía metadata OIDC).
-- In dev, `RequireHttpsMetadata = false`.
+- En dev, `RequireHttpsMetadata = false`.
 
-### Key requirement in the Zitadel app
+### Requisito clave en la app de Zitadel
-- **Auth Token Type = JWT** (otherwise Zitadel issues an **opaque** token with no dots, which `JwtBearer` can't validate → 401 on everything protected).
+- **Auth Token Type = JWT** (si no, Zitadel emite un token **opaco** sin puntos y `JwtBearer` no lo puede validar → 401 en todo lo protegido).
-- **User Info inside Token** enabled if you want the access token to carry profile claims (`name`, `email`, `picture`). By default the access token is minimal (`sub`, `aud`, `iss`, `exp`…), with no profile info.
+- **User Info inside Token** activado si quieres que el access token traiga claims de perfil (`name`, `email`, `picture`). Por defecto el access token es mínimo (`sub`, `aud`, `iss`, `exp`…), sin perfil.
 
-## `sub` is numeric → `User.Id` is `long`
+## El `sub` es numérico → `User.Id` es `long`
 
-Zitadel's `sub` is a 64-bit integer encoded as a string (e.g. `371953080444977155`), **not a GUID**. Because of that:
+El `sub` de Zitadel es un entero de 64 bits en string (p. ej. `371953080444977155`), **no un GUID**. Por eso:
-- `User.Id` and every user-related FK (`PlayList.UserId`, `UserHasTrack.UserId`, `UploadIntent.UserId`) are **`long`**.
+- `User.Id` y todas las FKs de usuario (`PlayList.UserId`, `UserHasTrack.UserId`, `UploadIntent.UserId`) son **`long`**.
-- `User.Id` has `[DatabaseGenerated(None)]` so EF doesn't autogenerate it: it's assigned from the `sub`.
+- `User.Id` lleva `[DatabaseGenerated(None)]` para que EF **no** lo autogenere: se asigna el `sub`.
-- `CurrentUser.Id` is `long?` (parsed with `long.TryParse`); `RequiredId` throws if it's missing.
+- `CurrentUser.Id` es `long?` (parsea con `long.TryParse`); `RequiredId` lanza si falta.
 
-**Why**: the original code did `Guid.Parse(sub)`, which threw a `FormatException` → 401 on every protected endpoint. The fix was to store the `sub` as-is, as a number.
+**Por qué**: el código antiguo hacía `Guid.Parse(sub)` y reventaba (FormatException) → 401 en cada endpoint protegido. Se decidió guardar el `sub` tal cual como número.
 
-## User provisioning / sync
+## Provisioning / sincronización de usuarios
 
-On every validated token, `JwtBearerEventsHandler.TokenValidated`:
+En cada token validado, `JwtBearerEventsHandler.TokenValidated`:
-1. Reads `sub` (id), `name`/`preferred_username`/`email` (with fallback), and the OIDC `picture` claim.
+1. Lee `sub` (id), `name`/`preferred_username`/`email` (con fallback) y el claim OIDC `picture`.
-2. Sends a `SyncUserCommand`.
+2. Envía un `SyncUserCommand`.
 
-`SyncUserCommandHandler` does an **idempotent upsert**:
+`SyncUserCommandHandler` hace un **upsert idempotente**:
-- If the user doesn't exist yet → creates it.
+- Si el usuario no existe → lo crea.
-- If it exists → updates the name and `ProfilePictureUrl` **only if they changed** (a DB write only happens when something is different).
+- Si existe → actualiza nombre/apellidos/`ProfilePictureUrl` **solo si cambiaron** (escribe en DB únicamente cuando hay cambios).
 
-**Why "write only if changed"**: `TokenValidated` runs on **every request**; without that guard we'd be writing to the DB on every single call. It also needs to be resilient: if provisioning fails, it's logged but authentication **doesn't** fail because of it.
+**Por qué upsert con "escribe solo si cambió"**: `TokenValidated` se ejecuta en **cada request**; sin ese guardado condicional estaríamos escribiendo en cada petición. Y debe ser resiliente: si el provisioning falla, se loguea pero **no** tumba la autenticación.
 
-> Note: `CreateUserCommand` (the manual `POST /users` endpoint) is still create-only; login sync uses `SyncUserCommand`.
+> Nota: `CreateUserCommand` (endpoint manual `POST /users`) sigue siendo create-only; el sync del login usa `SyncUserCommand`.
 
-## Profile picture
+## Foto de perfil
 
-`User.ProfilePictureUrl` is filled from the token's `picture` claim. If Zitadel doesn't include profile info in the access token (see above), it arrives as `null`. The code is correct, there's just nothing to sync until that option is turned on.
+`User.ProfilePictureUrl` se rellena desde el claim `picture` del token. Si Zitadel no mete la info de perfil en el access token (ver arriba), llega `null` — el código es correcto, pero no hay nada que sincronizar hasta activar esa opción.

docs/development.md

@@ -1,25 +1,21 @@
-# Development environment
+# Entorno de desarrollo
 
-How to run everything locally and test it. The full deployment details (dev
+Cómo levantar todo en local y probarlo. El detalle completo del deploy (y el de
-and prod) live in [deploy/README.md](../deploy/README.md).
+producción) está en [deploy/README.md](../deploy/README.md).
 
-## Startup
+## Arranque
-
-Bring up the separate `Infrastructure` repository first (Postgres, Zitadel,
-SeaweedFS, RabbitMQ, Jaeger, see its own README for the exact command), then:
 
 ```sh
 docker compose -f deploy/compose.yml -f deploy/compose.dev.yml up -d
 ```
 
-That runs Musify's own one-shot bootstrap jobs: it generates the RS256
+Ese único comando levanta la infraestructura y corre los jobs *one-shot* de
-stream-ticket keys in `deploy/keys/`, applies the EF Core migrations, creates
+bootstrap: genera las claves RS256 de stream-ticket en `deploy/keys/`, aplica
-Musify's storage bucket, and provisions Zitadel (project + OIDC apps),
+las migraciones EF Core y provisiona Zitadel (proyecto + apps OIDC), dejando
-writing the client ids into `deploy/.env`. Full details, including how to run
+los client ids en `deploy/.env`. Detalle completo, incluido cómo arrancar las
-the apps in Docker with `--profile apps`, are in
+apps en Docker con `--profile apps`, en [deploy/README.md](../deploy/README.md).
-[deploy/README.md](../deploy/README.md).
 
-## Applications
+## Aplicaciones
 
 ```powershell
 dotnet run --project backend/Hosts/Musify.Api               # :5111
@@ -28,45 +24,45 @@ dotnet run --project backend/Hosts/Musify.Worker            # background
 npm --prefix web-player run dev                       # :5173
 ```
 
-## Port map
+## Mapa de puertos
 
-| Service | Port |
+| Servicio | Puerto |
 |---|---|
 | Musify.Api | 5111 (`/scalar/v1`, `/openapi/v1.json`) |
 | Musify.StreamingGateway | 8081 (`/health`, `/media/...`) |
-| web-player | 5173 (`npm run dev`) or 3000 (container) |
+| web-player | 5173 (`npm run dev`) o 3000 (contenedor) |
+| SeaweedFS S3 / filer / master | 8333 / 8888 / 9333 |
+| Zitadel | 8080 |
+| PostgreSQL | 59000 (→ 5432 en el contenedor) |
+| RabbitMQ AMQP / management | 5672 / 15672 |
+| Jaeger UI / OTLP | 16686 / 4317 |
+| pgAdmin (`-Tools`) | 5050 |
 
-Postgres, Zitadel, SeaweedFS, RabbitMQ and Jaeger are not run by this repo.
+DB: `musify_db`, usuario `postgres`/`postgres`. Bucket S3: `webapi-storage`
-Their ports are documented in the separate `Infrastructure` repository's own
+(credenciales `admin_access_key`/`admin_secret_key`). Todos los valores salen de
-README.
+`deploy/.env`.
 
-DB: `musify_db`, user `postgres`/`postgres` on Infrastructure's shared
+## Migraciones
-Postgres. S3 bucket: `webapi-storage` (credentials
-`admin_access_key`/`admin_secret_key`, also Infrastructure's). All of these
-come from `deploy/.env`.
 
-## Migrations
+El servicio `migrate` de `deploy/compose.yml` las aplica en cada `docker
-
+compose up -d` (no-op si el esquema ya está al día). A mano, tras cambios de
-The `migrate` service in `deploy/compose.yml` applies them on every `docker
+esquema, contra la base local:
-compose up -d` (a no-op if the schema is already current). To run them by
-hand after a schema change, against the local database:
 
 ```powershell
 dotnet ef database update --project backend/Core/Musify.Infrastructure --startup-project backend/Core/Musify.Infrastructure --context Database
 ```
 
-`Musify.Infrastructure` is both the migrations project and the startup
+`Musify.Infrastructure` es a la vez el proyecto de migraciones y el de arranque:
-project: it has the `IDesignTimeDbContextFactory` and the `EFCore.Design`
+tiene el `IDesignTimeDbContextFactory` y el paquete `EFCore.Design`. La cadena
-package. The connection string is read from its user-secrets, or from the
+de conexión se lee de sus user-secrets, o de la variable de entorno
-`Database__ConnectionString` environment variable if there are no
+`Database__ConnectionString` si no hay user-secrets (así es como la usa el
-user-secrets (which is how the `migrate` container uses it, see
+contenedor `migrate`, ver `backend/Musify.Migrator.Dockerfile`).
-`backend/Musify.Migrator.Dockerfile`).
 
-## Stream tickets (RS256 keys)
+## Stream-tickets (claves RS256)
 
-The API signs stream tickets with the private key, and the gateway validates
+La API firma los stream-tickets con la clave privada y el gateway los valida con
-them with the public one. The `keys-init` service in `deploy/compose.yml`
+la pública. El servicio `keys-init` de `deploy/compose.yml` las genera en
-generates them in `deploy/keys/` if they don't exist yet; to do it by hand:
+`deploy/keys/` si no existen; a mano:
 
 ```powershell
 openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out deploy/keys/stream_private.pem
@@ -82,74 +78,74 @@ openssl rsa -in deploy/keys/stream_private.pem -pubout -out deploy/keys/stream_p
 dotnet test backend/Musify.slnx
 ```
 
-`backend/Tests/` (the `/Tests/` folder in the `.slnx`) has five xUnit projects:
+`backend/Tests/` (carpeta `/Tests/` en el `.slnx`) tiene cinco proyectos xUnit:
 
-| Project | Covers | Docker |
+| Proyecto | Cubre | Docker |
 |---|---|---|
-| `Musify.Domain.Tests` | Value object logic (`TrackAudio`/`TrackPictures`: `IsProcessed`, `IsFailed`, `IsInProgress`). Entities are mostly anemic, with no behavior of their own beyond that. | No |
+| `Musify.Domain.Tests` | Lógica de los value objects (`TrackAudio`/`TrackPictures`: `IsProcessed`, `IsFailed`, `IsInProgress`). Las entidades son en su mayoría anémicas — sin comportamiento propio, nada más que testear ahí. | No |
-| `Musify.Application.Tests` | The ~45 handlers and services in `Musify.Application` (Albums, Tracks, PlayLists, Users, Mixes). | No |
+| `Musify.Application.Tests` | Los ~45 handlers y servicios de `Musify.Application` (Albums, Tracks, PlayLists, Users, Mixes). | No |
-| `Musify.Infrastructure.Tests` | `Database`/migrations, `StorageService`, `StreamTicketService`, `AuditableEntityInterceptor`, `PictureService`, `SingleFlightCache`, `PlayListPresetSeeder`. | **Yes** |
+| `Musify.Infrastructure.Tests` | `Database`/migraciones, `StorageService`, `StreamTicketService`, `AuditableEntityInterceptor`, `PictureService`, `SingleFlightCache`, `PlayListPresetSeeder`. | **Sí** |
-| `Musify.Api.Tests` | Real HTTP endpoints (routing, auth, `ValidationFilter`, `ErrorOr`→HTTP mapping) via `WebApplicationFactory`, plus `ErrorOrHttpExtensions`/`CurrentUser`/FluentValidation validators in isolation. | **Yes** |
+| `Musify.Api.Tests` | Endpoints HTTP reales (routing, auth, `ValidationFilter`, mapeo `ErrorOr`→HTTP) vía `WebApplicationFactory`, más `ErrorOrHttpExtensions`/`CurrentUser`/validators FluentValidation en aislado. | **Sí** |
-| `Musify.StreamingGateway.Tests` | `TicketValidator` (RS256) and `TicketValidationMiddleware` (traversal, prefix limits, ticket extraction). | No |
+| `Musify.StreamingGateway.Tests` | `TicketValidator` (RS256) y `TicketValidationMiddleware` (traversal, límites de prefijo, extracción de ticket). | No |
 
-`Musify.Worker` has no test project: its `Program.cs` is pure DI/host wiring
+`Musify.Worker` no tiene proyecto de test: su `Program.cs` es puro *wiring* de
-(Hangfire, MassTransit, jobs). The actual logic it runs lives in
+DI/host (Hangfire, MassTransit, jobs) — la lógica real que ejecuta vive en
-`Musify.Infrastructure`, already covered there.
+`Musify.Infrastructure`, ya cubierta ahí.
 
-### Application.Tests: why in-memory SQLite instead of mocks
+### Application.Tests: por qué SQLite en memoria y no mocks
 
-`IDatabase` exposes `DbSet<T>` directly, so handlers build real LINQ
+`IDatabase` expone `DbSet<T>` directamente, así que los handlers arman LINQ
-(`Where`, `Include`, `Select`...) against it. That can't be mocked with
+real (`Where`, `Include`, `Select`...) contra él — no se puede mockear eso con
-NSubstitute, since there's no `IQueryable` behind a mock. Instead,
+NSubstitute, no hay `IQueryable` detrás de un mock. En su lugar,
-`TestSupport/TestDatabase.cs` is a real `DbContext` on top of in-memory
+`TestSupport/TestDatabase.cs` es un `DbContext` real sobre SQLite en memoria
-SQLite (a fresh `:memory:` connection per test, with real foreign keys,
+(una conexión `:memory:` nueva por test, con foreign keys reales — a diferencia
-unlike EF Core's InMemory provider, SQLite also supports transactions,
+del proveedor InMemory de EF Core, SQLite además soporta transacciones, que dos
-which two handlers rely on). `TestSupport/TestEntities.cs` and
+handlers usan). `TestSupport/TestEntities.cs` y `TestConfigurations.cs`
-`TestConfigurations.cs` build entities and configuration with sensible
+construyen entidades y configuración con valores por defecto sensatos.
-defaults. `IStorageService`, `IEventBus`, etc. are mocked with NSubstitute,
+`IStorageService`, `IEventBus`, etc. sí se mockean con NSubstitute, al ser
-since those are plain interfaces.
+interfaces normales.
 
-### Infrastructure.Tests and Api.Tests: Testcontainers
+### Infrastructure.Tests y Api.Tests: Testcontainers
 
-These two need Docker running. They spin up a real Postgres
+Estos dos sí necesitan Docker corriendo. Levantan un Postgres real
-(`Testcontainers.PostgreSql`) and, in `Infrastructure.Tests`, a real
+(`Testcontainers.PostgreSql`) y, en `Infrastructure.Tests`, también un
-SeaweedFS too (the same `chrislusf/seaweedfs:latest` image/command as
+SeaweedFS real (mismo `chrislusf/seaweedfs:latest` e imagen/comando que
-`deploy/compose.yml`, not MinIO), so `StorageService` is tested against the
+`deploy/compose.yml`, no MinIO) — así `StorageService` se prueba contra el
-same S3-compatible backend production uses, not against AWS S3. Containers
+mismo backend S3-compatible que usa producción, no contra AWS S3. Los
-are started once per run (`ICollectionFixture`), with real EF Core
+contenedores se levantan una vez por corrida (`ICollectionFixture`), con
-migrations applied against the ephemeral Postgres.
+migraciones EF Core reales aplicadas contra el Postgres efímero.
 
-`Api.Tests` uses `WebApplicationFactory<Program>` against that same
+`Api.Tests` usa `WebApplicationFactory<Program>` contra ese mismo Postgres —
-Postgres, with real routing, auth, and validation, but replaces the services
+routing, auth y validación reales — pero sustituye por fakes los servicios que
-that talk over the network with fakes (`IStorageService`, `IEventBus`,
+hablan por red (`IStorageService`, `IEventBus`, `IStreamTicketService`) y el
-`IStreamTicketService`), and swaps the real JWT auth scheme for a test
+esquema de autenticación JWT real por un handler
-handler (see `TestSupport/FakeAuthenticationHandler.cs`) that authenticates
+de prueba (ver `TestSupport/FakeAuthenticationHandler.cs`) que autentica según
-based on a header, with no real Zitadel needed.
+un header, sin necesitar un Zitadel real.
 
-Writing these tests against the real backend found and fixed two actual
+Escribir estos tests contra el backend real encontró y arregló dos bugs reales
-bugs (not staged ones): `StorageService.RemoveFolderAsync` threw a
+(no simulados): `StorageService.RemoveFolderAsync` reventaba con
-`NullReferenceException` against SeaweedFS (its `DeleteObjects` response
+`NullReferenceException` contra SeaweedFS (su respuesta `DeleteObjects` omite
-omits the `<Error>` list when there are no errors, unlike AWS S3), and
+la lista `<Error>` cuando no hay errores, a diferencia de AWS S3), y
-`AuditableEntityInterceptor` never updated `UpdatedAt` on a normal update
+`AuditableEntityInterceptor` nunca actualizaba `UpdatedAt` en una actualización
-(load → modify → save) because it ran before EF had detected the pending
+normal (carga → modifica → guarda) porque corría antes de que EF detectara los
-changes.
+cambios pendientes.
 
 ## Config (AppSettings)
 
-Convention: `AppSettings.json` is the template, with empty or neutral
+Convención: `AppSettings.json` es la plantilla con valores vacíos o neutros;
-values; `AppSettings.Development.json` has the real dev values; in Docker
+`AppSettings.Development.json` tiene los valores reales de dev; en Docker todo
-everything is overridden with environment variables (`Section__Key`) from
+se sobreescribe con variables de entorno (`Seccion__Clave`) desde
-`deploy/compose.yml`. To run `Musify.Api` from the IDE, the `Authentication`
+`deploy/compose.yml`. Para correr `Musify.Api` desde el IDE, los valores de
-values go into user-secrets (not the repo). Copy them from `deploy/.env`
+`Authentication` van en user-secrets (no en el repo) — cópialos de
-once `zitadel-init` has generated them (see
+`deploy/.env` una vez que `zitadel-init` los haya generado (ver
 [deploy/README.md](../deploy/README.md)).
 
-Key sections: `Authentication` (Zitadel), `Database`, `MassTransit`,
+Secciones clave: `Authentication` (Zitadel), `Database`, `MassTransit`,
 `InfrastructureStorage` (S3), `ApplicationStorage` (bucket), `Track`, `PlayList`,
 `UploadIntent`, `AudioTranscoder`, `Workers`, `StreamGateway` / `StreamTicket`.
 
-## Host requirements
+## Requisitos del host
 
-- .NET 10 SDK and Node 22.
+- .NET 10 SDK y Node 22.
-- **ffmpeg** on the PATH (for the Worker's audio transcoding).
+- **ffmpeg** en el PATH (transcode de audio del Worker).
 - Docker Desktop.

docs/media-processing.md

@@ -1,46 +1,46 @@
-# Media processing (Worker + MassTransit)
+# Procesado de medios (Worker + MassTransit)
 
-Heavy processing (audio transcoding, thumbnails, bucket transfers) happens **outside the HTTP request**, in the **Worker**, orchestrated with **MassTransit** on top of RabbitMQ.
+El procesado pesado (transcode de audio, miniaturas, transferencias en el bucket) ocurre **fuera del request HTTP**, en el **Worker**, orquestado con **MassTransit** sobre RabbitMQ.
 
-## Why async, and why routing slips
+## Por qué asíncrono y con routing slips
 
-- Transcoding audio and resizing images is CPU/IO-intensive: it shouldn't block an API call.
+- Transcodificar audio y redimensionar imágenes es CPU/IO intensivo: no debe bloquear una llamada a la API.
-- It's a **multi-step process with side effects** (download from S3 → transcode → upload results → update the DB). If a step fails, the previous ones need to be **undone**. That's what **routing slips** are for (MassTransit's Saga pattern): each step is an *activity* with its own **compensation**.
+- Es un proceso **multi-paso con efectos secundarios** (descargar de S3 → transcodificar → subir resultados → actualizar DB). Si un paso falla, hay que **deshacer** los anteriores. Para eso se usan **routing slips** (patrón Saga de MassTransit): cada paso es una *activity* con su **compensación**.
-- **Transactional outbox** (EF + MassTransit): the event is published consistently with the DB change (never lost, never duplicated).
+- **Outbox transaccional** (EF + MassTransit): el evento se publica de forma consistente con el cambio en la DB (no se pierde ni se duplica).
 
-## Trigger
+## Disparo
 
-When a track or playlist is created or updated, the handler publishes an event (e.g. `CreateTrackResourcesEvent`). A **consumer** (`CreateTrackConsumer`, `UpdateTrackPictureConsumer`, …) builds a **routing slip** with the sequence of activities and executes it.
+Al crear/actualizar una pista o playlist, el handler publica un evento (p. ej. `CreateTrackResourcesEvent`). Un **consumer** (`CreateTrackConsumer`, `UpdateTrackPictureConsumer`, …) construye un **routing slip** con la secuencia de activities y lo lanza.
 
-## Routing slip builders
+## Builders de routing slip
 
-- `CreateTrackRoutingSlipBuilder`: creating a track (consumes intents, moves files, kicks off processing).
+- `CreateTrackRoutingSlipBuilder` — alta de pista (consume intents, mueve ficheros, dispara procesado).
-- `PictureWorkflowRoutingSlipBuilder`: image pipeline (download → resize → upload → update).
+- `PictureWorkflowRoutingSlipBuilder` — pipeline de imágenes (descargar → redimensionar → subir → actualizar).
-- `AudioWorkflowRoutingSlipBuilder`: audio pipeline (download → transcode to `.m4a` → upload folder → update).
+- `AudioWorkflowRoutingSlipBuilder` — pipeline de audio (descargar → transcodificar a `.m4a` → subir carpeta → actualizar).
 - `DeleteTrackRoutingSlipBuilder`, `DeletePlayListRoutingSlipBuilder`, `PlayListPictureSourceRoutingSlipBuilder`.
 
-## Activities (steps)
+## Activities (pasos)
 
-Grouped by area:
+Agrupadas por área:
 - **Files**: `DownloadFileFromBucketActivity`, `UploadFileToBucketActivity`, `TransferFilesToBucketActivity`, `CopyFileInBucketActivity`, `RemoveFileFromBucketActivity`.
-- **Audio**: `GenerateAudioWorkflowPathsActivity`, `TranscodeAudioActivity` (ffmpeg → `.m4a`), `UpdateTrackAudioActivity` (saves `AudioFolderName` and marks it `Completed`).
+- **Audio**: `GenerateAudioWorkflowPathsActivity`, `TranscodeAudioActivity` (ffmpeg → `.m4a`), `UpdateTrackAudioActivity` (guarda `AudioFolderName` y marca `Completed`).
 - **Pictures**: `GeneratePictureWorkflowPathsActivity`, `ResizePictureActivity` (ImageSharp), `UpdateTrackPictureActivity`, `UpdatePlayListPictureActivity`.
-- **Tracks/Playlists**: `MarkTrackAsRemovingActivity`, `DeleteTrackFromDbActivity`, `PublishTrackProcessingEventsActivity`, and their playlist equivalents.
+- **Tracks/PlayLists**: `MarkTrackAsRemovingActivity`, `DeleteTrackFromDbActivity`, `PublishTrackProcessingEventsActivity`, y equivalentes de playlist.
 - **UploadIntents**: `ConsumeUploadIntentsActivity`.
 
-`RoutingSlipCleanUpConsumer` reacts to `Completed`/`Faulted` to clean up (e.g. deleting the temporary working directory).
+`RoutingSlipCleanUpConsumer` reacciona a `Completed`/`Faulted` para limpiar (p. ej. borrar el directorio temporal de trabajo).
 
-## Audio transcoding
+## Transcode de audio
 
-`AudioTranscoderService` calls **ffmpeg**, reading the original from stdin and producing a single `audio.m4a` in a working directory: AAC with a configurable codec/bitrate/sample-rate/profile, and `-movflags +faststart` (moov at the start, so range-based seeking works). `TransferFilesToBucketActivity` then uploads that folder to `Tracks/ProcessedAudios/{folder}/`, and `UpdateTrackAudioActivity` saves the `AudioFolderName` (the **destination folder in S3**, not the local one) and sets the status to `Completed`.
+`AudioTranscoderService` invoca **ffmpeg** leyendo el original por stdin y produciendo en un directorio de trabajo un único `audio.m4a`: AAC con codec/bitrate/sample-rate/profile configurables y `-movflags +faststart` (moov al inicio → seek por range). Luego `TransferFilesToBucketActivity` sube esa carpeta a `Tracks/ProcessedAudios/{folder}/` y `UpdateTrackAudioActivity` guarda el `AudioFolderName` (la carpeta **de destino en S3**, no la local) y pone el estado en `Completed`.
 
-## What the Worker needs configured
+## Configuración que necesita el Worker
 
-The Worker registers: storage (S3), transcoder (ffmpeg), pictures, the DB, the MassTransit consumers, and the upload-intent jobs. Its `AppSettings` needs the right sections: `Bucket` (= `webapi-storage`, same as the API), `PlayList`, `Track`, `MassTransit`, `AudioTranscoder`, `UploadIntent`, `Workers` (temp directory), `InfrastructureStorage`, `Database`.
+El Worker registra: storage (S3), transcoder (ffmpeg), pictures, DB, los consumers de MassTransit y los jobs de upload intents. Su `AppSettings` debe tener las secciones correctas: `Bucket` (= `webapi-storage`, el mismo que la API), `PlayList`, `Track`, `MassTransit`, `AudioTranscoder`, `UploadIntent`, `Workers` (directorio temporal), `InfrastructureStorage`, `Database`.
 
-## Background jobs
+## Jobs de fondo
 
-- `UploadIntentExpirationJob`: marks expired intents as such (freeing quota) every `ExpirationJobIntervalSeconds`.
+- `UploadIntentExpirationJob` — marca intents caducados como expirados (libera cuota) cada `ExpirationJobIntervalSeconds`.
-- `TemporalUploadsCleanUpJob`: cleans up old temporary uploads.
+- `TemporalUploadsCleanUpJob` — limpia subidas temporales antiguas.
 
-Both run on the Worker host (`AddUploadIntentJobs`). If they aren't registered anywhere, stale intents never get cleaned up on their own.
+Corren en el host del Worker (`AddUploadIntentJobs`). Si no se registran en ningún proceso, los intents colgados no se limpian solos.

docs/projects.md

@@ -1,76 +1,74 @@
-# Projects
+# Proyectos
 
-The .NET projects live under `backend/` (solution `Musify.slnx`, folders
+Los proyectos .NET viven en `backend/` (solución `Musify.slnx`, carpetas
-`Core/`, `Hosts/` and `Tests/`); the web client lives under `web-player/`.
+`Core/`, `Hosts/` y `Tests/`); el cliente web en `web-player/`.
 
 ## Musify.Api  (`:5111`)
 
-The public REST API (Minimal APIs, .NET 10). The thin public face of the system.
+API REST pública (Minimal APIs, .NET 10). Es la fachada fina del sistema.
 
 - **Endpoints**: `UserEndpoints`, `TrackEndpoints`, `PlayListEndpoints`.
-- **Authentication**: JWT Bearer against Zitadel (`Authentication/`), with a `JwtBearerEventsHandler` that syncs the user on every validated token.
+- **Autenticación**: JWT Bearer contra Zitadel (`Authentication/`), con `JwtBearerEventsHandler` que sincroniza el usuario en cada token validado.
-- **`CurrentUser`**: an abstraction bound as an endpoint parameter (`IBindableFromHttpContext`) that exposes the basic claims (`Id` as `long?`, `RequiredId`, name, etc.) without reading `ClaimsPrincipal` by hand.
+- **`CurrentUser`**: abstracción que se enlaza como parámetro de endpoint (`IBindableFromHttpContext`) y expone los claims básicos (`Id` como `long?`, `RequiredId`, nombre, etc.) sin tener que leer `ClaimsPrincipal` a mano.
-- **Issues**: presigned upload URLs (via `IStorageService`) and **stream tickets** (via `IStreamTicketService`, RS256).
+- **Emite**: presigned URLs de subida (vía `IStorageService`) y **stream-tickets** (vía `IStreamTicketService`, RS256).
-- **OpenAPI + Scalar** for docs/testing; OAuth2 (PKCE) set up for logging in from Scalar.
+- **OpenAPI + Scalar** para documentación/prueba; OAuth2 (PKCE) configurado para login desde Scalar.
-- **CORS** wide open, but **only in Development** (for the local frontend).
+- **CORS** totalmente abierto **solo en Development** (para el front local).
-- Translates `ErrorOr` into HTTP in `ResultHttpExtensions`.
+- Traduce `ErrorOr` → HTTP en `ResultHttpExtensions`.
 
-**Purpose**: keep the public surface (authorization + metadata) separate from processing and byte-serving.
+**Propósito/porqué**: separar la cara pública (autorización + metadatos) del procesado y del servido de bytes.
 
 ## Musify.Domain + Musify.Application + Musify.Infrastructure
 
-The core, split into three projects (clean architecture):
+El núcleo, en tres proyectos (clean architecture):
 
 ### Domain
-Entities (`Entities/`) and value objects/enums (`ValueObjects/`: `ProcessingStatus`, `LifeCycleStatus`, `UploadIntentStatus`, …). No infrastructure dependencies.
+Entidades (`Entities/`) y value objects/enums (`ValueObjects/`: `ProcessingStatus`, `LifeCycleStatus`, `UploadIntentStatus`, …). Sin dependencias de infraestructura.
 
 ### Application
-Use cases (CQRS with Mediator):
+Casos de uso (CQRS con Mediator):
 - `Tracks/`, `PlayLists/`, `Users/` → `Commands`, `Queries`, `Handlers`, `Responses`.
-- `Contracts/` → interfaces that infrastructure implements (`IDatabase`, `IStorageService`, `IAudioTranscoderService`, `IPictureService`, `IEventBus`, `IStreamTicketService`).
+- `Contracts/` → interfaces que implementa la infraestructura (`IDatabase`, `IStorageService`, `IAudioTranscoderService`, `IPictureService`, `IEventBus`, `IStreamTicketService`).
-- `Configuration/` → typed options (Track, PlayList, ApplicationStorage, UploadIntent…) bound and validated at startup.
+- `Configuration/` → opciones tipadas (Track, PlayList, ApplicationStorage, UploadIntent…) bindeadas y validadas al arranque.
-- `Shared/` → cross-cutting helpers (`StorageKey.Combine`, `ImageSize`).
+- `Shared/` → helpers transversales (`StorageKey.Combine`, `ImageSize`).
 - `Pagination/` → `PaginatedResponse<T>`.
 
-**Why**: business logic doesn't know about EF, S3, or RabbitMQ, only interfaces. Shared by both the API and the Worker.
+**Porqué**: la lógica de negocio no conoce EF, S3 ni RabbitMQ; solo interfaces. Reutilizable por la API y el Worker.
 
 ### Infrastructure
-Concrete implementations:
+Implementaciones concretas:
-- `Persistence/` → `Database` (EF Core/Npgsql), migrations.
+- `Persistence/` → `Database` (EF Core/Npgsql), migraciones.
-- `Services/` → `StorageService` (AWSSDK.S3 against SeaweedFS), `AudioTranscoderService` (ffmpeg → `.m4a`), `PictureService` (ImageSharp), `StreamTicketService` (RS256 signing).
+- `Services/` → `StorageService` (AWSSDK.S3 contra SeaweedFS), `AudioTranscoderService` (ffmpeg → `.m4a`), `PictureService` (ImageSharp), `StreamTicketService` (firma RS256).
-- `MassTransit/` → consumers, activities, and routing slips (see [media-processing.md](media-processing.md)).
+- `MassTransit/` → consumers, activities y routing slips (ver [media-processing.md](media-processing.md)).
 - `Jobs/` → `UploadIntentExpirationJob`, `TemporalUploadsCleanUpJob`.
 
 ## Musify.StreamingGateway  (`:8081`)
 
-A reverse proxy (ASP.NET + **YARP**) that serves audio (`.m4a`) from SeaweedFS. Validates the stream ticket (RS256, public key) and, if the requested object falls under the authorized prefix, forwards it to the filer.
+Reverse proxy (ASP.NET + **YARP**) que sirve el audio (`.m4a`) desde SeaweedFS. Valida el stream-ticket (RS256, clave pública) y, si el objeto pedido cae bajo el prefijo autorizado, reenvía al filer.
 
-**Why a separate project**: it scales with byte traffic independently of the API, has a minimal surface (it only knows how to validate a JWT and proxy), and lets SeaweedFS stay on a private network. See [streaming.md](streaming.md).
+**Porqué un proyecto aparte**: escala con el tráfico de bytes independientemente de la API, tiene superficie mínima (solo sabe validar un JWT y proxiar) y permite que SeaweedFS quede en red privada. Ver [streaming.md](streaming.md).
 
 ## Musify.Worker
 
-A background Worker Service that consumes MassTransit events and runs the heavy processing: audio transcoding to `.m4a` (ffmpeg), thumbnail generation (ImageSharp), file transfers within the bucket, and the upload-intent expiration/cleanup jobs.
+Worker Service (host de fondo) que consume los eventos de MassTransit y ejecuta el procesado pesado: transcode de audio a `.m4a` (ffmpeg), generación de miniaturas (ImageSharp), transferencias de ficheros en el bucket, y los jobs de expiración/limpieza de upload intents.
 
-**Why separate**: CPU/IO-heavy work shouldn't happen inside an HTTP request; it scales and restarts independently. (Previously named `Musify.PictureWorker`; renamed once it started doing more than just images.)
+**Porqué aparte**: el trabajo CPU/IO no debe ocurrir dentro de un request HTTP; se escala y reinicia por separado. (Antes se llamaba `Musify.PictureWorker`; se renombró porque hace más que imágenes.)
 
-## web-player  (`:5173` in dev, `:3000` in a container)
+## web-player  (`:5173` en dev, `:3000` en contenedor)
 
-The web client (SvelteKit 2 + Svelte 5 + Tailwind 4). The OIDC session lives
+Cliente web (SvelteKit 2 + Svelte 5 + Tailwind 4). La sesión OIDC vive en el
-on the server (an encrypted cookie); backend calls go out from the server
+servidor (cookie cifrada); las llamadas al backend salen del servidor con el
-with the access token, and uploads go straight to the presigned S3 URLs.
+access token, y las subidas se hacen contra las URLs prefirmadas de S3.
 
 ## Tests
 
-`backend/Tests/` (the `/Tests/` folder in the `.slnx`) has five xUnit projects:
+`backend/Tests/`, carpeta `/Tests/` en el `.slnx`: cinco proyectos xUnit —
-`Musify.Domain.Tests`, `Musify.Application.Tests` (in-memory SQLite, no
+`Musify.Domain.Tests`, `Musify.Application.Tests` (SQLite en memoria, sin
-Docker), `Musify.Infrastructure.Tests` and `Musify.Api.Tests` (Testcontainers:
+Docker), `Musify.Infrastructure.Tests` y `Musify.Api.Tests` (Testcontainers:
-real Postgres + SeaweedFS), and `Musify.StreamingGateway.Tests`. Details in
+Postgres + SeaweedFS reales) y `Musify.StreamingGateway.Tests`. Detalle en
 [development.md](development.md#tests).
 
-## Other folders
+## Otras carpetas
 
-- **`deploy/`**: Musify's own Docker Compose stacks (dev and prod). The
+- **`deploy/`** — stacks de Docker Compose (dev y prod), autocontenidos. Ver
-  shared infrastructure (Postgres, Zitadel, SeaweedFS, RabbitMQ, Jaeger)
-  lives in the separate `Infrastructure` repo instead. See
   [../deploy/README.md](../deploy/README.md).
-- **`docs/`**: this documentation.
+- **`docs/`** — esta documentación.

docs/storage.md

@@ -1,48 +1,48 @@
-# Storage (SeaweedFS / S3)
+# Almacenamiento (SeaweedFS / S3)
 
-## What it is
+## Qué es
 
-**SeaweedFS** is the object store, S3-API compatible. It holds the uploaded originals and their derivatives (`.m4a` audio, thumbnails). Accessed via `AWSSDK.S3` from `StorageService` (`IStorageService`).
+**SeaweedFS** es el almacén de objetos, compatible con la API S3. Guarda los originales subidos y los derivados (audio `.m4a`, miniaturas). Se accede vía `AWSSDK.S3` desde `StorageService` (`IStorageService`).
 
-It exposes:
+Expone:
-- **S3 API** (`:8333`): S3 operations (presigned URLs, put/get/list…).
+- **S3 API** (`:8333`) — operaciones S3 (presigned URLs, put/get/list…).
-- **filer HTTP** (`:8888`): serves files by path, used by the **StreamingGateway**.
+- **filer HTTP** (`:8888`) — sirve los ficheros por ruta; lo usa el **StreamingGateway**.
-- master (`:9333`) and volume server, internal only.
+- master (`:9333`) y volume server — internos.
 
-App bucket: **`webapi-storage`** (`ApplicationStorage:Bucket`). Important: the API and the Worker use **the same bucket** (the worker processes whatever the API uploads).
+Bucket de la app: **`webapi-storage`** (`ApplicationStorage:Bucket`). Importante: la API y el Worker usan **el mismo bucket** (el worker procesa lo que sube la API).
 
-## Key layout
+## Estructura de claves (layout)
 
-- `temp/{userId}/Tracks/{guid}.{ext}`: temporary uploads, the target of presigned PUTs, before the intent is consumed.
+- `temp/{userId}/Tracks/{guid}.{ext}` — subidas temporales (objetivo de las presigned PUT, antes de consumir el intent).
-- `uploads/{userId}/Tracks/OriginalPictures|OriginalAudios/...`: originals that have already been consumed.
+- `uploads/{userId}/Tracks/OriginalPictures|OriginalAudios/...` — originales ya consumidos.
-- `Tracks/SmallPictures|MediumPictures|LargePictures/...`: generated thumbnails.
+- `Tracks/SmallPictures|MediumPictures|LargePictures/...` — miniaturas generadas.
-- `Tracks/ProcessedAudios/{AudioFolderName}/`: transcoded audio (`audio.m4a`, AAC with faststart).
+- `Tracks/ProcessedAudios/{AudioFolderName}/` — audio transcodificado (`audio.m4a`, AAC con faststart).
 
-Keys are always built with the `StorageKey.Combine(...)` helper (in `Application/Shared`), which joins segments with `/` and trims stray spaces and slashes. It's centralized to keep the logic consistent and avoid repeating it.
+Las claves se construyen **siempre** con el helper `StorageKey.Combine(...)` (en `Application/Shared`), que une segmentos con `/` limpiando espacios y barras. Está centralizado para estandarizar y no repetir lógica.
 
-> In the filer, S3 objects live under `/buckets/{bucket}/{key}`, which is why the gateway rewrites `/media/{key}` → `/buckets/webapi-storage/{key}`.
+> En el filer, los objetos S3 viven bajo `/buckets/{bucket}/{key}` — de ahí que el gateway reescriba `/media/{key}` → `/buckets/webapi-storage/{key}`.
 
-## Presigned URLs
+## URLs prefirmadas (presigned)
 
-To **avoid** routing large files through the API, the client talks to S3 directly using short-lived signed URLs:
+Para **no** hacer pasar ficheros grandes por la API, el cliente habla directo con S3 mediante URLs firmadas de corta vida:
 
-- **Uploads (PUT)**: `RequestTrackUploadUrls` / `RequestPlayListPictureUpload` generate presigned PUTs (with signed `Content-Type` and `If-None-Match: *`, ~120s expiry). The client uploads straight to S3.
+- **Subidas (PUT)**: `RequestTrackUploadUrls` / `RequestPlayListPictureUpload` generan presigned PUT (con `Content-Type` y `If-None-Match: *` firmados, expiración ~120s). El cliente sube directo a S3.
-- **Images (GET)**: thumbnails are served via presigned GETs (one object = one URL).
+- **Imágenes (GET)**: las miniaturas se sirven con presigned GET (un objeto = una URL).
 
-**Why presigned instead of proxying**: routing a ~100 MB audio file through the API would burn memory and bandwidth on the application servers and wouldn't scale well. A direct presigned PUT to S3 is the standard, correct pattern here.
+**Por qué presigned y no proxiar**: subir un audio de ~100 MB a través de la API consumiría memoria/ancho de banda de los servidores de aplicación y escalaría mal. La presigned PUT directa a S3 es el patrón estándar y correcto.
 
-### Upload intents and quota
+### Upload intents y cuota
-Every `upload-urls` call creates **UploadIntents** (reservations in the `Issued` state) and returns the URLs. They're **consumed** when the track/playlist is created. There's a per-user quota (`MaxActiveUploadIntentsPerUser`, byte limits…) to prevent abuse. The `UploadIntentExpirationJob` (in the Worker) marks expired intents and frees up quota. If that job isn't running, stale intents pile up and block new uploads.
+Cada `upload-urls` crea **UploadIntents** (reservas en estado `Issued`) y devuelve las URLs. Al crear la pista/playlist se **consumen**. Hay cuota por usuario (`MaxActiveUploadIntentsPerUser`, bytes…) para evitar abuso. El `UploadIntentExpirationJob` (en el Worker) marca como expirados los intents caducados y libera la cuota; si ese job no corre, los intents colgados se acumulan y bloquean nuevas subidas.
 
-## What's public and what's private (deployment)
+## Qué es público y qué privado (despliegue)
 
-| Expose to the internet | Keep private |
+| Exponer a internet | Mantener privado |
 |---|---|
-| S3 API `:8333` (behind TLS), needed for the client's presigned PUT/GET | filer `:8888` (internal network, gateway only) |
+| S3 API `:8333` (tras TLS) — necesario para presigned PUT/GET del cliente | filer `:8888` (solo el gateway, en red interna) |
-| StreamingGateway `:8081` | master `:9333`, volume server, admin UI |
+| StreamingGateway `:8081` | master `:9333`, volume server, UI de admin |
 
-- **Audio** is served through the gateway, so SeaweedFS can stay private for that flow.
+- **El audio** se sirve por el gateway → SeaweedFS puede quedar privado para ese flujo.
-- **Uploads and images** use presigned URLs, so the client talks to the S3 endpoint directly and `:8333` has to be reachable (though useless without a valid signature, this is the standard model for any S3/MinIO bucket).
+- **Subidas e imágenes** usan presigned → el cliente toca el endpoint S3 directamente, así que `:8333` debe ser alcanzable (pero inútil sin firma válida; es el modelo de cualquier bucket S3/MinIO).
-- In **production**: `InfrastructureStorage:Address` must be the **public S3 endpoint** (the signature is computed for that host). If the servers can't reach it internally, use split config: public host for signing, internal host for server-side operations.
+- En **producción**: `InfrastructureStorage:Address` debe ser el **endpoint S3 público** (la firma se calcula para ese host); si los servidores no lo alcanzan internamente, se usa config dividida (host público para firmar / interno para operaciones server-side).
 
-**Rule of thumb**: the gateway, and at most the signed `:8333`, are the only public surface. Master, volume, filer and admin are **never** exposed.
+**Regla**: el gateway y, como mucho, el `:8333` firmado son la única superficie pública; master/volume/filer/admin **nunca** se exponen.

docs/streaming.md

@@ -1,55 +1,55 @@
-# Audio streaming
+# Streaming de audio
 
-## Goal
+## Objetivo
 
-Play audio **without the bytes passing through the API**, while still controlling access. The API only issues a short-lived permission; the reverse proxy serves the bytes from SeaweedFS.
+Reproducir el audio **sin que los bytes pasen por la API**, pero con control de acceso. La API solo emite un permiso corto; el reverse proxy sirve los bytes desde SeaweedFS.
 
-## Format: a single AAC file (.m4a), served via HTTP range
+## Formato: fichero único AAC (.m4a) por HTTP range
 
-Audio is transcoded into **one `audio.m4a`** (AAC, MP4 container with `+faststart` so the `moov` atom sits at the start and range-based seeking works), stored under `Tracks/ProcessedAudios/{AudioFolderName}/`. There's no manifest or segments: the player downloads the file via **HTTP range requests** (the same model Spotify uses for on-demand music).
+El audio se transcodifica a **un único `audio.m4a`** (AAC, contenedor MP4 con `+faststart` para que el átomo `moov` quede al inicio y el seek por range funcione), dentro de la carpeta `Tracks/ProcessedAudios/{AudioFolderName}/`. No hay manifest ni segmentos: el reproductor descarga el fichero por **HTTP range requests** (modelo tipo Spotify para VOD musical).
 
-Multi-bitrate isn't implemented yet; the path to add it is transcoding several qualities (`audio_96.m4a`, …) and letting the client pick one at playback start (no seamless mid-track ABR, same as Spotify).
+Multi-bitrate no está implementado hoy; el camino para añadirlo es transcodificar varias calidades (`audio_96.m4a`, …) y que el cliente elija una al iniciar (sin ABR fluido a mitad de pista, igual que Spotify).
 
-## Access control: a prefix-scoped stream ticket
+## El acceso: stream-ticket de prefijo
 
-Access is authorized for **the track's folder prefix** via a short-lived *stream ticket*, validated by the proxy on every request. Even though there's only one object today, the ticket is still scoped to the prefix `Tracks/ProcessedAudios/<folder>/` (covering the current file and any future quality variants).
+Se autoriza **el prefijo de la carpeta** de la pista con un *stream-ticket* de corta vida, y el proxy lo valida en cada petición. Aunque hoy sea un único objeto, el ticket sigue acotado al prefijo `Tracks/ProcessedAudios/<folder>/` (cubre el fichero actual y cualquier calidad futura).
 
-## Flow
+## Flujo
 
-1. `GET /tracks/{id}/stream` (authenticated) → the API authorizes the request and returns:
+1. `GET /tracks/{id}/stream` (autenticado) → la API autoriza y devuelve:
    ```json
    { "manifestUrl": "http://<gateway>/media/Tracks/ProcessedAudios/<folder>/audio.m4a",
      "ticket": "<JWT RS256>", "expiresInSeconds": 3600 }
    ```
-   The ticket carries the claim `prefix = "Tracks/ProcessedAudios/<folder>/"`.
+   El ticket lleva el claim `prefix = "Tracks/ProcessedAudios/<folder>/"`.
-2. The player opens the audio URL with `?t=<ticket>` appended (or the `X-Stream-Ticket` header).
+2. El reproductor abre la URL del audio añadiéndole `?t=<ticket>` (o la cabecera `X-Stream-Ticket`).
-3. The **StreamingGateway** (YARP) validates the ticket and forwards the request to the filer; the bytes flow SeaweedFS → client (with range/seek support).
+3. El **StreamingGateway** (YARP) valida el ticket y reenvía al filer; los bytes van SeaweedFS → cliente (con range/seek).
 
-## The ticket (RS256)
+## El ticket (RS256)
 
-- Signed by the API with a **private** key (`StreamTicketService`); validated by the gateway with the **public** one (`TicketValidator`). That way the gateway **can't issue** tickets, only verify them.
+- Lo firma la API con clave **privada** (`StreamTicketService`); el gateway valida con la **pública** (`TicketValidator`). Así el gateway **no puede emitir** tickets, solo verificarlos.
-- Claims: `sub`, `prefix`, `aud = media-gateway`, `iss = musify-webapi`, `exp` (~1h TTL).
+- Claims: `sub`, `prefix`, `aud = media-gateway`, `iss = musify-webapi`, `exp` (TTL ~1h).
 
-**Why RS256 (asymmetric)**: it separates responsibilities. The issuer (API) and the verifier (gateway) don't share a secret, so even if the gateway is compromised, it can't mint permissions.
+**Por qué RS256 (asimétrica)**: separa responsabilidades — emisor (la API) y verificador (gateway) no comparten secreto; el gateway, aunque se comprometa, no puede crear permisos.
 
-## The gateway (validation + proxy)
+## El gateway (validación + proxy)
 
-`TicketValidationMiddleware`, on every request to `/media/**`:
+`TicketValidationMiddleware` en cada petición a `/media/**`:
-1. Reads `?t=`, validates its signature/aud/iss/exp.
+1. Lee `?t=`, valida firma/aud/iss/exp.
-2. Checks that the requested key **starts with** the ticket's `prefix`. If not → 403.
+2. Comprueba que la clave pedida **empieza por** el `prefix` del ticket (`StartsWith`). Si no → 403.
-3. Strips the `?t=` and passes the request on to YARP, which rewrites `/media/{key}` → `/buckets/webapi-storage/{key}` for the filer.
+3. Quita el `?t=` y deja pasar a YARP, que reescribe `/media/{key}` → `/buckets/webapi-storage/{key}` del filer.
 
-- No ticket → **401**; outside the prefix → **403**; ok → **200** (and **206** for range requests, so seeking works).
+- Sin ticket → **401**; fuera de prefijo → **403**; ok → **200** (y **206** en range requests, así que el seek funciona).
-- Passes through `Range`/`Accept-Ranges` and exposes those headers via CORS.
+- Pasa `Range`/`Accept-Ranges` y expone esos headers por CORS.
 
-## One ticket per track?
+## ¿Un ticket por canción?
 
-Yes. Each ticket is scoped to **one** folder (one track). Playing a different one means requesting a new ticket. It's cheap (the API just signs a JWT) and it's the safest option: every permission only unlocks what you're about to play.
+Sí. Cada ticket está acotado a **una** carpeta (una pista). Para reproducir otra, se pide otro ticket. Es barato (la API solo firma un JWT) y es lo más seguro: cada permiso abre solo lo que vas a reproducir.
 
-- If that ever becomes a problem (very frequent track switching), the same `prefix` claim mechanism can widen the scope to a whole playlist or the whole library (`Tracks/ProcessedAudios/`). It's a security/convenience trade-off. The default is **per track**.
+- Si algún día molesta (muchísimos cambios de pista), el mismo mecanismo del claim `prefix` permite ampliar el alcance: a nivel de playlist o de toda la biblioteca (`Tracks/ProcessedAudios/`). Trade-off seguridad ↔ comodidad. Por defecto, **por canción**.
 
-## Open items / security notes
+## Pendiente / notas de seguridad
 
-- Today, the policy for who can request a ticket is "any authenticated user" (TODO: restrict it with `UserHasTrack`/visibility).
+- La política de quién puede pedir el ticket es hoy "cualquier autenticado" (TODO: restringir con `UserHasTrack`/visibilidad).
-- The prefix check is a literal `StartsWith`; it would be worth hardening it against `..` path traversal, even though browsers and ASP.NET normalize `..`.
+- El check de prefijo es `StartsWith` literal; conviene endurecer rechazando claves con `..` (path traversal), aunque navegadores y ASP.NET normalizan `..`.
-- The ticket travels in the query string (`?t=`); the gateway strips it before forwarding, so it never reaches the filer's logs.
+- El ticket viaja en la query (`?t=`); el gateway lo elimina antes de reenviar (no llega a los logs del filer).

web-player/design_handoff_musify_player/Crear playlist.dc.html

@@ -0,0 +1,183 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<script src="./support.js"></script>
+</head>
+<body>
+<x-dc>
+<helmet>
+<link href="https://fonts.googleapis.com/css2?family=Sora:wght@400;500;600;700&family=Plus+Jakarta+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
+<style>
+*{box-sizing:border-box}
+html,body{margin:0;padding:0;background:#050507}
+a{color:#b4a4ea;text-decoration:none}
+a:hover{color:#cdc0f5}
+img{display:block}
+input,textarea{font-family:inherit}
+input::placeholder,textarea::placeholder{color:#5d5d63}
+@keyframes modalIn{from{opacity:0;transform:translateY(14px) scale(.985)}to{opacity:1;transform:none}}
+@keyframes fadeIn{from{opacity:0}to{opacity:1}}
+</style>
+</helmet>
+
+<div style="position:relative;min-height:100vh;display:grid;place-items:center;padding:40px 20px;background:radial-gradient(120% 90% at 50% 0%,#15131c,#08080b 58%,#050507);font-family:'Plus Jakarta Sans',system-ui,sans-serif;color:#c9c8cc;-webkit-font-smoothing:antialiased">
+
+  <div style="position:absolute;inset:0;background:rgba(4,4,6,.55);backdrop-filter:blur(3px)"></div>
+
+  <div data-screen-label="Crear playlist" style="position:relative;width:100%;max-width:560px;border-radius:24px;overflow:hidden;border:1px solid rgba(255,255,255,.075);background:linear-gradient(180deg,#141419,#0d0d11 62%,#0b0b0e);box-shadow:0 32px 90px rgba(0,0,0,.66),0 2px 0 rgba(255,255,255,.035) inset;animation:modalIn .28s cubic-bezier(.2,.8,.3,1)">
+
+    <div style="position:absolute;inset:0;pointer-events:none;background:{{ auraTop }};transition:background .5s ease"></div>
+
+    <!-- HEADER -->
+    <div style="position:relative;display:flex;align-items:flex-start;justify-content:space-between;gap:16px;padding:24px 26px 0">
+      <div>
+        <div style="font-size:10.5px;letter-spacing:.16em;text-transform:uppercase;color:#8f8f93;font-weight:600;margin-bottom:9px">Tu biblioteca</div>
+        <div style="font-family:'Sora',sans-serif;font-size:21px;font-weight:600;letter-spacing:-.03em;color:#d8d7db">Crear playlist</div>
+      </div>
+      <div onClick="{{ close }}" title="Cerrar" style="flex:0 0 auto;width:32px;height:32px;border-radius:10px;display:grid;place-items:center;cursor:pointer;color:#87878c;border:1px solid rgba(255,255,255,.06);background:rgba(255,255,255,.025);transition:background .18s ease,color .18s ease" style-hover="background:rgba(255,255,255,.07);color:#d0cfd4">
+        <svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"><path d="M6 6l12 12M18 6L6 18"></path></svg>
+      </div>
+    </div>
+
+    <!-- BODY -->
+    <div style="position:relative;padding:22px 26px 0;display:flex;gap:20px;align-items:flex-start">
+
+      <!-- COVER -->
+      <div style="flex:0 0 auto;width:124px">
+        <div style="position:relative;width:124px;height:124px;border-radius:16px;overflow:hidden;border:1px solid rgba(255,255,255,.07);background:{{ coverGrad }};box-shadow:{{ coverGlow }};transition:background .45s ease,box-shadow .45s ease;display:grid;place-items:center">
+          <svg viewBox="0 0 24 24" width="26" height="26" fill="none" stroke="rgba(255,255,255,.62)" stroke-width="1.5" stroke-linecap="round"><path d="M9 18V6l10-2v12"></path><circle cx="6.5" cy="18" r="2.5"></circle><circle cx="16.5" cy="16" r="2.5"></circle></svg>
+        </div>
+        <div style="display:flex;gap:6px;margin-top:11px">
+          <sc-for list="{{ swatches }}" as="s" hint-placeholder-count="5">
+            <div onClick="{{ s.pick }}" title="{{ s.name }}" style="flex:1;height:20px;border-radius:7px;cursor:pointer;background:{{ s.dot }};box-shadow:{{ s.ring }};transition:box-shadow .18s ease"></div>
+          </sc-for>
+        </div>
+        <div onClick="{{ upload }}" style="margin-top:9px;text-align:center;font-size:11px;font-weight:500;color:#8a8a8f;padding:7px 0;border-radius:9px;border:1px dashed rgba(255,255,255,.1);cursor:pointer;transition:color .18s ease,border-color .18s ease" style-hover="color:#cfccd9;border-color:rgba(255,255,255,.2)">Subir imagen</div>
+      </div>
+
+      <!-- FIELDS -->
+      <div style="flex:1;min-width:0">
+        <label style="display:block;font-size:11px;font-weight:600;letter-spacing:.03em;color:#87878c;margin-bottom:8px">Nombre</label>
+        <input value="{{ name }}" onChange="{{ onName }}" maxLength="60" placeholder="Playlist sin título" style="width:100%;padding:12px 14px;border-radius:12px;background:rgba(255,255,255,.035);border:1px solid rgba(255,255,255,.075);outline:none;color:#dcdbe0;font-family:'Sora',sans-serif;font-size:16px;font-weight:600;letter-spacing:-.02em" style-focus="border-color:rgba(255,255,255,.2);background:rgba(255,255,255,.055)">
+        <div style="display:flex;justify-content:flex-end;font-size:10.5px;color:#65656a;margin-top:6px">{{ counter }}</div>
+
+        <label style="display:block;font-size:11px;font-weight:600;letter-spacing:.03em;color:#87878c;margin:10px 0 8px">Descripción <span style="font-weight:400;color:#5f5f65">· opcional</span></label>
+        <textarea value="{{ desc }}" onChange="{{ onDesc }}" rows="3" placeholder="Para qué sirve esta playlist, cuándo la escuchas…" style="width:100%;resize:none;padding:11px 14px;border-radius:12px;background:rgba(255,255,255,.035);border:1px solid rgba(255,255,255,.075);outline:none;color:#c4c3c9;font-size:12.5px;line-height:1.6" style-focus="border-color:rgba(255,255,255,.2);background:rgba(255,255,255,.055)"></textarea>
+      </div>
+    </div>
+
+    <!-- OPTIONS -->
+    <div style="position:relative;padding:20px 26px 0">
+      <div style="display:flex;align-items:center;justify-content:space-between;gap:14px;padding:13px 15px;border-radius:13px;background:rgba(255,255,255,.026);border:1px solid rgba(255,255,255,.055)">
+        <div style="min-width:0">
+          <div style="font-size:12.5px;font-weight:600;color:#cfccd9">Visibilidad</div>
+          <div style="font-size:11px;color:#7b7b81;margin-top:3px">{{ visHint }}</div>
+        </div>
+        <div style="flex:0 0 auto;display:flex;gap:3px;padding:3px;border-radius:10px;background:rgba(0,0,0,.34);border:1px solid rgba(255,255,255,.05)">
+          <sc-for list="{{ visOptions }}" as="v" hint-placeholder-count="2">
+            <div onClick="{{ v.pick }}" style="padding:6px 14px;border-radius:8px;font-size:11.5px;font-weight:600;cursor:pointer;background:{{ v.bg }};color:{{ v.fg }};transition:background .18s ease,color .18s ease">{{ v.label }}</div>
+          </sc-for>
+        </div>
+      </div>
+
+      <div onClick="{{ toggleCollab }}" style="display:flex;align-items:center;justify-content:space-between;gap:14px;margin-top:9px;padding:13px 15px;border-radius:13px;cursor:pointer;background:rgba(255,255,255,.026);border:1px solid rgba(255,255,255,.055);transition:background .18s ease" style-hover="background:rgba(255,255,255,.045)">
+        <div style="min-width:0">
+          <div style="font-size:12.5px;font-weight:600;color:#cfccd9">Colaborativa</div>
+          <div style="font-size:11px;color:#7b7b81;margin-top:3px">Quien tenga el enlace puede añadir canciones</div>
+        </div>
+        <div style="flex:0 0 auto;width:40px;height:23px;border-radius:20px;padding:3px;background:{{ collabTrack }};transition:background .2s ease">
+          <div style="width:17px;height:17px;border-radius:50%;background:#0c0c10;transform:{{ collabKnob }};transition:transform .2s cubic-bezier(.3,.8,.3,1)"></div>
+        </div>
+      </div>
+    </div>
+
+    <!-- FOOTER -->
+    <div style="position:relative;display:flex;align-items:center;justify-content:space-between;gap:14px;flex-wrap:wrap;margin-top:22px;padding:17px 26px 20px;border-top:1px solid rgba(255,255,255,.055);background:rgba(0,0,0,.2)">
+      <div style="font-size:11px;color:#6e6e74;max-width:230px;line-height:1.5">Podrás añadir canciones desde cualquier pantalla.</div>
+      <div style="display:flex;gap:9px;margin-left:auto">
+        <div onClick="{{ close }}" style="padding:11px 19px;border-radius:11px;border:1px solid rgba(255,255,255,.1);font-size:12.5px;font-weight:500;cursor:pointer;color:#a9a7b2;transition:background .18s ease,color .18s ease" style-hover="background:rgba(255,255,255,.05);color:#d3d2d8">Cancelar</div>
+        <div onClick="{{ create }}" style="display:flex;align-items:center;gap:8px;padding:11px 21px;border-radius:11px;font-size:12.5px;font-weight:600;background:{{ ctaBg }};color:{{ ctaFg }};cursor:{{ ctaCursor }};opacity:{{ ctaOpacity }};transition:background .18s ease,opacity .18s ease">
+          <svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"><path d="M12 5v14M5 12h14"></path></svg>
+          Crear playlist
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <sc-if value="{{ created }}" hint-placeholder-val="{{ false }}">
+    <div style="position:fixed;left:50%;bottom:34px;transform:translateX(-50%);display:flex;align-items:center;gap:11px;padding:12px 18px;border-radius:13px;background:#16161c;border:1px solid rgba(255,255,255,.09);box-shadow:0 18px 46px rgba(0,0,0,.6);animation:fadeIn .22s ease">
+      <div style="width:26px;height:26px;border-radius:8px;background:{{ coverGrad }};flex:0 0 auto"></div>
+      <div style="font-size:12.5px;color:#cfccd9;font-weight:500">Playlist «{{ createdName }}» creada</div>
+    </div>
+  </sc-if>
+</div>
+
+</x-dc>
+<script type="text/x-dc" data-dc-script data-props="{&quot;$preview&quot;:{&quot;width&quot;:900,&quot;height&quot;:760}}">
+const HUES = [
+  { name: 'Ámbar', h: 68 },
+  { name: 'Violeta', h: 288 },
+  { name: 'Azul', h: 244 },
+  { name: 'Verde', h: 158 },
+  { name: 'Rojo', h: 22 },
+];
+
+class Component extends DCLogic {
+  state = { name: '', desc: '', hue: 1, vis: 'Privada', collab: false, created: false, createdName: '' };
+
+  renderVals() {
+    const h = HUES[this.state.hue].h;
+    const name = this.state.name;
+    const ready = name.trim().length > 0;
+    return {
+      name, desc: this.state.desc,
+      counter: name.length + '/60',
+      onName: e => this.setState({ name: e.target.value }),
+      onDesc: e => this.setState({ desc: e.target.value }),
+      coverGrad: `linear-gradient(150deg,oklch(.66 .16 ${h}),oklch(.34 .11 ${h}) 58%,#0e0e13)`,
+      coverGlow: `0 14px 34px oklch(.5 .13 ${h} / .22)`,
+      auraTop: `radial-gradient(110% 60% at 18% -10%,oklch(.55 .13 ${h} / .16),transparent 62%)`,
+      swatches: HUES.map((s, i) => ({
+        name: s.name,
+        dot: `linear-gradient(145deg,oklch(.66 .16 ${s.h}),oklch(.38 .11 ${s.h}))`,
+        ring: i === this.state.hue
+          ? '0 0 0 1.5px rgba(255,255,255,.85), 0 0 0 4px rgba(0,0,0,.5)'
+          : '0 0 0 1px rgba(255,255,255,.07)',
+        pick: () => this.setState({ hue: i }),
+      })),
+      visOptions: ['Privada', 'Pública'].map(label => ({
+        label,
+        bg: this.state.vis === label ? '#cfccd9' : 'transparent',
+        fg: this.state.vis === label ? '#0a0a0d' : '#8e8e94',
+        pick: () => this.setState({ vis: label }),
+      })),
+      visHint: this.state.vis === 'Privada'
+        ? 'Solo tú la ves en tu biblioteca'
+        : 'Aparece en tu perfil y se puede compartir',
+      collabTrack: this.state.collab ? `oklch(.68 .15 ${h})` : 'rgba(255,255,255,.12)',
+      collabKnob: this.state.collab ? 'translateX(17px)' : 'translateX(0)',
+      toggleCollab: () => this.setState(s => ({ collab: !s.collab })),
+      ctaBg: ready ? '#c6c4cb' : 'rgba(255,255,255,.08)',
+      ctaFg: ready ? '#0a0a0d' : '#6c6c72',
+      ctaCursor: ready ? 'pointer' : 'not-allowed',
+      ctaOpacity: ready ? 1 : 0.85,
+      create: () => {
+        if (!ready) return;
+        this.setState({ created: true, createdName: name.trim() });
+        clearTimeout(this._t);
+        this._t = setTimeout(() => this.setState({ created: false }), 2600);
+      },
+      close: () => this.setState({ name: '', desc: '', collab: false, created: false }),
+      upload: () => {},
+      created: this.state.created,
+      createdName: this.state.createdName,
+    };
+  }
+  componentWillUnmount() { clearTimeout(this._t); }
+}
+
+</script>
+</body>
+</html>