Capa dbt · Transformación (dónde vive la lógica de negocio)

Página transversal. La ingesta (Cloud Run, Pub/Sub, Dataflow, Airbyte, Datastream) solo mueve el dato a solvento-data-prod. Toda la lógica de negocio —dedup, redondeos, joins, conversiones de moneda, reglas, métricas— vive en modelos dbt. Si un número en un dashboard o en el frontend "se ve raro", la explicación casi siempre está aquí.

Terminal en dbt-etls (terminal_client / terminal_market) fue ELIMINADO el 2026-09-11

Los modelos de terminal en dbt-etls (models/terminal_client/, models/terminal_market/, datasets …terminal y …terminal_stg, ej. client_dbt) ya no existen: existían solo para alimentar el export a Supabase, que se apagó ese día (ver Apagado Terminal → Supabase). El producto de pricing actual es Terminal v3 (repo terminal), que lee de dbt-analytics en solvento-risk-analytics-prod y materializa terminal_v3.datarelease_*. Las referencias a terminal/client_dbt de abajo se conservan por contexto histórico; trátalas como deprecadas.

Los dos proyectos dbt

Proyecto	Repo	Rol	Admin
dbt-etls	`dbt-etls`	Ingeniería — consistencia de datos crudos y tablas que alimentan productos (`consistency_jobs`, mensajería, elevenlabs, CRM Lightfield)	Martin
dbt-analytics	`dbt-analytics`	Analytics — warehouse completo (medallion) para riesgo, ventas, operaciones, producto	Diego

Ambos están orquestados por dbt Cloud y corren con schedule diario (madrugada), pero escriben en proyectos BigQuery distintos:

Proyecto dbt	Escribe en	Esquemas
dbt-etls	`solvento-adv-analytics-prod`	`consistency_jobs`
dbt-analytics	`solvento-risk-analytics-prod`	`analytics_engineering_staging` / `_intermediate` / `_core` / `_data_products`

Cómo se resuelve el proyecto de salida: en dbt-etls cada modelo fija database='solvento-adv-analytics-prod' en su config{}. En dbt-analytics el proyecto no se escribe en los modelos — lo aporta la conexión de dbt Cloud (target → solvento-risk-analytics-prod); por eso buscar el nombre del proyecto en los modelos da 0 resultados (solo aparece en tests/). dbt-analytics además lee de solvento-adv-analytics-prod (salida de dbt-etls) para encadenar. Los esquemas con prefijo dfrade_* son de ramas de desarrollo, no de prod.

Diagrama de la capa

graph LR
    RAW[("solvento-data-prod<br/>RAW · syntage / datastream_loanpro<br/>hubspot / toku / shinkansen / catalog")]

    subgraph etls["dbt-etls · Ingeniería"]
        AA["models/advanced_analytics/<br/><i>invoices.sql → consistency_jobs</i>"]
    end

    subgraph an["dbt-analytics · Analytics (medallion)"]
        STG["staging/ (stg_*)<br/><i>~71 modelos · vistas</i>"]
        INT["intermediate/ (int_*)<br/><i>~42 · lógica de negocio</i>"]
        MART["marts/core/ (fact_* / dim_*)<br/><i>~33 · gold</i>"]
        DP["data_products/<br/><i>~41 · DSCR, score, decisioning…</i>"]
    end

    OUTE[("solvento-adv-analytics-prod<br/>consistency_jobs")]
    OUTA[("solvento-risk-analytics-prod<br/>analytics_engineering_*")]
    MB["Metabase / Riesgo"]

    RAW --> AA --> OUTE
    RAW --> STG --> INT --> MART --> DP --> OUTA
    OUTE -->|"dbt-analytics lee de aquí"| STG
    OUTA --> MB
    OUTE --> MB

    classDef store fill:#bfdbfe,stroke:#1e40af,color:#000;
    classDef logic fill:#dcfce7,stroke:#15803d,color:#000;
    class RAW,OUTE,OUTA store;
    class AA,STG,INT,MART,DP logic;

Qué proyectos/esquemas de BigQuery escriben

dbt-etls sale a solvento-adv-analytics-prod; dbt-analytics sale a solvento-risk-analytics-prod (esquemas con prefijo analytics_engineering_):

