# ucm-gidia-pd1/c2526-r2 architecture

> Architecture diagram of the GitHub repository ucm-gidia-pd1/c2526-r2, 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/ucm-gidia-pd1/c2526-r2
- Repository: https://github.com/ucm-gidia-pd1/c2526-r2

## Overview

##### Qué tipo de proyecto es y para qué sirve (según árbol + README)

**Tipo:** pipeline de datos (ETL/ELT) en Python, con foco geoespacial e inmobiliario.
**Propósito:** construir datasets (Madrid) para alimentar tres “motores” funcionales descritos en el README:

##### Ejecución (usuario/runner) dispara scripts por etapa
- `1_Extraccion/*` → produce datasets “raw”
##### Extracción habla con fuentes externas (HTTP APIs/descargas) y escribe en
- **MinIO/raw** (o local temporal + subida a MinIO)
##### Limpieza lee desde MinIO/raw y escribe a
- **MinIO/processed**
##### Agrupación lee de processed (y/o raw) y genera
- **MinIO/curated** (datasets listos para features/modelos)
##### Analítica/modelos (futuro) consume curated y produce
- predicciones, capas geográficas, scores, etc. (posiblemente de vuelta a MinIO o a una DB/serving layer)

**Aristas importantes a dibujar:**
- `funciones_minio.py` como dependencia transversal de todas las etapas (flechas de dependencia, no de datos).
- `config.py` alimenta al cliente MinIO (flecha de configuración).

##### Patrones/decisiones arquitectónicas a resaltar (c)

- **Arquitectura por pipeline** (ETL por scripts) con separación por etapas.
- **Separación por dominios de datos** dentro de cada etapa (viviendas, transporte, INE, catastro, OSM).
- **Almacenamiento tipo “data lake”** (MinIO) como “single source of truth”.
- **Geoespacial como eje**: rejillas, geometrías, joins espaciales (especialmente en `2_Agrupacion`).
- **Configuración por entorno** (env vars) para credenciales.

##### Tecnologías y librerías a incluir en el diagrama (d)

Del README y nombres:
- **Python + uv** (gestión de entorno/ejecución)
- **MinIO (S3 compatible)** como dataset store
- **OSMnx / OpenStreetMap**
- Fuentes: **INE**, **Catastro**, **Ayuntamiento de Madrid**, **CRTM/transporte**, **Idealista API**

Si en `pyproject.toml` aparecen (no lo has pegado, pero es probable): geopandas, pandas, shapely, requests, scikit-learn, etc.; inclúyelas solo si son realmente relevantes para explicar un bloque (p.ej., “GeoPandas en fase de agregación”).

##### Paso 1: Haz 3 niveles de diagramas (recomendado)
1) **Contexto (C4 L1)**: sistema MAiDay vs actores/fuentes externas (INE, Catastro, OSM, Idealista, Ayto, CRTM, MinIO).
##### Contenedores (C4 L2): Ingesta, Procesado, Storage, Consumo analítico.
3) **Componentes (C4 L3)**: cada script importante como componente dentro de Ingesta/Limpieza/Agrupación.

Esto evita un único diagrama gigante ilegible, pero sigue “separando en tantos componentes como sea posible”.

##### Paso 2: En el diagrama de contenedores, modela “zonas de datos”
En MinIO dibuja **tres prefijos** aunque sean conceptuales:
- `raw/` (salidas directas de extracción)
- `processed/` (datos limpios)
- `curated/` (agregados/features listos)

##### Paso 3: En el diagrama de componentes, sé literal con el repo
Cada archivo principal es un bloque:
- `1_Extraccion`: A…H
- `2_Datos/1_Limpieza`: A…C
- `2_Datos/2_Agrupacion`: A…B + ayto
- `utils/funciones_minio.py` como librería transversal

Conecta cada bloque al dataset que produce/consume (etiqueta flechas con formato: Parquet/CSV/GeoJSON, etc., si lo sabes).

##### Paso 4: Señala “lo que falta” sin inventar
`3_Carga` y `4_Analisis` están vacíos: dibújalos como **placeholders** (“not implemented in repo yet”) conectados con líneas punteadas desde curated.

##### Elementos visuales obligatorios en el diagrama (según tu checklist)

