# anthonnysorianofranco-dot/etl_opinionesclientes architecture

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

- Interactive diagram: https://gitdiagram.com/anthonnysorianofranco-dot/etl_opinionesclientes
- Repository: https://github.com/anthonnysorianofranco-dot/etl_opinionesclientes

## Overview

##### Tipo y propósito del proyecto (a partir del file tree + README)
Este proyecto es un **pipeline ETL batch** (no es una app web) para **análisis de opiniones de clientes**. Su función es:

- **Extract**: leer múltiples **CSV** ubicados en `data/raw/`
- **Transform**: limpiar/normalizar/combinar datos usando **Python + Pandas**
- **Load**: cargar los datos resultantes en **SQL Server** vía **PyODBC**
- Preparación de la BD: `sql/01_create_database_and_tables.sql` crea base y tablas en SQL Server (ejecutado típicamente desde SSMS)

La “arquitectura” es por tanto un flujo de datos orquestado por un script (`src/etl.py`) con dependencias externas (filesystem y SQL Server).

##### Análisis de la estructura del repo (qué componentes debes reflejar)
Del file tree se identifican claramente estos bloques:

- **Entradas (Sources / Raw data)**
`data/raw/*.csv`:
- `clients.csv`
- `products.csv`
- `social_comments.csv`
- `web_reviews.csv`
- `surveys_part1.csv`
- `fuente_datos.csv` (probable “catálogo”/metadatos/origen)

- **Proceso (ETL runtime)**
`src/etl.py`: *la unidad de cómputo/orquestación*. Aquí ocurren:
- lectura de CSV
- transformaciones con Pandas
- conexión ODBC a SQL Server y cargas

- **Destino (Data store)**
SQL Server (externo al repo).
`sql/01_create_database_and_tables.sql`: *provisioning* del destino (schema + tablas)

- **Dependencias/entorno**
`requirements.txt`: Pandas, PyODBC (y lo demás).
(Implicit) Driver ODBC + credenciales + red.

- **Documentación/Imagenes**
`imagenes/` (y README menciona `Documentacion/` aunque no aparece en el tree): útil para anexar al diagrama como referencia, no como componente runtime.

Conclusión: el diagrama debe priorizar **flujo batch**, **capas de datos**, **puntos de fallo** (archivos/DB/conectividad) y **responsabilidades** (script vs DB scripts).

##### Qué buscar/explicitar del README (para el diagrama)
El README fija tecnologías y límites del sistema:

- Transformación: **Pandas**
- Conectividad: **PyODBC**
- Motor destino: **SQL Server**
- Operación humana: **SSMS** para ejecutar el SQL de creación

Eso implica que tu diagrama debe mostrar **dos “runtimes” separados**:

##### Diagrama 1 — Contexto (qué hay alrededor)
Componentes:
- **Operador / Data Analyst** (persona)
- **Máquina de ejecución** (Windows/Linux host donde corre Python)
- **File System / Carpeta `data/raw/`**
- **SQL Server instance**
- **SSMS** (herramienta usada para crear DB/tablas)
Relaciones:
- Operador запуска `etl.py`
- Operador ejecuta `01_create_database_and_tables.sql` en SSMS contra SQL Server
- `etl.py` lee CSV del filesystem
- `etl.py` escribe a SQL Server via ODBC

Esto define alcance y dependencias externas.

##### Diagrama 2 — Contenedores / Componentes principales (alto nivel ejecutable)
Aquí separa el sistema en “bloques deployables” aunque sea local:

##### ETL Runner (Python 3)
- Artifact: `src/etl.py`
- Libs: Pandas, PyODBC
- Responsabilidad: orquestar E/T/L

##### Raw Data Store (CSV)
- Ubicación: `data/raw/`
- Responsabilidad: fuentes de datos estructurados

##### SQL Server (DWH/DB operacional del proyecto)
- Schema/tablas provisionadas por `sql/01_create_database_and_tables.sql`
- Responsabilidad: persistencia y consultas posteriores

##### DB Provisioning Script
- Artifact: `sql/01_create_database_and_tables.sql`
- Ejecutado por: SSMS (humano) o pipeline