Proyecto dbt	Proyecto BigQuery · esquema	Qué contiene
dbt-etls	`solvento-adv-analytics-prod` · `consistency_jobs`	Datos Syntage deduplicados/canonizados (`invoices`, `invoices_items`)
dbt-analytics	`solvento-risk-analytics-prod` · `analytics_engineering_staging`	Capa bronze (vistas `stg_*`)
dbt-analytics	`…` · `analytics_engineering_intermediate`	Lógica de negocio (silver, `int_*`)
dbt-analytics	`…` · `analytics_engineering_core`	Marts gold (`fact_`, `dim_`)
dbt-analytics	`…` · `analytics_engineering_data_products`	Productos especializados (DSCR, score, decisioning, segmentación…)
dbt-analytics	`…` · `analytics_engineering_semantic`	Modelos semánticos

Las capas (medallion)

dbt-analytics sigue una arquitectura de capas; dbt-etls tiene su propia silver→gold para el terminal.

RAW (solvento-data-prod)
  → staging/      stg_*    vistas, limpieza/renombrado, 1:1 con la fuente   (bronze)
  → intermediate/ int_*    joins, enriquecimiento, reglas de negocio        (silver)
  → marts/core/   fact_*/dim_*   tablas analíticas                          (gold)
  → data_products/   métricas/productos finales (score, DSCR, decisioning)

En dbt-etls:

RAW → advanced_analytics/  (consistency_jobs)   ← dedup/canonización Syntage
                           (messaging, elevenlabs, lightfield, moratory_interest…)

Fuentes (`sources`) — de dónde leen

Las fuentes declaradas apuntan a solvento-data-prod (y al propio solvento-adv-analytics-prod para encadenar):

dbt-etls (models/sources.yml): syntage (invoices, invoices_items, cp_body, cp_mercancias, cp_ubicaciones, …), catalog (c_estado, c_municipio), analiticas (exchange_rates, catalogo_prodyserv_sat), lightfield (accounts, contacts, opportunities, members, definitions).
dbt-analytics (models/staging/**/src_*.yml): syntage (invoices, invoices_items, tax_compliance_*), syntage_adv_analytics (= solvento-adv-analytics-prod.consistency_jobs), loanpro (datastream_loanpro.5202851_P_*), hubspot (deals, company, contact…), toku (invoice, payment, transaction…), catalog, analiticas.

Ejemplos reales de modelos

Modelo · archivo	Repo	Sale a	Qué hace
`invoices` · `models/advanced_analytics/invoices.sql`	dbt-etls	`…consistency_jobs.invoices`	Dedup por `id`, redondeo de montos, canoniza emisor/receptor, convierte moneda (`exchange_rates`). Incremental `merge`, partición `etl_dts`, cluster `id`.
`stg_syntage__invoices` · `models/staging/syntage/`	dbt-analytics	`…staging`	Vista que combina Syntage en vivo + histórico de `consistency_jobs` evitando solapes.
`int_syntage_invoices_items` · `models/intermediate/syntage/`	dbt-analytics	`…intermediate`	Enriquece ítems con catálogo SAT; incremental `merge`, partición mensual por `processed_at`.
`dim_loans` · `models/marts/core/loanpro/dim_loans.sql`	dbt-analytics	`…core`	Dimensión de préstamos (identidad, cliente, financiamiento, tasas).
`dscr` · `models/data_products/dscr/dscr.sql`	dbt-analytics	`…data_products`	Debt Service Coverage Ratio: ingresos 12/6/3M, clasificación, segmentación.
`credit_decisioning_features` · `models/data_products/credit_decisioning/`	dbt-analytics	`…data_products`	Features de decisión de crédito (9 flags: ingresos, buró, historial de pago, cumplimiento fiscal).
`customer_type` · `models/data_products/customer_classifier/`	dbt-analytics	`…data_products`	Clasifica clientes por patrón de facturación.

Subcarpetas de data_products: solvento_score_v2, dscr, credit_decisioning, customer_classifier, segmentation, hubspot, statements, variable_interest_reserve_writeoff.

Bloque `config` típico (de dónde sale el destino)

-- dbt-etls/models/advanced_analytics/invoices.sql
{{ config(
  database='solvento-adv-analytics-prod',
  schema='consistency_jobs',
  materialized='incremental',
  unique_key='id',
  incremental_strategy='merge'
) }}

