How felipebridge/spotify-streaming-analytics works
Tipo y propósito del proyecto (qué dibujar y por qué)
Este repo es un proyecto de Data Analytics cuyo “producto” final es un dashboard en Power BI, alimentado por un modelo relacional en PostgreSQL que se carga mediante un pipeline ETL en Python. La arquitectura es, esencialmente, una pipeline batch (no es una app web) con tres grandes fases:
ETL (Python/Pandas): extrae/transforma/carga
3. Serving/consumo: PostgreSQL como capa de datos modelados + Power BI como capa de visualización
Tu diagrama debe enfatizar: flujo de datos, componentes de ejecución (Docker), y contratos (esquema SQL/tablas) entre etapas.
Lectura de la estructura del repo (qué componentes existen realmente)
A partir del file tree:
• src/etl.py
Núcleo lógico del sistema: script ETL (probablemente batch) que hace transformaciones con Pandas y carga a Postgres.
• sql/ddl.sql
Definición del modelo/DDL en Postgres. Esto es el “contrato” de la capa de serving.
• docker-compose.yml
Orquestación del runtime de Postgres (y quizá red/volúmenes). Importante para diagramar “infra local reproducible”.
• requirements.txt
Dependencias del ETL (Pandas, driver PostgreSQL como psycopg2/sqlalchemy, etc.).
• docs/ + imágenes
Evidencia del output: dashboard de Power BI (aunque el .pbix no está en el árbol, el README confirma el consumo con Power BI).
Esto sugiere una arquitectura simple, clara, y muy “diagramable” en 6–8 cajas.
Componentes principales a incluir (separar “al máximo” sin inventar)
Dibuja estos componentes como bloques explícitos:
Data Source (Entrada)
• Spotify Dataset (files): CSV/JSON (no está en tree, pero es la fuente declarada por README).
• En el diagrama, represéntalo como “File(s) / Dataset”.
ETL Layer (Proceso)
• Python ETL Job (src/etl.py)
• Sub-bloques internos (opcional, pero recomendable para precisión):
• Extract: lectura de archivos/dataset
• Transform: limpieza, joins, agregaciones, cálculo de métricas (skip rate, intensidad, etc.)
• Load: inserción/UPSERT a Postgres
Data Model / Storage (Capa de datos)
• PostgreSQL DB (Docker)
• DDL / Schema (sql/ddl.sql) como artefacto que crea tablas.
• Si quieres detalle: separa “Database” y “Schema/Tables”, donde el DDL alimenta a la DB.
Consumption / BI (Salida)
• Power BI Dashboard
• Conexión a PostgreSQL (DirectQuery o Import; como no está especificado, pon “Power BI ↔ PostgreSQL (connector)” sin asumir modo).
Runtime / DevOps (Soporte)
• Docker Compose (docker-compose.yml) como “Infra provisioning local”
• Python environment (requirements.txt) como “ETL dependencies runtime”
Relaciones e interacciones (flechas que no deben faltar)
Dibuja el flujo con flechas direccionales claras:
Spotify Dataset → Python ETL (etl.py)
Etiqueta: “Extract (read CSV/JSON)”
Python ETL → PostgreSQL
Etiqueta: “Load (insert/update) via driver”
ddl.sql → PostgreSQL
Etiqueta: “Schema initialization / migrations (DDL)”
Docker Compose → PostgreSQL container
Etiqueta: “Provision DB service + volumes + ports”
Power BI → PostgreSQL
Etiqueta: “Query/Refresh for dashboards”
(Opcional, si quieres cerrar el ciclo) PostgreSQL → Power BI
Flecha inversa o bidireccional, para representar consulta.
Enfatiza que el ETL es batch: puedes poner un ícono/nota “Manual run / scheduled run (cron/Task Scheduler)”. Aunque el scheduler no existe en el repo, el diagrama puede marcarlo como “execution trigger” si quieres representar operación real.
Patrones/decisiones arquitectónicas que conviene reflejar
• Pipeline ETL clásico (Extract → Transform → Load) en un único job.
• Serving layer en modelo relacional (PostgreSQL) diseñado por DDL.
• Separación de responsabilidades:
• Transformaciones en Python/Pandas
• Persistencia/modelado en SQL/Postgres
• Visualización en Power BI
• Reproducibilidad local con Docker: DB como servicio aislado.
Tecnologías y librerías a etiquetar en el diagrama
Incluye explícitamente en los bloques:
• ETL: Python + Pandas (y “Postgres driver” genérico si no quieres asumir el paquete exacto)
• Storage: PostgreSQL (Docker container)
• Provisioning: Docker Compose
• BI: Power BI
• Schema: SQL DDL
Cómo dibujar el “mejor” diagrama para ESTE proyecto (capas + nivel de detalle)
Te recomiendo 2 diagramas (o uno con 2 niveles):
Diagrama 1: “System Context / Data Flow” (alto nivel)
Bloques grandes:
• Dataset → ETL (Python) → PostgreSQL → Power BI
Y al costado: Docker Compose aprovisiona Postgres; DDL crea esquema.
Objetivo: que alguien entienda el sistema en 15 segundos.
Desglosa:
• Un contenedor “ETL Runner (Python env)” ejecutando src/etl.py
• Un contenedor “PostgreSQL (Docker)” con “schema from sql/ddl.sql”
• Power BI como cliente externo
• Volumen (opcional) para persistencia de Postgres (si está en compose; si no lo sabes, dibuja “DB Volume (optional)”)
Objetivo: representar ejecución real y dependencias.
Elementos visuales obligatorios (claridad máxima)
• Labels claros: usa nombres del repo en los nodos (ej. src/etl.py, sql/ddl.sql, docker-compose.yml).
• Flechas con verbos:
• “reads”, “transforms”, “loads”, “queries”, “provisions”, “creates schema”
• Infra (Docker/Compose) = otro
• Consumo (Power BI) = otro
• Leyenda: pequeño recuadro con significado de colores/formas.
PostgreSQL (Docker container)
• debajo: DDL sql/ddl.sql apuntando a Postgres
• al costado: docker-compose.yml apuntando a Postgres
Power BI Dashboard apuntando a Postgres
Así el lector ve inmediatamente: “datos → procesamiento → storage → BI”, con “infra y schema” como soportes.
Qué NO hacer (errores comunes aquí)
• No dibujar esto como “microservicios” o “frontend/backend”: es una pipeline analítica.
• No omitir el DDL: en este tipo de proyecto, el modelo relacional es parte del diseño.
• No confundir Docker Compose con “el sistema”: es el mecanismo de despliegue local del Postgres.
Si quieres que el diagrama sea todavía más fiel, abre src/etl.py y docker-compose.yml y extrae:
• nombre de la DB, puerto, volumen, credenciales (enmascaradas)
• nombres de tablas y entidades del ddl.sql
• pasos principales del ETL (funciones o etapas)
y los conviertes en subcomponentes/labels dentro de los bloques existentes, sin cambiar la arquitectura base.