Skip to content

Proyecto Terminal

Proyecto completo de análisis y visualización de datos de terminales de carga, que consume datos del Data Warehouse (DWH) y los expone a través de una aplicación web construida con Lovable.

Descripción

El Proyecto Terminal es una solución end-to-end que transforma datos de terminales desde el DWH (solvento-adv-analytics-prod) hacia Supabase, donde una aplicación web construida con Lovable consume y visualiza los datos para análisis de mercado y operaciones de terminales.

Arquitectura del Proyecto

graph TB
    subgraph dwh["Data Warehouse<br/>solvento-adv-analytics-prod"]
        DBT[dbt ETLs<br/>Transformaciones]
        TerminalSchema[terminal schema<br/>client_dbt, market_dbt]
    end

    subgraph etl["ETL Pipeline"]
        CloudRun[Cloud Run<br/>terminal-uploader-prod]
        Scheduler[Cloud Scheduler<br/>Cron: 10:30 AM diario]
    end

    subgraph supabase["Supabase<br/>PostgreSQL"]
        FreightShipments[freight_shipments<br/>Envíos de Clientes]
        Market[market<br/>Datos de Mercado]
        ETLControl[etl_control<br/>Control de ETL]
    end

    subgraph app["Aplicación Web"]
        LovableApp[Solvento Terminal<br/>Lovable + React + TypeScript]
        SupabaseClient[Supabase Client<br/>Consultas en tiempo real]
    end

    DBT -->|"Genera tablas<br/>client_dbt, market_dbt"| TerminalSchema
    Scheduler -->|"HTTP GET /run"| CloudRun
    CloudRun -->|"Query incremental<br/>WHERE etl_dts > watermark"| TerminalSchema
    CloudRun -->|"UPSERT por batches"| FreightShipments
    CloudRun -->|"UPSERT por batches"| Market
    CloudRun -->|"Actualiza watermark"| ETLControl

    FreightShipments -->|"Consulta datos"| SupabaseClient
    Market -->|"Consulta datos"| SupabaseClient
    SupabaseClient --> LovableApp

Componentes del Proyecto

1. Data Warehouse (Origen)

Proyecto GCP: solvento-adv-analytics-prod

Dataset: terminal

Tablas Generadas por dbt: - client_dbt: Modelo gold de datos de clientes terminales - Generado por: Proyecto dbt dbt-etls (modelo client_dbt) - Schema: terminal - Contiene: Datos depurados de envíos de carga de clientes terminales

  • market_dbt: Modelo gold de datos de mercado terminal
  • Generado por: Proyecto dbt dbt-etls (modelo market_dbt)
  • Schema: terminal
  • Contiene: Datos agregados de mercado terminal para análisis

Relación con dbt: Ver dbt - Terminal Client y Terminal Market

2. ETL Pipeline (Cloud Run)

Servicio: terminal-uploader-prod

Repositorio: terminal-uploader (ubicado en /Users/solvento/Desktop/terminal-uploader)

Funcionalidad: - Extrae datos incrementales de BigQuery (solvento-adv-analytics-prod.terminal) - Carga datos a Supabase mediante UPSERT - Gestiona watermarks para carga incremental - Procesa en batches para optimizar rendimiento

Orquestación: Cloud Scheduler ejecuta el pipeline diariamente a las 10:30 AM

Detalles técnicos: Ver Terminal Uploader - ETL

3. Supabase (Destino)

Base de Datos: PostgreSQL (hosted en Supabase)

Tablas: - freight_shipments: Envíos de carga de clientes terminales - Mapeo desde: terminal.client_dbt - Primary Key: uuid - Constraint: UNIQUE en uuid (para UPSERT)

  • market: Datos agregados de mercado terminal
  • Mapeo desde: terminal.market_dbt
  • Primary Key: uuid

  • Constraint: UNIQUE en uuid (para UPSERT)

  • etl_control: Tabla de control para gestión de watermarks

  • Gestiona: last_etl_dts, last_execution, status, records_processed

4. Aplicación Web (Solvento Terminal)

Plataforma: Lovable (React + TypeScript + Supabase)

Repositorio: solvento-terminal (ubicado en /Users/solvento/Desktop/solvento-terminal)

Tecnologías: - Frontend: React, TypeScript, Tailwind CSS - UI Components: shadcn-ui - Backend: Supabase (PostgreSQL + Auth + Real-time) - Build Tool: Vite

Funcionalidades: - Dashboard de analytics de terminales - Visualización de datos de envíos (freight_shipments) - Análisis de mercado terminal (market) - Filtros y búsquedas interactivas - Integración directa con Supabase para consultas en tiempo real - Chat interface para análisis conversacional

