# felipebridge/spotify-streaming-analytics architecture

> Architecture diagram of the GitHub repository felipebridge/spotify-streaming-analytics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/felipebridge/spotify-streaming-analytics
- Repository: https://github.com/felipebridge/spotify-streaming-analytics

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================================================
%% Legend (color coding)
%% =========================================================
subgraph "Legend"
direction TB
LData["Data / Files"]:::data
LCompute["Compute / ETL"]:::compute
LStore[("Storage / DB")]:::storage
LInfra["Infra / Provisioning"]:::infra
LBI["BI / Consumption"]:::bi
LArtifact["Artifact / Contract (SQL/Docs)"]:::artifact
end

%% =========================================================
%% System: Spotify Analytics ETL -> Postgres -> Power BI
%% =========================================================
subgraph "Batch Data Pipeline (Analytics)"
direction TB

%% -------- Data Source --------
subgraph "A) Data Source"
direction TB
Dataset["Spotify Dataset (CSV/JSON files)"]:::data
end

%% -------- ETL Layer --------
subgraph "B) ETL Layer (Python + Pandas)"
direction TB
PyEnv["Python Environment (deps)"]:::infra
ETL["Python ETL Job (src/etl.py)"]:::compute

subgraph "ETL Steps (single batch job)"
direction TB
Extract["Extract\n(read files)"]:::compute
Transform["Transform\n(clean/join/aggregate/metrics)"]:::compute
Load["Load\n(insert/update to Postgres)"]:::compute
end

PyEnv -->|provides_runtime| ETL
ETL -->|runs_steps| Extract
Extract -->|outputs_raw_frames| Transform
Transform -->|produces_curated_frames| Load
end

%% -------- Storage / Serving Layer --------
subgraph "C) Serving Layer (PostgreSQL)"
direction TB
Postgres[("PostgreSQL Database\n(Docker container)")]:::storage
Schema["PostgreSQL Schema / Tables\n(from DDL)"]:::artifact
DDL["SQL DDL (sql/ddl.sql)"]:::artifact
end

%% -------- Consumption --------
subgraph "D) Consumption / BI"
direction TB
PowerBI["Power BI Dashboard"]:::bi
Docs["Docs / Evidence (images)"]:::artifact
end

%% -------- Runtime / DevOps --------
subgraph "E) Runtime / DevOps"
direction TB
Compose["Docker Compose\n(docker-compose.yml)"]:::infra
Readme["README (Architecture & Usage)"]:::artifact
end

end

%% =========================================================
%% Connections (data flow + contracts)
%% =========================================================
Dataset -->|"Extract(read_CSV/JSON)"| ETL
Load -->|"Load(insert/update_via_driver)"| Postgres

DDL -->|creates_schema_DDL| Schema
Schema -->|applies_to| Postgres

Compose -->|"provisions_DB(service/ports/volumes)"| Postgres

PowerBI <-->|"queries/refresh(connector)"| Postgres
Docs -->|shows_dashboard_output| PowerBI

Readme -->|describes_pipeline| Dataset
Readme -->|explains_execution| ETL
Readme -->|documents_DB_setup| Compose
Readme -->|documents_BI_consumption| PowerBI

%% Optional operational note (no scheduler in repo)
Trigger["Execution Trigger\n(manual run / scheduled run)"]:::note
Trigger -->|starts_batch_job| ETL

%% =========================================================
%% Click Events (component mapping)
%% =========================================================
click ETL "https://github.com/felipebridge/spotify-streaming-analytics/blob/main/src/etl.py"
click DDL "https://github.com/felipebridge/spotify-streaming-analytics/blob/main/sql/ddl.sql"
click Compose "https://github.com/felipebridge/spotify-streaming-analytics/blob/main/docker-compose.yml"
click PyEnv "https://github.com/felipebridge/spotify-streaming-analytics/blob/main/requirements.txt"
click Docs "https://github.com/felipebridge/spotify-streaming-analytics/tree/main/docs/"
click Readme "https://github.com/felipebridge/spotify-streaming-analytics/blob/main/README.md"

%% =========================================================
%% Styles
%% =========================================================
classDef data fill:#E3F2FD,stroke:#1565C0,stroke-width:1.5px,color:#0D47A1;
classDef compute fill:#E8F5E9,stroke:#2E7D32,stroke-width:1.5px,color:#1B5E20;
classDef storage fill:#FFF3E0,stroke:#EF6C00,stroke-width:1.5px,color:#E65100;
classDef infra fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1.5px,color:#4A148C;
classDef bi fill:#FFFDE7,stroke:#F9A825,stroke-width:1.5px,color:#F57F17;
classDef artifact fill:#ECEFF1,stroke:#455A64,stroke-width:1.5px,color:#263238;
classDef note fill:#FFEBEE,stroke:#C62828,stroke-width:1.5px,color:#B71C1C;
```