- **Etiquetas claras**: nombre del script + rol (“Extractor INE”, “Limpieza transporte”, “Agregación rejilla”)
- **Flechas direccionales**:
- Fuentes externas → Extractores
- Extractores → MinIO/raw
- Limpieza → MinIO/processed
- Agrupación → MinIO/curated
- Curated → Motores analíticos
- **Codificación por colores / formas** (sugerencia concreta):
- Rectángulos azules: *Jobs/Scripts Python*
- Cilindros morados: *Storage (MinIO)*
- Nubes grises: *Fuentes externas*
- Hexágonos verdes: *Motores ML/IA (consumidores)*
- Líneas punteadas: *futuro / no implementado*

##### Plantilla de diagrama (para que lo puedas plasmar rápido)

**Diagrama “Contenedores” (alto nivel):**
- Actor: “Analista/Dev (uv run …)”
- Bloque: “Extracción (1_Extraccion)” → MinIO/raw
- Bloque: “Limpieza (2_Datos/1_Limpieza)” lee raw → escribe processed
- Bloque: “Agrupación (2_Datos/2_Agrupacion)” lee processed → escribe curated
- Bloques punteados: “Carga (3_Carga)”, “Análisis/Modelos (4_Analisis)”
- Fuentes externas: Idealista, INE, Catastro, OSM, Ayto, Transporte/CRTM

**Diagrama “Componentes extracción”:**
- 7 conectores (A…H) cada uno con flecha a su fuente y a MinIO/raw
- `G_rejillas_madrid.py` como “grid generator” que alimenta después agregación

Si pegas el contenido de `src/config.py` y `src/utils/funciones_minio.py` (y, si quieres, `pyproject.toml`), puedo decirte exactamente qué cajas y flechas añadir (p.ej., si hay rutas/prefijos concretos en MinIO, formatos de salida, dependencias internas entre scripts) para que el diagrama sea todavía más fiel al código.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Actors / Execution
%% =========================
Dev["Analista/Dev<br/>(ejecución manual)"]:::actor
Runner["Runner local<br/>(Python + uv)"]:::runner

Dev -->|"uv_run_python"| Runner

%% =========================
%% Config & Shared Utilities
%% =========================
subgraph "Config & Utils (Transversal)"
direction TB
Env[".env (local)<br/>Secrets/Creds (no repo)"]:::config
Config["src/config.py<br/>(config/env loader)"]:::config
MinioClient["utils/funciones_minio.py<br/>(MinIO S3 client)"]:::utils

Env -->|"env_vars"| Config
Config -->|"configura"| MinioClient
end

Runner -->|"importa_config"| Config

%% =========================
%% External Data Sources
%% =========================
subgraph "Fuentes externas (HTTP / descargas)"
direction TB
Idealista["Idealista API<br/>(anuncios)"]:::external
Ayto["Ayuntamiento de Madrid<br/>(open data)"]:::external
CRTM["Transporte / CRTM<br/>(open data)"]:::external
Catastro["Catastro<br/>(parcelas/inmuebles)"]:::external
INE["INE<br/>(estadística/censo)"]:::external
OSM["OpenStreetMap<br/>(OSMnx)"]:::external
end

%% =========================
%% Storage (Data Lake)
%% =========================
subgraph "Almacenamiento (Data Lake)"
direction TB
MinIO[("MinIO (S3 compatible)<br/>Bucket datasets")]:::storage
Raw[("Zona raw/staging<br/>(prefijo raw/)")]:::storage
Processed[("Zona processed<br/>(prefijo processed/)")]:::storage
Curated[("Zona curated/features<br/>(prefijo curated/)")]:::storage

MinIO --> Raw
MinIO --> Processed
MinIO --> Curated
end

%% =========================
%% Pipeline: Extraction
%% =========================
subgraph "1) Extracción / Ingesta (src/1_Extraccion)"
direction TB

AAnuncios["A_Anuncios_viviendas.py<br/>(Extractor listings)"]:::job
HIdealista["H_Idealista_api.py<br/>(Conector Idealista)"]:::job
BAyto["B_aytoMadrid.py<br/>(Conector Ayto Madrid)"]:::job
CTrans["C_transporte.py<br/>(Conector transporte/CRTM)"]:::job
DCat["D_catastro.py<br/>(Conector Catastro)"]:::job
EINE["E_INE.py<br/>(Conector INE)"]:::job
FOSM["F_osmnx.py<br/>(OSMnx downloader)"]:::job
GGrid["G_rejillas_madrid.py<br/>(Generación rejilla Madrid)"]:::job
end