Flujo de Datos Completo

1. Transformación (dbt)

Los datos raw de solvento-data-prod son transformados por dbt hacia solvento-adv-analytics-prod.terminal:

Proceso dbt: - Silver Layer: Transformaciones intermedias de datos de terminales - Gold Layer: Modelos finales client_dbt y market_dbt - Frecuencia: Ejecución programada de dbt (ver dbt)

2. ETL Incremental (Cloud Run)

El servicio terminal-uploader-prod sincroniza datos desde BigQuery hacia Supabase:

Proceso ETL: 1. Cloud Scheduler invoca el servicio a las 10:30 AM diariamente 2. El servicio lee el último watermark desde etl_control en Supabase 3. Extrae registros nuevos de BigQuery con WHERE etl_dts > last_etl_dts 4. Procesa datos en batches (1,000 registros para freight_shipments, 250 para market) 5. Ejecuta UPSERT en Supabase usando uuid como clave 6. Actualiza watermark con el máximo etl_dts procesado

Características: - Carga incremental basada en etl_dts - UPSERT para manejar actualizaciones históricas - Procesamiento paralelo por batches - Connection pooling optimizado

3. Consumo (Aplicación Web)

La aplicación Solvento Terminal consume datos directamente de Supabase:

Consultas: - Consultas SQL directas a Supabase - Filtros y agregaciones en tiempo real - Visualizaciones interactivas - Análisis de tendencias y métricas

Repositorios del Proyecto

terminal-uploader

Ubicación: /Users/solvento/Desktop/terminal-uploader

Contenido: - Pipeline ETL Python (Cloud Run) - Configuración de batches y workers - Gestión de watermarks - Scripts de deployment

Estructura: 

terminal-uploader/
├── gcp-etl/
│   ├── main.py              # Cloud Run entry point
│   ├── config.py            # Configuración centralizada
│   ├── extractors/          # Extracción de BigQuery
│   ├── loaders/             # Carga a Supabase
│   ├── utils/               # Watermarks y batches
│   └── terraform/           # Infraestructura como código

solvento-terminal

Ubicación: /Users/solvento/Desktop/solvento-terminal

Contenido: - Aplicación web React + TypeScript - Componentes de dashboard y analytics - Integración con Supabase - Configuración de Lovable

Estructura: 

solvento-terminal/
├── src/
│   ├── components/          # Componentes React
│   ├── pages/               # Páginas de la aplicación
│   ├── hooks/               # Custom hooks
│   ├── integrations/        # Integración Supabase
│   └── lib/                 # Utilidades
├── supabase/                # Configuración Supabase
└── public/                   # Assets estáticos

Integración con Otros Componentes

dbt (Procesamiento)

Relación: dbt genera las tablas client_dbt y market_dbt en solvento-adv-analytics-prod.terminal

Ver: dbt - Terminal Client y Terminal Market

Cloud Run (Consumo)

Relación: El servicio terminal-uploader-prod ejecuta el pipeline ETL

Ver: Cloud Run - terminal-uploader-prod

Cloud Scheduler (Orquestación)

Relación: Cloud Scheduler orquesta la ejecución diaria del pipeline

Job: Terminal_Uploader (10:30 AM diario)

Ver: Cloud Scheduler

Monitoreo y Métricas

Estado del ETL

Consultar en Supabase: 

SELECT * FROM etl_control ORDER BY last_execution DESC;

Logs del Pipeline

gcloud run services logs read terminal-uploader-prod --region=us-central1 --limit=50

Métricas Clave

  • Registros procesados: Por tabla y por ejecución
  • Tiempo de ejecución: Duración del pipeline
  • Tasa de éxito: Porcentaje de ejecuciones exitosas
  • Gap de datos: Diferencia entre BigQuery y Supabase (monitoreo de integridad)

Próximos Pasos

  • [ ] Documentar modelos específicos de dbt para Terminal
  • [ ] Agregar métricas de uso de la aplicación web
  • [ ] Documentar procesos de deployment de la aplicación Lovable
  • [ ] Agregar diagramas de flujo específicos por funcionalidad

Referencias

  • ETL Pipeline: Terminal Uploader - ETL
  • Transformaciones dbt: dbt - Terminal
  • Cloud Run Service: Cloud Run
  • Cloud Scheduler: Cloud Scheduler
  • Repositorio ETL: terminal-uploader (ubicado en /Users/solvento/Desktop/terminal-uploader)
  • Repositorio Aplicación: solvento-terminal (ubicado en /Users/solvento/Desktop/solvento-terminal)