Flechas:
- CSV → ETL Runner (lectura)
- ETL Runner → SQL Server (inserciones/loads)
- Provisioning Script → SQL Server (DDL: create db/tables)

##### Diagrama 3 — Flujo ETL detallado (máxima fidelidad)
Este es el más “preciso” para un ETL. Dibújalo como un pipeline:

**Extract**
- Node por cada archivo CSV (o agrúpalos en “Raw CSVs” y lista dentro):
- clients.csv
- products.csv
- social_comments.csv
- web_reviews.csv
- surveys_part1.csv
- fuente_datos.csv

**Transform (en `etl.py`)**
Divide el bloque Transform en sub-bloques (aunque el código no se muestre aquí, es el nivel correcto para el diagrama):
- Parsing & typing (fechas, ids, encoding)
- Cleaning (nulls, duplicates)
- Normalization (column naming, categories)
- Joining/enrichment (ej. unir clientes↔opiniones↔productos)
- Derivations (scores, sentiment flags, KPIs)
- Validation (constraints, reject rows) — aunque sea conceptual, es clave arquitectónicamente

**Load**
- “ODBC Connection (PyODBC)”
- “Target Tables (SQL Server)”
Idealmente lista las tablas si las conoces del SQL; como no están en el README, pon un placeholder:
- `dbo.<clients>`
- `dbo.<products>`
- `dbo.<reviews/comments/surveys>`
- `dbo.<fact_opinions>` (si existe)
y anota: “según `01_create_database_and_tables.sql`”.

Flechas:
- Cada CSV → Transform
- Transform → Load
- Load → SQL Server tables

Anotaciones importantes en el diagrama:
- “Batch job / on-demand execution”
- “Idempotency strategy” (si existe: truncate+load, upserts, staging)
Si no lo sabes aún, pon un callout: “Definir: truncate/merge/upsert”.

##### Patrones y principios arquitectónicos a resaltar (específicos para este repo)
- **Pipeline ETL por etapas** (Extract → Transform → Load)
- **Separación de concerns**:
- DDL/infra de DB en `sql/`
- Proceso de datos en `src/`
- Datos crudos en `data/raw/`
- **Batch processing** (no streaming)
- **Externalized persistence** (SQL Server fuera del runtime Python)
- **Tooling boundary**: SSMS como interfaz de administración, no parte del runtime del ETL

##### Tecnologías/librerías que deben aparecer explícitamente en el diagrama
Inclúyelas como “badges” o texto bajo cada componente:
- ETL Runner: **Python 3**, **Pandas**
- DB Connectivity: **PyODBC** + “ODBC Driver for SQL Server”
- Database: **SQL Server**
- Admin tool: **SSMS** (para ejecutar el script de creación)

##### Elementos obligatorios
- **Etiquetas claras** por bloque: “Raw CSV”, “ETL Script (`src/etl.py`)", “SQL Server”
- **Flechas direccionales** con verbo:
- “read CSV”
- “transform (clean/normalize/join)”
- “insert/bulk load via ODBC”
- “create schema/tables (DDL)”
- Cilindro: almacenamiento (CSV folder, SQL Server)
- Rectángulo: cómputo/proceso (etl.py)
- Documento: scripts SQL
- Persona: operador

##### Nivel de detalle “sin sobrepensar”
Dado que este repo es pequeño, lo más valioso es **separar en muchos componentes explícitos**:
- mostrar cada CSV como source separado (o al menos agrupar y listar)
- mostrar “Transform” descompuesto en 4–6 subpasos
- mostrar “DDL provisioning” como camino independiente del load (porque es un prerequisito)

##### Plantilla de diagrama (qué dibujar literalmente)
Si lo plasmas en un diagrama único (tipo C4 híbrido + pipeline), el layout sugerido es:

**Izquierda (Sources)**
`data/raw/clients.csv`
`data/raw/products.csv`
`data/raw/social_comments.csv`
`data/raw/web_reviews.csv`
`data/raw/surveys_part1.csv`
`data/raw/fuente_datos.csv`

→ **Centro (ETL Runner)**
`Python 3 runtime`
`src/etl.py`
sub-bloques: Extract | Transform | Load
Transform substeps listados

