Translate docs to English, rewrite README, drop design handoff folder

Translate all of docs/ from Spanish to English and rewrite the root
README as a short project overview instead of a technical run guide.
Remove web-player/design_handoff_musify_player, an old design-tool
export that was no longer needed.
This commit is contained in:
2026-09-21 18:41:04 +02:00
parent 3f8d517ee3
commit 23e30d96fc
21 changed files with 347 additions and 3969 deletions
+32 -28
View File
@@ -1,47 +1,51 @@
# Musify — Documentación
# Musify documentation
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.
Musify is a music streaming backend: upload tracks, process them (transcode
the audio to `.m4a`, generate thumbnails), organize them into playlists, and
stream them without the bytes ever passing through the API.
Esta carpeta explica **qué hace cada pieza, su propósito y por qué está diseñada así**.
This folder explains **what each piece does, its purpose, and why it's built
this way**.
## Índice
## Index
- [architecture.md](architecture.md) — Visión global: componentes, cómo encajan y los flujos principales.
- [projects.md](projects.md) — Qué es y para qué sirve cada proyecto/solución.
- [authentication.md](authentication.md) — Zitadel (OIDC), validación de JWT, provisioning/sync de usuarios.
- [storage.md](storage.md) — SeaweedFS (S3), estructura de claves, URLs prefirmadas, qué es público y qué privado.
- [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) — El worker y los workflows de MassTransit (transcode de audio, miniaturas).
- [development.md](development.md) — Cómo levantar todo en local: contenedores, puertos y comandos.
- [../deploy/README.md](../deploy/README.md) — El deploy en detalle: compose, scripts y producción.
- [architecture.md](architecture.md): overview, components, how they fit together, and the main flows.
- [projects.md](projects.md): what each project/solution is and what it's for.
- [authentication.md](authentication.md): Zitadel (OIDC), JWT validation, user provisioning/sync.
- [storage.md](storage.md): SeaweedFS (S3), key layout, presigned URLs, what's public vs. private.
- [streaming.md](streaming.md): audio streaming (`.m4a` over HTTP range) with stream tickets (RS256) and the reverse proxy (StreamingGateway).
- [media-processing.md](media-processing.md): the worker and its MassTransit workflows (audio transcoding, thumbnails).
- [development.md](development.md): running everything locally, containers, ports, commands.
- [../deploy/README.md](../deploy/README.md): deployment in detail, compose, scripts, and production.
## Mapa de componentes (alto nivel)
## Component map (high level)
```
┌─────────────────────────────────────────────┐
Cliente ───► │ Musify.Api (:5111) API REST + emite tickets │
Client ───► │ Musify.Api (:5111) REST API + issues tickets│
└─────────────────────────────────────────────┘
│ EF Core │ presigned (subidas) │ MassTransit (eventos)
│ EF Core │ presigned (uploads) │ MassTransit (events)
▼ ▼ ▼
PostgreSQL SeaweedFS S3 (:8333) RabbitMQ ──► Worker (procesa)
(metadatos) (objetos) audio→.m4a, imágenes
PostgreSQL SeaweedFS S3 (:8333) RabbitMQ ──► Worker (processes)
(metadata) (objects) audio→.m4a, images
▲
Cliente ───► StreamingGateway (:8081) ┘ sirve audio .m4a (valida ticket, proxy al filer)
Client ───► StreamingGateway (:8081) ┘ serves .m4a audio (validates ticket, proxies to the filer)
Login: Cliente ◄──► Zitadel (:8080, OIDC) → Musify.Api valida el JWT
Login: Client ◄──► Zitadel (:8080, OIDC) → Musify.Api validates the JWT
```
## Stack
- **.NET 10**, C#. Minimal APIs (`Musify.Api`), Worker Service (`Musify.Worker`), ASP.NET + YARP (`Musify.StreamingGateway`).
- **CQRS** con [Mediator] (source-generator) y resultados con **ErrorOr**.
- **EF Core 10** + **PostgreSQL** (metadatos).
- **MassTransit 8** + **RabbitMQ** (procesado asíncrono con routing slips/sagas).
- **SeaweedFS** (almacenamiento de objetos compatible con S3, vía AWSSDK.S3).
- **ffmpeg** (transcode de audio a AAC/`.m4a`), **SixLabors.ImageSharp** (miniaturas).
- **Zitadel** (OIDC/OAuth2) para identidad.
- **CQRS** with [Mediator] (source generator) and results via **ErrorOr**.
- **EF Core 10** + **PostgreSQL** (metadata).
- **MassTransit 8** + **RabbitMQ** (async processing with routing slips/sagas).
- **SeaweedFS** (S3-compatible object storage, via AWSSDK.S3).
- **ffmpeg** (audio transcoding to AAC/`.m4a`), **SixLabors.ImageSharp** (thumbnails).
- **Zitadel** (OIDC/OAuth2) for identity.
## Estructura del repositorio
## Repository layout
Un solo repo: `backend/` (los seis proyectos .NET), `web-player/` (cliente web
SvelteKit), `deploy/` (stacks de Docker Compose y scripts) y `docs/`.
A single repo: `backend/` (the six .NET projects), `web-player/` (the
SvelteKit web client), `deploy/` (Docker Compose stacks and scripts), and
`docs/`.