Runner -->|"ejecuta"| AAnuncios
Runner -->|"ejecuta"| HIdealista
Runner -->|"ejecuta"| BAyto
Runner -->|"ejecuta"| CTrans
Runner -->|"ejecuta"| DCat
Runner -->|"ejecuta"| EINE
Runner -->|"ejecuta"| FOSM
Runner -->|"ejecuta"| GGrid

%% Dependencies (shared MinIO client)
AAnuncios -.->|"usa"| MinioClient
HIdealista -.->|"usa"| MinioClient
BAyto -.->|"usa"| MinioClient
CTrans -.->|"usa"| MinioClient
DCat -.->|"usa"| MinioClient
EINE -.->|"usa"| MinioClient
FOSM -.->|"usa"| MinioClient
GGrid -.->|"usa"| MinioClient

%% External calls
AAnuncios -->|"consume"| Idealista
HIdealista -->|"consume"| Idealista
BAyto -->|"consume"| Ayto
CTrans -->|"consume"| CRTM
DCat -->|"consume"| Catastro
EINE -->|"consume"| INE
FOSM -->|"consume"| OSM

%% Outputs to raw
AAnuncios -->|"escribe_datasets_raw"| Raw
HIdealista -->|"escribe_datasets_raw"| Raw
BAyto -->|"escribe_datasets_raw"| Raw
CTrans -->|"escribe_datasets_raw"| Raw
DCat -->|"escribe_datasets_raw"| Raw
EINE -->|"escribe_datasets_raw"| Raw
FOSM -->|"escribe_datasets_raw"| Raw
GGrid -->|"escribe_grid_raw"| Raw

%% =========================
%% Pipeline: Processing - Cleaning
%% =========================
subgraph "2) Procesado - Limpieza (src/2_Datos/1_Limpieza)"
direction TB
LimpVivi["A_viviendas_modificacion.py<br/>(Limpieza viviendas)"]:::job
LimpAyto["B_aytoMadrid.py<br/>(Limpieza Ayto)"]:::job
LimpTrans["C_transporte.py<br/>(Limpieza transporte)"]:::job
end

Runner -->|"ejecuta"| LimpVivi
Runner -->|"ejecuta"| LimpAyto
Runner -->|"ejecuta"| LimpTrans

LimpVivi -.->|"usa"| MinioClient
LimpAyto -.->|"usa"| MinioClient
LimpTrans -.->|"usa"| MinioClient

Raw -->|"lee_raw"| LimpVivi
Raw -->|"lee_raw"| LimpAyto
Raw -->|"lee_raw"| LimpTrans

LimpVivi -->|"escribe_processed"| Processed
LimpAyto -->|"escribe_processed"| Processed
LimpTrans -->|"escribe_processed"| Processed

%% =========================
%% Pipeline: Processing - Aggregation / Spatial Joins
%% =========================
subgraph "2) Procesado - Agrupación/Uniones geoespaciales (src/2_Datos/2_Agrupacion)"
direction TB
AggGrid["A_rejilla_madrid.py<br/>(Features por rejilla)"]:::geo
AggINEGeo["B_INE_con_geometria.py<br/>(INE + geometría)"]:::geo
AggAyto["B_aytoMadrid.py<br/>(Agregación Ayto)"]:::geo
end

Runner -->|"ejecuta"| AggGrid
Runner -->|"ejecuta"| AggINEGeo
Runner -->|"ejecuta"| AggAyto

AggGrid -.->|"usa"| MinioClient
AggINEGeo -.->|"usa"| MinioClient
AggAyto -.->|"usa"| MinioClient

Processed -->|"lee_processed"| AggGrid
Processed -->|"lee_processed"| AggINEGeo
Processed -->|"lee_processed"| AggAyto

Raw -->|"lee_grid_si_aplica"| AggGrid
GGrid -->|"produce_rejilla"| AggGrid

AggGrid -->|"escribe_curated"| Curated
AggINEGeo -->|"escribe_curated"| Curated
AggAyto -->|"escribe_curated"| Curated

