Arquitectura

Los tres productos de DataSpoc --- Pipe, Lens y ML --- nunca importan el codigo de los demas. Se comunican exclusivamente a traves de archivos Parquet en un bucket compartido siguiendo una convencion de directorios estricta.

El Contrato del Bucket

La estructura del bucket es la interfaz entre todos los productos. Este es el contrato sagrado --- nunca debe cambiar sin versionamiento.

bucket/
  .dataspoc/
    manifest.json                       # Catalog (Pipe writes, Lens reads)
    state/<pipeline>/state.json         # Incremental bookmarks (Pipe only)
    logs/<pipeline>/<timestamp>.json    # Execution logs (Pipe only)
  raw/<source>/<table>/                 # Raw data (Pipe writes)
    dt=YYYY-MM-DD/
      *.parquet
  curated/<domain>/<table>/             # Cleaned data (Pipe transforms)
    dt=YYYY-MM-DD/
      *.parquet
  gold/<domain>/<table>/                # Analyst aggregations (Lens transforms)
    *.parquet
  ml/models/<model>/                    # ML artifacts (ML writes, Lens reads)
    model.pkl
    features.json
    metrics.json
  ml/predictions/<model>/              # ML predictions (ML writes, Lens reads)
    *.parquet

manifest.json

El manifiesto es el catalogo de todo lo que hay en el bucket. Pipe lo escribe en cada ejecucion. Lens lo lee para descubrir tablas, esquemas y particiones. ML lo lee para encontrar datos de entrenamiento.

Capas del Data Lake

Capa	Quien escribe	Quien lee	Herramienta
Raw	Ingenieros de Datos	Ingenieros de Datos	Pipe (ingesta)
Curated	Ingenieros de Datos	Analistas	Pipe (transformacion)
Gold	Analistas	Todos	Lens (transformaciones SQL)
ML Models	Cientificos de Datos	DS, API	ML (entrenamiento)
ML Predictions	Cientificos de Datos	Analistas	ML (prediccion), Lens (consulta)

Raw

Pipe escribe datos crudos exactamente como se extraen de la fuente. Un directorio por fuente, un subdirectorio por tabla, particionado por fecha.

Curated

Las transformaciones de Pipe limpian y normalizan los datos crudos. Deduplicacion, conversion de tipos, manejo de nulos. Organizados por dominio de negocio en lugar de sistema de origen.

Gold

Las transformaciones de Lens crean agregaciones listas para analistas. Resumenes de ingresos, tablas de KPI, feeds para dashboards. Legibles por todos en la organizacion.

ML

ML lee de las capas curated o gold, entrena modelos y escribe artefactos y predicciones de vuelta en el bucket. Lens puede luego consultar las predicciones como cualquier otra tabla.

Control de Acceso

DataSpoc nunca implementa autenticacion. El control de acceso se maneja completamente por IAM de la nube.

Bucket	Acceso	Usuarios
s3://company-bronze	Solo DE	Ingenieros de Datos
s3://company-finance	Equipo de Finanzas	Analistas, CFO
s3://company-hr	Equipo de RR.HH.	Analistas de RR.HH.
s3://company-product	Equipo de Producto	PMs, Analistas de Producto

Un bucket por limite de permisos. Tu proveedor de nube determina quien puede leer y escribir.

Reglas Entre Productos

Estas reglas aseguran que los productos permanezcan desacoplados y que el contrato del bucket sea el unico punto de integracion:

1. Pipe nunca importa codigo de Lens o ML --- la comunicacion es solo via bucket
2. Lens nunca importa codigo de Pipe o ML --- lee el bucket, llama a ML via subproceso
3. ML nunca importa codigo de Pipe o Lens --- lee y escribe Parquet en el bucket
4. Platform nunca importa codigo de Pipe, Lens o ML --- llama a ML via subproceso
5. Todos los mensajes CLI en ingles
6. Todos los repos usan Python 3.10+, Typer, Pydantic, pytest, uv
7. Sin secretos en ningun repo --- solo variables de entorno o IAM de la nube