Registros de Decisión de Arquitectura (ADR)
Este registro documenta las decisiones técnicas fundamentales adoptadas para la plataforma RutaViva, incluyendo alternativas evaluadas y justificación técnica.
ADR-0001: Airflow con CeleryExecutor
- Estado: Aceptado
- Contexto: Se requiere orquestar pipelines batch que ingieren millones de viajes históricos, consultan el clima cada hora y generan reportes mensuales.
- Decisión: Utilizar Apache Airflow con
CeleryExecutorsobre contenedores. - Alternativas Descartadas:
- Sequential/LocalExecutor: No permite paralelismo real de tareas ni distribución horizontal.
- AWS Step Functions: Mayor costo por transición de estado y menor portabilidad con el ecosistema de datos local/on-premise.
- Consecuencias: Requiere un broker (RabbitMQ/Redis) y base de datos de metadatos PostgreSQL independiente.
ADR-0002: RabbitMQ como Broker de Mensajería
- Estado: Aceptado
- Contexto: 8,000 vehículos transmiten telemetría cada 15 segundos (~533 mensajes/segundo sostenidos, con picos de solicitudes de hasta 5,000 req/min).
- Decisión: Implementar RabbitMQ con topología de Topic Exchanges y colas durables.
- Alternativas Descartadas:
- Llamadas HTTP Síncronas directas: Las ráfagas saturarían la base de datos o el proceso calculador.
- Apache Kafka: Aunque excelente para streams masivos, añade sobrecarga operacional innecesaria (ZooKeeper/KRaft) para el volumen y retention window requerido.
- Consecuencias: Máximo throughput con
DeliveryMode.NOT_PERSISTENTen telemetría ydurable=Truepara garantizar resiliencia ante reinicios.
ADR-0003: Apache Spark para Procesamiento Batch en Medallón
- Estado: Aceptado
- Contexto: Procesamiento de más de 6 meses de archivos NYC Yellow Taxi con esquemas cambiantes entre años (2019 vs 2022) y validación de reglas de calidad.
- Decisión: Implementar dos jobs PySpark desacoplados (
job1_clean_validateyjob2_enrich_model). - Alternativas Descartadas:
- Pandas / Procesamiento en memoria de nodo único: Saturación de memoria RAM (OOM) y más de 6 horas de procesamiento por mes.
- AWS Glue Job: Costos de inicio en frío elevados para pruebas locales y menor reproducibilidad en desarrollo.
- Consecuencias: Permite reejecutar independientemente el paso que falle y garantiza reprocesamiento idempotente.
ADR-0004: Estado Operacional en PostgreSQL (RDS)
- Estado: Aceptado
- Contexto: El sistema debe mantener catálogos, estados de conductores/licencias/sanciones, telemetría reciente y auditorías de viaje con integridad referencial estricta.
- Decisión: Utilizar PostgreSQL 16 como base de datos operacional.
- Alternativas Descartadas:
- Bases NoSQL (MongoDB/DynamoDB): Complejidad para garantizar integridad referencial y comprobaciones de estados legales de conductores (RN-09).
- Consecuencias: Consultas de multiplicador por clave primaria en milisegundos y soporte transaccional ACID para auditorías.
ADR-0005: Data Lake en S3 (Parquet) + Amazon Athena
- Estado: Aceptado
- Contexto: Exposición analítica para dashboards en Power BI sin degradar el rendimiento operacional de la base de datos transaccional.
- Decisión: Almacenar la capa Gold en formato Parquet columnar particionado en Amazon S3 y consultar vía Athena.
- Alternativas Descartadas:
- Conectar Power BI directamente a PostgreSQL: Consultas analíticas pesadas colapsarían la base de datos operacional utilizada por la API en vivo.
- Consecuencias: Separación total entre OLTP y OLAP; costo por consulta optimizado mediante particionamiento por año/mes y formato columnar Snappy.
ADR-0006: Desacoplamiento de Pipelines CI/CD y Estrategia de Despliegue en Amazon ECR
- Estado: Aceptado
- Contexto: El monorepo de RutaViva contiene dos cargas de trabajo con características técnicas radicalmente distintas:
- Microservicios operacionales de baja latencia (
services/: FastAPI, SQLAlchemy, RabbitMQ). - Jobs analíticos de procesamiento distribuido por lotes (
batch/: Apache Spark, Java 17 Temurin, PyArrow, DAGs de Airflow). Mantener un único pipeline CI/CD monolítico obligaba a instalar Java 17 y Spark en cada cambio menor de la API, elevando el tiempo de ejecución a más de 3 minutos e introduciendo fallos cruzados. Adicionalmente, se requiere garantizar el principio de Shift-Left Security (CT-02) y trazabilidad inmutable de imágenes para despliegues.
- Microservicios operacionales de baja latencia (
- Decisión:
- Separación de Pipelines (RWI-65):
ci-cd-app.yml: Monitoreaservices/**einfra/**. Ejecuta escaneo CT-02, linter (ruff), contenedor efímero PostgreSQL 16 y 19 pruebas unitarias. Al fusionar enmain, construye y publica imágenes Docker multi-stage en Amazon ECR.ci-cd-data.yml: Monitoreabatch/**. Configura Java 17 Temurin, escaneo CT-02, validación de sintaxis AST (py_compile) y pruebas PySpark. Al fusionar enmain, sincroniza DAGs y jobs a AWS S3.
- Quality Gate Preventivo y Bloqueante (CT-02 / RWI-66): El escaneo de secretos se ejecuta como el primer paso antes de compilar o probar, abortando de inmediato si se detectan llaves privadas o claves de acceso AWS.
- Inmutabilidad y Trazabilidad en Amazon ECR: Las imágenes se publican con doble taggeo:
${{ github.sha }}(inmutable, garantizando reproducibilidad y rollbacks exactos) ylatest(para orquestadores de desarrollo).
- Separación de Pipelines (RWI-65):
- Alternativas Descartadas:
- Pipeline Único Monolítico (
ci.yml): Añadía~150 sinnecesarios por cada commit en la API y hacía frágil el pipeline ante dependencias de JVM no relacionadas con los microservicios. - Matrix Builds Globales: Forzaba la ejecución de la suite de datos incluso en PRs exclusivos de documentación o frontend.
- Despliegue síncrono por SSH a servidores: Descartado en favor de contenedores inmutables en ECR listos para Kubernetes (EKS) o ECS.
- Pipeline Único Monolítico (
- Consecuencias: Tiempo de retroalimentación en PRs de la API reducido a
~40 s, aislamiento total de fallos entre equipos de desarrollo de API y de Data Engineering, y conformidad estricta con el estándar de seguridad CT-02.
ADR-0007: Formato Parquet Snappy para Datasets Históricos F1
- Estado: Aceptado
- Contexto: Los datos de viajes TLC de NYC en CSV superan con creces el gigabyte por mes, saturando el ancho de banda y memoria durante la lectura de Spark.
- Decisión: Utilizar Apache Parquet con compresión Snappy para la fuente F1 histórica y para las capas Silver y Gold.
- Consecuencias: Reducción de ~75% de almacenamiento en disco, lectura columnar y pushdown de predicados nativo en Spark.
ADR-0008: Open-Meteo Archive API para Clima Horario Histórico (F3)
- Estado: Aceptado
- Contexto: El cálculo de tarifas dinámicas y el modelo dimensional exigen correlacionar cada viaje con la precipitación horaria (
weather_hour). - Decisión: Consumir la API abierta de Open-Meteo Archive (
https://archive-api.open-meteo.com/v1/archive) para NYC (40.7128,-74.0060) con granularidad horaria. - Consecuencias: Resolución horaria estricta de 744 h/696 h que sincroniza exactamente con
date_trunc("hour", tpep_pickup_datetime)a costo $0.00.
ADR-0009: Enriquecimiento Geoespacial con STRtree de Shapely
- Estado: Aceptado
- Contexto: Los datos TLC anteriores a julio de 2016 utilizaban coordenadas GPS en vez de LocationIDs.
- Decisión: Distribuir el shapefile oficial mediante
sparkContext.broadcasty utilizar un índice espacialshapely.strtree.STRtreedentro de una UDF de PySpark. - Consecuencias: Búsqueda espacial en memoria local $O(\log N)$ por punto en cada worker, eliminando el overhead de joins espaciales cartesianos.
ADR-0010: Ingesta Idempotente con Validación de Metadatos en S3
- Estado: Aceptado
- Contexto: Reintentos del pipeline batch en Airflow o re-ejecuciones manuales corrían el riesgo de re-subir gigabytes redundantes a S3.
- Decisión: Implementar verificación previa mediante
s3.head_object()comparandosource-sizeysource-mtime-ns. - Consecuencias: Ingesta idempotente; si los archivos no han cambiado de tamaño o timestamp, se omite la transferencia y la tarea toma menos de 5 segundos.
ADR-0011: Aislamiento del Intérprete Python en Ejecutores PySpark
- Estado: Aceptado
- Contexto: Los workers de PySpark invocaban por defecto el Python del sistema operativo host, generando errores de librerías faltantes (
pyarrow,shapely). - Decisión: Configurar explícitamente
spark.pyspark.pythonyspark.pyspark.driver.pythonhaciasys.executable. - Consecuencias: Garantiza que tanto el Driver como los Workers de Spark utilicen exactamente el entorno virtual activo con todas las dependencias científicas.
ADR-0012: Zona de Cuarentena Explícita con Causa de Rechazo
- Estado: Aceptado
- Contexto: Los datos de transporte crudos presentan viajes anómalos (distancias 0 con cobros altos, coordenadas fuera de NYC, etc.).
- Decisión: Aislar los registros defectuosos en
quarantine/trips/year=YYYY/month=MM/agregando la columnareject_reason. - Consecuencias: Auditabilidad regulatoria completa (RN-07) sin perder trazabilidad de datos descartados.