# Tech stack y arquitectura (MusifyBackend)

Este documento describe **qué tecnologías usa este repo** y **cómo encajan** (capas, workers, mensajería, storage, observabilidad). Está pensado para alguien que llega de cero o para una IA que necesita contexto.

## Foto rápida
- Runtime: **.NET 10** (C#)
- Estilo: **Clean Architecture** (capas `Domain` / `Application` / `Infrastructure`)
- Casos de uso: **CQRS** con **DispatchR** (similar a MediatR)
- Persistencia: **Entity Framework Core** + **PostgreSQL** (provider `Npgsql`)
- Workers / mensajería: **MassTransit** + **RabbitMQ**
- Orquestación de workflows: **MassTransit Courier / RoutingSlip** (Activities)
- Storage de objetos: **SeaweedFS** expuesto como **S3-compatible** (vía AWS SDK `IAmazonS3`)
- Observabilidad: **OpenTelemetry** (traces + metrics, export OTLP)
- Procesado multimedia:
  - Imágenes: **SixLabors.ImageSharp** (resize, WebP)
  - Audio: **ffmpeg** (transcode a DASH)

## Estructura del repo (capas)

### `Domain/` (núcleo de negocio)
- Entidades puras (sin dependencias de infraestructura).
- Ejemplos: `Track`, `PlayList`, `Upload`, etc.
- Estados de negocio relevantes:
  - `ProcessingStatus` (procesado en curso/finalizado, etc.).
  - `LifeCycleStatus` (p.ej. `Active`, `Removing`) para deletes asíncronos.

### `Application/` (casos de uso + contratos)
- Contiene comandos/queries/handlers por feature.
- CQRS:
  - `Commands/` y `Queries/` por feature (`PlayLists`, `Tracks`, `Users`, ...).
  - `Handlers/` ejecutan la lógica de aplicación (coordinar DB + eventos), pero **no implementan** detalles de infraestructura.
- Contratos con infraestructura: `Application/Abstractions/Infrastructure/*`
  - `IDatabase` (abstracto de EF DbContext)
  - `IEventBus` (publicación de eventos)
  - `IStorageService`, `IPictureService`, `IAudioTranscoderService`, etc.
- Eventos de integración: `Application/Events/*`
  - Se publican desde `Application` y se consumen en `Infrastructure`.

### `Infrastructure/` (implementaciones + integraciones)
- Implementa las abstracciones de `Application`.
- Contiene:
  - EF Core DbContext y migraciones
  - MassTransit (consumers, activities, routing slips, outbox)
  - Integración S3 (SeaweedFS) mediante AWS SDK
  - Observabilidad OpenTelemetry
  - Servicios de procesado (ImageSharp/ffmpeg)

## CQRS con DispatchR
- Los “use cases” se modelan como:
  - **Commands**: mutaciones (crear/actualizar/borrar).
  - **Queries**: lecturas.
- Los handlers viven en `Application/*/Handlers/` y dependen de:
  - `IDatabase` para persistencia (sin acoplarse al DbContext concreto).
  - `IEventBus` para emitir eventos cuando hay trabajo asíncrono.

## Persistencia (EF Core + PostgreSQL)
- DbContext: `Infrastructure/Persistence/Database.cs`
  - Usa `UseNpgsql(connectionString)`.
  - Incluye tablas de MassTransit Outbox/Inbox (ver sección de mensajería).
- DI: `Infrastructure/Persistence/DatabaseDependencyInjection.cs`
- Config: `Infrastructure/Configuration/DatabaseConfiguration.cs` (sección `Database`)
  - `ConnectionString`

## Mensajería y workers (MassTransit + RabbitMQ)

### Qué se usa
- Broker: RabbitMQ (`MassTransit.RabbitMQ`).
- MassTransit está configurado en dos modos:
  1) **Cliente** (publica eventos): `Infrastructure/MassTransit/DependencyInjection/MassTransitDependencyInjection.cs` → `AddMassTransitClient()`
  2) **Workers** (consumen y ejecutan activities): `AddMassTransitConsumers()`

### Outbox / Inbox (robustez)
- Se usa **EntityFramework Outbox** (`AddEntityFrameworkOutbox<Database>()`) con:
  - `UsePostgres()`
  - `UseBusOutbox()`
  - `QueryDelay = 1s`
  - `DuplicateDetectionWindow = 30m`
- En el DbContext se registran entidades de MassTransit:
  - `AddInboxStateEntity()`
  - `AddOutboxMessageEntity()`
  - `AddOutboxStateEntity()`

Idea clave:
- La outbox asegura que, tras confirmar la transacción de DB, los mensajes/eventos pendientes se publican de forma fiable.

### Courier / RoutingSlip (workflows asíncronos)
Para operaciones multi-paso (p.ej. imagen/audio y deletes), se usa **MassTransit Courier**:
- Un “RoutingSlip” es una lista de pasos.
- Cada paso es una **Activity** (con args + log opcional).
- Existen dos tipos que aparecen en este repo:
  - `ExecuteActivity` (endpoint `<name>_execute`), típicamente acciones atómicas.
  - `Activity` (con compensación/log), típico para pasos de workflow.

