# xcaim04/cuadre architecture

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

- Interactive diagram: https://gitdiagram.com/xcaim04/cuadre
- Repository: https://github.com/xcaim04/cuadre

## Overview

Ruta Cobrada reconciles cash-on-delivery activity to show courier debt and explain cash discrepancies. Its main workflow loads daily sources into bronze, transforms them through silver into gold, checks quality, then publishes Parquet for BI. The repository also offers a BigQuery/Dataform implementation. The graph preserves documented stages and capabilities; several SQL and BI details are described in the README but their implementation files were not sampled, so those links rely on README evidence.

Main entry points: [`pipeline.py`](https://github.com/xcaim04/cuadre/blob/main/pipeline.py) (Pipeline runner), [`sql/gold`](https://github.com/xcaim04/cuadre/tree/main/sql/gold) (Gold marts), [`cargar_bigquery.py`](https://github.com/xcaim04/cuadre/blob/main/cargar_bigquery.py) (BigQuery loader), [`dataform/definitions`](https://github.com/xcaim04/cuadre/tree/main/dataform/definitions) (Dataform models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Local pipeline"]
  node_generator["Synthetic data generator<br/>[generar_datos.py]"]
  node_runner["Pipeline runner<br/>[pipeline.py]"]
  node_bronze["Bronze ingestion<br/>[pipeline.py]"]
  node_bronze_store[("Bronze tables<br/>[pipeline.py]")]
  node_duckdb[("DuckDB store<br/>[pipeline.py]")]
end

subgraph group_model["Data modeling"]
  node_silver["Silver transforms"]
  node_gold["Gold marts"]
  node_quality["Quality checks"]
end

subgraph group_cloud["BigQuery pipeline"]
  node_bq_loader["BigQuery loader<br/>[cargar_bigquery.py]"]
  node_bq_bronze[("BigQuery bronze<br/>[fuentes.js]")]
  node_dataform["Dataform models"]
  node_bq_gold[("BigQuery gold")]
end

subgraph group_outputs["Reporting"]
  node_parquet["Published Parquet"]
  node_bi["Evidence BI<br/>[index.md]"]
end

node_sources["Daily source files"]
node_cloud_storage[("Cloud Storage")]
node_analyst(("Finance user"))

node_generator -->|"generates"| node_sources
node_sources -->|"loads"| node_bronze
node_runner -->|"loads files"| node_bronze
node_bronze -->|"writes"| node_bronze_store
node_runner -->|"materializes"| node_silver
node_runner -->|"materializes"| node_gold
node_bronze_store -->|"transforms"| node_silver
node_silver -->|"feeds"| node_gold
node_runner -->|"runs checks"| node_quality
node_quality -->|"validates"| node_gold
node_runner -->|"publishes"| node_parquet
node_gold -->|"exports"| node_parquet
node_bq_loader -->|"prepares"| node_sources
node_bq_loader -->|"loads tables"| node_bq_bronze
node_bq_loader -.->|"uploads optionally"| node_cloud_storage
node_bq_bronze -->|"transforms"| node_dataform
node_dataform -->|"builds"| node_bq_gold
node_dataform -->|"asserts rules"| node_quality
node_parquet -->|"feeds"| node_bi
node_analyst -->|"views reports"| node_bi

click node_generator "https://github.com/xcaim04/cuadre/blob/main/generar/generar_datos.py"
click node_runner "https://github.com/xcaim04/cuadre/blob/main/pipeline.py"
click node_bronze "https://github.com/xcaim04/cuadre/blob/main/pipeline.py"
click node_bronze_store "https://github.com/xcaim04/cuadre/blob/main/pipeline.py"
click node_silver "https://github.com/xcaim04/cuadre/tree/main/sql/silver"
click node_gold "https://github.com/xcaim04/cuadre/tree/main/sql/gold"
click node_quality "https://github.com/xcaim04/cuadre/tree/main/sql/calidad"
click node_duckdb "https://github.com/xcaim04/cuadre/blob/main/pipeline.py"
click node_bq_loader "https://github.com/xcaim04/cuadre/blob/main/cargar_bigquery.py"
click node_bq_bronze "https://github.com/xcaim04/cuadre/blob/main/dataform/definitions/bronze/fuentes.js"
click node_dataform "https://github.com/xcaim04/cuadre/tree/main/dataform/definitions"
click node_bq_gold "https://github.com/xcaim04/cuadre/tree/main/dataform/definitions/gold"
click node_bi "https://github.com/xcaim04/cuadre/blob/main/bi/pages/index.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_generator,node_runner,node_bronze,node_bronze_store,node_duckdb,node_analyst toneBlue
class node_silver,node_gold,node_quality,node_cloud_storage toneAmber
class node_bq_loader,node_bq_bronze,node_dataform,node_bq_gold toneMint
class node_parquet,node_bi toneRose
class node_sources toneIndigo
```

## Components

### Local pipeline

- [Synthetic data generator](https://github.com/xcaim04/cuadre/blob/main/generar/generar_datos.py): `generar/generar_datos.py`
- [Pipeline runner](https://github.com/xcaim04/cuadre/blob/main/pipeline.py): `pipeline.py`
- [Bronze ingestion](https://github.com/xcaim04/cuadre/blob/main/pipeline.py): `pipeline.py`
- [Bronze tables](https://github.com/xcaim04/cuadre/blob/main/pipeline.py): `pipeline.py`
- [DuckDB store](https://github.com/xcaim04/cuadre/blob/main/pipeline.py): `pipeline.py`

### Data modeling

- [Silver transforms](https://github.com/xcaim04/cuadre/tree/main/sql/silver): `sql/silver`
- [Gold marts](https://github.com/xcaim04/cuadre/tree/main/sql/gold): `sql/gold`
- [Quality checks](https://github.com/xcaim04/cuadre/tree/main/sql/calidad): `sql/calidad`

### BigQuery pipeline

- [BigQuery loader](https://github.com/xcaim04/cuadre/blob/main/cargar_bigquery.py): `cargar_bigquery.py`
- [BigQuery bronze](https://github.com/xcaim04/cuadre/blob/main/dataform/definitions/bronze/fuentes.js): `dataform/definitions/bronze/fuentes.js`
- [Dataform models](https://github.com/xcaim04/cuadre/tree/main/dataform/definitions): `dataform/definitions`
- [BigQuery gold](https://github.com/xcaim04/cuadre/tree/main/dataform/definitions/gold): `dataform/definitions/gold`

### Reporting

- **Published Parquet**
- [Evidence BI](https://github.com/xcaim04/cuadre/blob/main/bi/pages/index.md): `bi/pages/index.md`

### Other components

- **Daily source files**
- **Cloud Storage**
- **Finance user**

## Connections

- Synthetic data generator → Daily source files: generates (evidence: `README.md`)
- Daily source files → Bronze ingestion: loads (evidence: `README.md`)
- Pipeline runner → Bronze ingestion: loads files (evidence: `pipeline.py`)
- Bronze ingestion → Bronze tables: writes (evidence: `pipeline.py`)
- Pipeline runner → Silver transforms: materializes (evidence: `pipeline.py`)
- Pipeline runner → Gold marts: materializes (evidence: `pipeline.py`)
- Bronze tables → Silver transforms: transforms (evidence: `README.md`)
- Silver transforms → Gold marts: feeds (evidence: `README.md`)
- Pipeline runner → Quality checks: runs checks (evidence: `pipeline.py`)
- Quality checks → Gold marts: validates (evidence: `README.md`)
- Pipeline runner → Published Parquet: publishes (evidence: `pipeline.py`)
- Gold marts → Published Parquet: exports (evidence: `README.md`)
- BigQuery loader → Daily source files: prepares (evidence: `cargar_bigquery.py`)
- BigQuery loader → BigQuery bronze: loads tables (evidence: `README.md`)
- BigQuery loader → Cloud Storage: uploads optionally (evidence: `cargar_bigquery.py`)
- BigQuery bronze → Dataform models: transforms (evidence: `README.md`)
- Dataform models → BigQuery gold: builds (evidence: `README.md`)
- Dataform models → Quality checks: asserts rules (evidence: `README.md`)
- Published Parquet → Evidence BI: feeds (evidence: `README.md`)
- Finance user → Evidence BI: views reports (evidence: `README.md`)