%% =========================
%% Placeholders: Load & Analysis (not implemented yet)
%% =========================
subgraph "3) Carga / Publishing (placeholder)"
direction TB
Carga["src/3_Carga<br/>(no implementado)"]:::placeholder
end

subgraph "4) Análisis / Modelado (placeholder)"
direction TB
Analisis["src/4_Analisis<br/>(no implementado)"]:::placeholder
end

Curated -.->|"futuro_publicación"| Carga
Curated -.->|"futuro_consumo"| Analisis

%% =========================
%% Downstream Consumers (Motors)
%% =========================
subgraph "Consumidores downstream (motores)"
direction TB
MotorReg["Motor 1<br/>Regresión multivariable<br/>(precio justo)"]:::consumer
MotorGeo["Motor 2<br/>Geointeligencia<br/>(capas/servicios/transporte)"]:::consumer
MotorVis["Motor 3<br/>Visión IA<br/>(score modernidad fotos)"]:::consumer
end

Curated -->|"datasets_features"| MotorReg
Curated -->|"capas_geoespaciales"| MotorGeo
Curated -->|"datasets_imágenes/labels"| MotorVis

%% =========================
%% Click Events (component mapping)
%% =========================
click Runner "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/pyproject.toml"
click AAnuncios "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/1_Extraccion/A_Anuncios_viviendas.py"
click HIdealista "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/1_Extraccion/H_Idealista_api.py"
click BAyto "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/1_Extraccion/B_aytoMadrid.py"
click CTrans "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/1_Extraccion/C_transporte.py"
click DCat "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/1_Extraccion/D_catastro.py"
click EINE "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/1_Extraccion/E_INE.py"
click FOSM "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/1_Extraccion/F_osmnx.py"
click GGrid "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/1_Extraccion/G_rejillas_madrid.py"
click LimpVivi "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/2_Datos/1_Limpieza/A_viviendas_modificacion.py"
click LimpAyto "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/2_Datos/1_Limpieza/B_aytoMadrid.py"
click LimpTrans "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/2_Datos/1_Limpieza/C_transporte.py"
click AggGrid "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/2_Datos/2_Agrupacion/A_rejilla_madrid.py"
click AggINEGeo "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/2_Datos/2_Agrupacion/B_INE_con_geometria.py"
click AggAyto "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/2_Datos/2_Agrupacion/B_aytoMadrid.py"
click MinioClient "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/utils/funciones_minio.py"
click Config "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/config.py"
click MinIO "https://github.com/ucm-gidia-pd1/c2526-r2/tree/main/src/utils/"
click Carga "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/3_Carga/.gitkeep"
click Analisis "https://github.com/ucm-gidia-pd1/c2526-r2/blob/main/src/4_Analisis/.gitkeep"
click AAnuncios "https://github.com/ucm-gidia-pd1/c2526-r2/tree/main/src/1_Extraccion/"
click LimpVivi "https://github.com/ucm-gidia-pd1/c2526-r2/tree/main/src/2_Datos/1_Limpieza/"
click AggGrid "https://github.com/ucm-gidia-pd1/c2526-r2/tree/main/src/2_Datos/2_Agrupacion/"

%% =========================
%% Styles
%% =========================
classDef actor fill:#111827,stroke:#0f172a,color:#ffffff,stroke-width:1px
classDef runner fill:#1f2937,stroke:#0f172a,color:#ffffff,stroke-width:1px
classDef config fill:#f59e0b,stroke:#92400e,color:#111827,stroke-width:1px
classDef utils fill:#fbbf24,stroke:#92400e,color:#111827,stroke-width:1px

classDef external fill:#9ca3af,stroke:#4b5563,color:#111827,stroke-width:1px
classDef storage fill:#7c3aed,stroke:#4c1d95,color:#ffffff,stroke-width:1px

classDef job fill:#2563eb,stroke:#1e3a8a,color:#ffffff,stroke-width:1px
classDef geo fill:#1d4ed8,stroke:#1e3a8a,color:#ffffff,stroke-width:1px

classDef consumer fill:#16a34a,stroke:#14532d,color:#ffffff,stroke-width:1px
classDef placeholder fill:#e5e7eb,stroke:#6b7280,color:#111827,stroke-width:1px,stroke-dasharray: 6 4
```