Dónde mirar:
- Builders: `Infrastructure/MassTransit/RoutingSlip/Builders/*`
- Activities: `Infrastructure/MassTransit/Activities/*`
- Consumers (punto de entrada del workflow): `Infrastructure/MassTransit/Consumers/*`
- Registro de endpoints: `Infrastructure/MassTransit/DependencyInjection/*`

Ejemplos de workflows presentes:
- Procesado de imagen (resize + upload + update DB)
- Procesado de audio (transcode DASH + upload + update DB)
- Deletes asíncronos (marcar “removing”, borrar objetos, borrar filas)

### Config de MassTransit
- `Infrastructure/Configuration/MassTransitConfiguration.cs` (sección `MassTransit`)
  - `Address`
  - `Username`
  - `Password`

## Storage de objetos (SeaweedFS como S3-compatible)

### Qué se usa
- SDK: `Amazon.S3` (`IAmazonS3`).
- Implementación: `Infrastructure/Services/StorageService.cs` (usa `IAmazonS3`).
- DI: `Infrastructure/Services/ServicesDependencyInjection.cs` → `AddStorageService()`

### Config
- `Infrastructure/Configuration/InfrastructureStorageConfiguration.cs` (sección `InfrastructureStorage`)
  - `Address` (ServiceURL)
  - `AccessKey` / `SecretAccessKey`
  - `ForcePathStyle` (útil en S3-compatibles)
  - `UseHttp`

Notas prácticas (S3-compatible):
- Algunas features avanzadas de AWS S3 pueden no comportarse igual (depende de SeaweedFS). Diseñar workflows para que sean correctos con el subconjunto básico: PUT/GET/HEAD/LIST/DELETE y paths bien definidos.

## Procesado multimedia

### Imágenes
- Librería: `SixLabors.ImageSharp`
- Servicio: `Infrastructure/Services/PictureService.cs`
- Contrato: `Application/Abstractions/Infrastructure/IPictureService.cs`
- Patrón: workers descargan/transforman/suben; la app coordina por eventos.

### Audio
- Herramienta: `ffmpeg` (binario externo)
- Config: `Infrastructure/Configuration/AudioTranscoderConfiguration.cs` (sección `AudioTranscoder`)
  - Timeout, codec/bitrate/channels/sample-rate, segmentación DASH, etc.
- Servicio: `Infrastructure/Services/AudioTranscoderService.cs`
- Contrato: `Application/Abstractions/Infrastructure/IAudioTranscoderService.cs`

### Directorio temporal (workers)
- Config: `Infrastructure/Configuration/WorkerConfiguration.cs` (sección `Workers`)
  - `Routes.TemporaryFilesDirectory`

## Observabilidad (OpenTelemetry)
- DI: `Infrastructure/Observability/OpenTelemetryDependencyInjection.cs`
- Config: `Infrastructure/Configuration/OpenTelemetryConfiguration.cs` (sección `OpenTelemetry`)
  - `OtlpEndpoint`

Qué instrumenta:
- Tracing:
  - `MassTransit`
  - ASP.NET Core
  - HttpClient
  - EF Core
  - Exporter OTLP
- Métricas:
  - `MassTransit`
  - ASP.NET Core
  - HttpClient
  - Runtime + Process
  - Exporter OTLP

## Identidad (Keycloak)
- El repo asume integración con **Keycloak** (ver `AGENTS.md` y nombres como `GetUserByKeycloakQuery`).
- La capa `Application` trata el “Keycloak Id” como identificador de usuario en algunos casos de uso.
- La integración concreta (tokens, validación, etc.) puede vivir fuera de estas 3 capas o en otro proyecto/host.

## Glosario rápido
- **Command / Query**: operación de escritura / lectura.
- **Handler**: clase que ejecuta el caso de uso (CQRS).
- **EventBus**: abstracción para publicar eventos (MassTransit por debajo).
- **Consumer**: “listener” de mensajes en una cola.
- **RoutingSlip**: workflow compuesto por Activities.
- **Activity**: paso del workflow (puede tener log/compensación).
- **Outbox**: patrón para publicar eventos de forma fiable tras commit de DB.

## “Dónde empiezo a leer” (ruta recomendada)
1) Arquitectura general: `AGENTS.md`
2) Casos de uso: `Application/*/Commands`, `Application/*/Queries` y sus `Handlers/`
3) Persistencia: `Infrastructure/Persistence/Database.cs` + migraciones
4) Mensajería/workflows: `Infrastructure/MassTransit/*`
5) Integraciones: `Infrastructure/Services/*` (S3, imagen, audio)
6) Observabilidad: `Infrastructure/Observability/OpenTelemetryDependencyInjection.cs`