En dbt-etls cada modelo fija explícitamente database y schema en su config{}. El macro generate_schema_name simplemente respeta el custom_schema_name (sin prefijos). No hay generate_database_name custom: el proyecto de salida es el del config.
En dbt-analytics el schema se define en dbt_project.yml por carpeta y en prod queda con prefijo analytics_engineering_*; el proyecto de salida (solvento-risk-analytics-prod) lo aporta la conexión de dbt Cloud (no se escribe en los modelos; solo aparece hardcodeado en tests/).

Cómo encontrar el modelo que define una métrica

Para un ingeniero/agente que parte de algo que ve (un número, una tabla, un campo):

Identifica la tabla/esquema que lee el consumo (Metabase, riesgo, producto). Ej.: el pricing de Terminal vive en solvento-risk-analytics-prod (ver Terminal v3). (El viejo terminal.client_dbt de dbt-etls fue eliminado el 2026-09-11.)
Mapea proyecto/esquema → repo: solvento-adv-analytics-prod (consistency_jobs) → dbt-etls; solvento-risk-analytics-prod (analytics_engineering_*, data_products) → dbt-analytics.

Encuentra el archivo del modelo: el nombre del modelo = nombre de la tabla. Buscar el .sql en models/**:

grep -rn "schema='terminal'" dbt-etls/models      # modelos que escriben en terminal
find dbt-analytics/models -name "dscr.sql"         # el modelo de DSCR

Recorre el linaje hacia atrás dentro del repo:
{{ ref('otro_modelo') }} → otro modelo dbt (sigue subiendo de gold → silver → staging).
{{ source('syntage','invoices') }} → tabla RAW en solvento-data-prod (ahí termina dbt y empieza la ingesta).
La regla de negocio (redondeo, dedup, conversión de moneda, flags) está en el SQL de ese modelo y/o en macros reutilizables: apply_exchange_rate, overlap_filter, clean_timestamp (en dbt-analytics/macros/).

Regla de oro: si la pregunta es "¿por qué este número es así?", la respuesta está en un modelo dbt (ref/SQL), no en la ingesta. Si es "¿por qué no llegó el dato?", mirá la ingesta y el run de dbt Cloud.

Orquestación

dbt Cloud corre ambos proyectos con schedule diario (madrugada).
dbt-analytics está conectado a dbt Cloud (proyecto analytics-engineering, host ey793.us1.dbt.com, target → solvento-risk-analytics-prod); usa dbt_utils (packages.yml) y incremental_strategy='merge' con unique_key para idempotencia.
Tras el run, las tablas en solvento-adv-analytics-prod (dbt-etls) y solvento-risk-analytics-prod (dbt-analytics) quedan listas para el frontend, Metabase y los modelos de riesgo.

Si falla 🛠️

Impacto: si el run diario de dbt no corre o un modelo falla, las tablas transformadas quedan con datos del día anterior; el RAW puede estar al día pero el consumo no se actualiza.

Síntoma	Dónde mirar	Acción
Frontend/Metabase con datos viejos pese a RAW al día	Run diario de dbt Cloud (proyecto correspondiente)	Re-ejecutar el job; ver qué modelo falló
Un número "raro" (montos, nombres, flags)	El modelo dbt que materializa esa tabla	Revisar el SQL / macro, no la ingesta
Falla un modelo `incremental` por schema change	Logs de dbt Cloud	Varios usan `on_schema_change='sync_all_columns'`; revisar columnas nuevas en la fuente

Escalación: lógica SQL / dbt-analytics / Metabase → Diego · dbt-etls / orquestación / infra → Martin · Airbyte → Gero.

Enlaces

📦 dbt-etls — ingeniería (models/advanced_analytics/; models/terminal_client|market/ fueron eliminados el 2026-09-11)
📦 dbt-analytics — analytics (models/staging|intermediate|marts/core|data_products)
📊 Estado de los runs: dashboard "Data Processes" (Cloud Monitoring) → ver infra-dashboard-monitoreo
🧭 Guía del agente: _guia-agente

Última actualización: 2026-10-05 · Página transversal. Si se agrega un esquema/capa o cambia la orquestación, actualizar esta ficha.