Este directorio contiene todas las decisiones arquitectónicas importantes del proyecto Remote Spotify Player para aplicaciones DJ. Cada ADR documenta una decisión significativa, su contexto, alternativas consideradas y consecuencias.
Cada ADR sigue la estructura:
- Estado: Propuesto / Aceptado / Rechazado / Deprecado / Superseded
- Fecha: Fecha de la decisión
- Decisores: Quién participó en la decisión
- Contexto: Situación que llevó a la decisión
- Decisión: Qué se decidió
- Justificación: Por qué se tomó esta decisión
- Alternativas: Qué otras opciones se consideraron
- Consecuencias: Impacto positivo y negativo
- Referencias: Links a documentos relacionados
| # | Título | Estado | Fecha |
|---|---|---|---|
| 001 | Event-Driven Architecture | Aceptado | 2025-11-14 |
| 002 | Database per Service Pattern | Aceptado | 2025-11-14 |
| 003 | Uso de IIS como Servidor Web | Superseded | 2025-11-14 |
| 004 | BIT como Plataforma de Componentes | Superseded | 2025-11-14 |
| 005 | React con Vite para el Frontend | Aceptado | 2025-11-14 |
| 006 | Python para Backend de Microservicios | Aceptado | 2025-11-14 |
| 007 | Trunk-Based Development Strategy | Aceptado | 2025-11-14 |
| 010 | Observability-First Architecture | Aceptado | 2025-11-14 |
Las decisiones 001-002, 005-007 forman el núcleo de nuestra arquitectura:
- Event-Driven (ADR-001): Comunicación asíncrona entre servicios
- Database per Service (ADR-002): Independencia de datos por microservicio
- React + Vite Frontend (ADR-005): Framework moderno para UI de control DJ
- Python Backend (ADR-006): Microservicios con FastAPI
- Trunk-Based Development (ADR-007): Estrategia de control de versiones y cambios
- GCP as Cloud Platform (ADR-007): Google Cloud Platform para infraestructura serverless
- Spotify Web API (ADR-008): Integración oficial con Spotify para control de reproducción
- Cloud Firestore Real-time Sync (ADR-009): Sincronización en tiempo real de estado de playback
- Observability-First Architecture (ADR-010): Stack open-source para observabilidad total (OpenTelemetry, Prometheus, Grafana, Jaeger)
- IIS Web Server (ADR-003): Reemplazado por Cloud Run (GCP) + Uvicorn/Vite
- BIT Components (ADR-004): Reemplazado por npm packages (frontend) y Python packages (backend)
- Copia la plantilla
adr-template.md - Nombra el archivo:
XXX-descripcion-corta.md - Completa todas las secciones
- Solicita review del equipo de arquitectura
- Actualiza este README con la nueva entrada
- Propuesto: En discusión, no implementado
- Aceptado: Aprobado y en uso
- Rechazado: Evaluado pero no seleccionado
- Deprecado: Ya no se usa, pero fue válido
- Superseded: Reemplazado por otro ADR (incluir link)
Los ADRs son inmutables una vez aceptados. Para cambiar una decisión:
- Crear nuevo ADR que supersede el anterior
- Marcar el ADR viejo como "Superseded by ADR-XXX"
- Explicar en el nuevo ADR por qué se cambió
Próximas decisiones arquitectónicas a documentar:
- MIDI Protocol Integration Strategy (controladores DJ)
- Audio Analysis and BPM Detection (fallback cuando Spotify no provee)
- Offline Mode and Caching Strategy
- Crossfade and Mixing Implementation
- Integration with DJ Software (Rekordbox, Serato)
- Estrategia de API Versioning
- Autenticación y Autorización (OAuth 2.0 con Spotify + JWT)
- Estrategia de Testing (Unit, Integration, E2E)
- Observabilidad y Monitoring (ADR-010): OpenTelemetry + Prometheus + Grafana + Jaeger + Loki
- CI/CD Pipeline Architecture (Cloud Build + Cloud Run)
- Disaster Recovery y Backup Strategy
- Performance Testing Strategy
- Rate Limiting and Throttling Strategy
- WebSocket vs Server-Sent Events for Real-time Commands