→ **Derecha (Destination)**
`SQL Server`
`Database + tables (from 01_create_database_and_tables.sql)`

**Arriba o abajo (Provisioning path)**
`SSMS` + `sql/01_create_database_and_tables.sql` → `SQL Server (DDL)`

##### Qué te falta para hacerlo “perfectamente exacto” (y cómo representarlo mientras tanto)
Para máxima precisión, abre `sql/01_create_database_and_tables.sql` y `src/etl.py` y extrae:
- nombres reales de tablas destino
- si hay staging tables
- estrategia de carga (truncate/append/merge)
- reglas de calidad (constraints, dedupe keys)
- scheduling (manual vs Task Scheduler/Airflow; aquí no aparece)

Mientras no lo tengas, en el diagrama:
- usa placeholders “Target tables (see DDL script)”
- añade callouts “Load mode: TBD (truncate/merge)”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =======================
    %% Context / Actors
    %% =======================
    Analyst["Operador / Data Analyst"]:::actor

    %% =======================
    %% Inputs (Filesystem)
    %% =======================
    subgraph "Inputs (Filesystem)"
        RawDir[("Raw Data Store\nFolder: data/raw/")]:::store

        Clients["clients.csv"]:::data
        Products["products.csv"]:::data
        Social["social_comments.csv"]:::data
        Web["web_reviews.csv"]:::data
        Surveys["surveys_part1.csv"]:::data
        Catalog["fuente_datos.csv\n(catálogo/metadatos)"]:::data
    end

    %% =======================
    %% Local / Runner Host (Python ETL)
    %% =======================
    subgraph "Local / Runner Host"
        README["README\n(descripción/uso)"]:::doc
        Reqs["requirements.txt\n(Pandas, PyODBC, etc.)"]:::doc

        subgraph "ETL Runner (Python 3)"
            ETL["ETL Script\nsrc/etl.py"]:::compute

            subgraph "Extract"
                ExtractStep["Read CSVs\n(parse/encoding)"]:::step
            end

            subgraph "Transform (Pandas)"
                T1["Parsing & typing\n(fecha/id/encoding)"]:::step
                T2["Cleaning\n(nulls/duplicates)"]:::step
                T3["Normalization\n(column naming/categories)"]:::step
                T4["Joining & enrichment\n(client↔product↔opinions)"]:::step
                T5["Derivations\n(scores/sentiment/KPIs)"]:::step
                T6["Validation\n(constraints/reject rows)"]:::step
            end

            subgraph "Load"
                ODBC["ODBC Connection\nPyODBC + ODBC Driver for SQL Server"]:::connector
                LoadMode["Load mode\nTBD: truncate/append/merge"]:::note
            end
        end

        Images["imagenes/\n(soporte)"]:::doc
    end

    %% =======================
    %% SQL Server (External)
    %% =======================
    subgraph "SQL Server (External Service)"
        SQLServer[("SQL Server Instance")]:::db

        TargetDB[("Database + Tables\n(from DDL script)")]:::db
        Tbl1["dbo.<clients>"]:::table
        Tbl2["dbo.<products>"]:::table
        Tbl3["dbo.<reviews/comments/surveys>"]:::table
        Tbl4["dbo.<fact_opinions>\n(if exists)"]:::table
    end

    %% =======================
    %% Provisioning / Admin Path
    %% =======================
    subgraph "DB Provisioning (Admin)"
        SSMS["SSMS\n(SQL Server Management Studio)"]:::tool
        DDL["01_create_database_and_tables.sql\n(DDL provisioning)"]:::sql
    end

    %% =======================
    %% Relationships (vertical, dataflow)
    %% =======================
    Analyst -->|"runs batch job"| ETL
    Analyst -->|"executes DDL via SSMS"| SSMS

    RawDir -->|"contains"| Clients
    RawDir -->|"contains"| Products
    RawDir -->|"contains"| Social
    RawDir -->|"contains"| Web
    RawDir -->|"contains"| Surveys
    RawDir -->|"contains"| Catalog

    Clients -->|"read CSV"| ExtractStep
    Products -->|"read CSV"| ExtractStep
    Social -->|"read CSV"| ExtractStep
    Web -->|"read CSV"| ExtractStep
    Surveys -->|"read CSV"| ExtractStep
    Catalog -->|"read CSV"| ExtractStep

    ETL -->|"orchestrates"| ExtractStep
    ExtractStep -->|"dataframes"| T1
    T1 --> T2 --> T3 --> T4 --> T5 --> T6
    T6 -->|"prepared dataset"| ODBC
    LoadMode -.->|"define strategy"| ODBC

    ODBC -->|"insert/bulk load"| TargetDB
    SQLServer -->|"hosts"| TargetDB
    TargetDB -->|"tables"| Tbl1
    TargetDB -->|"tables"| Tbl2
    TargetDB -->|"tables"| Tbl3
    TargetDB -->|"tables"| Tbl4

    SSMS -->|"runs"| DDL
    DDL -->|"create schema/tables (DDL)"| SQLServer

    Reqs -->|"installs libs for"| ETL
    README -.->|"documents setup/run"| Analyst
    Images -.->|"reference material"| README

    %% =======================
    %% Click Events (from component mapping)
    %% =======================
    click ETL "https://github.com/anthonnysorianofranco-dot/etl_opinionesclientes/blob/main/src/etl.py"
    click RawDir "https://github.com/anthonnysorianofranco-dot/etl_opinionesclientes/tree/main/data/raw/"
    click Clients "https://github.com/anthonnysorianofranco-dot/etl_opinionesclientes/blob/main/data/raw/clients.csv"
    click Products "https://github.com/anthonnysorianofranco-dot/etl_opinionesclientes/blob/main/data/raw/products.csv"
    click Social "https://github.com/anthonnysorianofranco-dot/etl_opinionesclientes/blob/main/data/raw/social_comments.csv"
    click Web "https://github.com/anthonnysorianofranco-dot/etl_opinionesclientes/blob/main/data/raw/web_reviews.csv"
    click Surveys "https://github.com/anthonnysorianofranco-dot/etl_opinionesclientes/blob/main/data/raw/surveys_part1.csv"
    click Catalog "https://github.com/anthonnysorianofranco-dot/etl_opinionesclientes/blob/main/data/raw/fuente_datos.csv"
    click DDL "https://github.com/anthonnysorianofranco-dot/etl_opinionesclientes/blob/main/sql/01_create_database_and_tables.sql"
    click Reqs "https://github.com/anthonnysorianofranco-dot/etl_opinionesclientes/blob/main/requirements.txt"
    click Images "https://github.com/anthonnysorianofranco-dot/etl_opinionesclientes/tree/main/imagenes/"
    click README "https://github.com/anthonnysorianofranco-dot/etl_opinionesclientes/blob/main/README.md"

    %% =======================
    %% Styles
    %% =======================
    classDef actor fill:#FFE8A3,stroke:#8A6D00,stroke-width:1.5,color:#1f1f1f
    classDef store fill:#D9F2FF,stroke:#1B6A8F,stroke-width:1.5,color:#0b2230
    classDef data fill:#EAF7FF,stroke:#2E86C1,stroke-width:1.2,color:#0b2230
    classDef compute fill:#E7F8E9,stroke:#2E7D32,stroke-width:1.6,color:#0b2230
    classDef step fill:#F0FFF4,stroke:#2E7D32,stroke-width:1.2,color:#0b2230
    classDef connector fill:#FFF2CC,stroke:#B07D00,stroke-width:1.5,color:#0b2230
    classDef db fill:#F3E8FF,stroke:#6A1B9A,stroke-width:1.6,color:#0b2230
    classDef table fill:#F8F1FF,stroke:#6A1B9A,stroke-width:1.0,color:#0b2230
    classDef sql fill:#FFE6E6,stroke:#B71C1C,stroke-width:1.5,color:#0b2230
    classDef tool fill:#E6EEFF,stroke:#1E40AF,stroke-width:1.5,color:#0b2230
    classDef doc fill:#EEEEEE,stroke:#616161,stroke-width:1.2,color:#1f1f1f
    classDef note fill:#FFF8E1,stroke:#C9A227,stroke-dasharray: 4 3,color:#1f1f1f
```
