Registro de decisiones de arquitectura

Un ADR (architecture decision record) es una nota corta que fija una decisión de arquitectura: contexto, opciones, decisión y qué se sacrifica.

Se escribe uno cuando una decisión cambia un contrato, una regla de CLAUDE.md, el costo o la seguridad, o cuando alguien podría volver a discutirla.
Un ADR aceptado no se reescribe: ni contexto, ni opciones, ni decisión, ni sacrificios. Solo cambian su línea de estado y sus relaciones.
Para cambiar una decisión se escribe un ADR nuevo; el nuevo dice Reemplaza ADR-NNN y el viejo pasa a Reemplazado por ADR-NNN. Si solo cambia un punto, Reemplaza en parte y Reemplazado en parte por.
Si un ADR suma sin cambiar nada, dice Complementa ADR-NNN y el otro Complementado por ADR-NNN.
Estados posibles: Propuesto, Aceptado, Reemplazado por ADR-NNN, Reemplazado en parte por ADR-NNN, Obsoleto. Formato: Estado: Aceptado el DD/MM/AAAA por Andrés. y, si aplica, una frase de relación.

Las 35 decisiones

#	Decisión	Estado
001	API Gateway, KrakenD frente a Kong	Aceptado el 10/11/2026 por Andrés.
002	mensajería con Kafka	Aceptado el 10/11/2026 por Andrés.
003	la capa es dueña del stock vendible y de las reservas	Aceptado el 10/11/2026 por Andrés.
004	saga orquestada en order-service	Aceptado el 10/11/2026 por Andrés.
005	modelo de lectura por eventos para stock y precio	Aceptado el 10/11/2026 por Andrés.
006	rate limit en dos niveles	Aceptado el 10/11/2026 por Andrés.
007	qué es síncrono y qué es asíncrono	Aceptado el 10/11/2026 por Andrés. Responde la "regla importante" del PDF.
008	Istio con sidecars para las capacidades transversales	Aceptado el 10/11/2026 por Andrés. Complementado por ADR-030 (la entrada sigue con recursos de Istio).
009	secretos con AWS Secrets Manager y Secrets Store CSI Driver	Aceptado el 10/11/2026 por Andrés.
010	lenguajes y uso de gRPC	Aceptado el 10/11/2026 por Andrés. Complementado por ADR-025 (segunda llamada gRPC interna, de oms-adapter a order-service; sin implementar al 15/11/2026).
011	versionado de APIs y modelo de errores	Aceptado el 10/11/2026 por Andrés.
012	configuración modular del gateway	Aceptado el 10/11/2026 por Andrés.
013	pasarela del demo, Stripe en modo de prueba más pasarela falsa	Aceptado el 10/11/2026 por Andrés (Stripe en su ambiente de prueba).
014	contrato gRPC de inventario alineado con buf STANDARD	Aceptado el 10/11/2026 por Andrés, antes de escribir código que use el contrato.
015	order-service valida el precio con su propia vista de precios	Aceptado el 10/11/2026 por Andrés. Complementado por ADR-020 (vigencias del precio; la ventana de tolerancia y la corrección no cambian).
016	todo error del borde sale en Problem Details	Aceptado el 10/11/2026 por Andrés.
017	la configuración de cada tópico vive en el contrato AsyncAPI	Aceptado el 10/11/2026 por Andrés.
018	marca de sincronización de cada fuente para calcular `asOf` y `stale`	Aceptado el 10/11/2026 por Andrés.
019	inventory-service filtra el stock por el surtido del canal	Aceptado el 11/11/2026 por Andrés. Complementado por ADR-023 (llaves de Redis por servicio).
020	precios con vigencia, el evento lleva el calendario y el precio se elige al leer	Aceptado el 11/11/2026 por Andrés. Complementa ADR-015 (vigencias del precio).
021	métricas de negocio en formato Prometheus, recogidas por la plataforma	Aceptado el 11/11/2026 por Andrés.
022	infraestructura del demo en AWS con OpenTofu	Aceptado el 15/11/2026 por Andrés (propuesto el 10/11/2026 por el carril `infra`; Andrés revisa además el plan antes de cada apply). Reemplazado en parte por ADR-027 (endpoint de la API de Kubernetes). Complementado por ADR-024 y por ADR-030 (fila 8: la entrada sigue con `Gateway` y `VirtualService` de Istio).
023	cada servicio tiene su espacio de llaves en Redis, con prefijo y usuario propio	Aceptado el 11/11/2026 por el agente, con aviso a Andrés (`docs/plan.md`, "Qué puede decidir el agente"). Complementa ADR-019 (las dos llaves `product:{sku}` de pricing-service e inventory-service). Implementado en compose y en los servicios el 15/11/2026; pendiente en EKS (ver la nota de implementación).
024	despliegue de las cargas en Kubernetes y Kafka en Confluent Cloud	Aceptado el 15/11/2026 por Andrés (propuesto el 13/11/2026 por el carril `infra`). Complementa ADR-022 y no cambia ninguna decisión registrada. Complementado por ADR-028 (Kafka en pod). La decisión 9 (particiones) se cerró el 15/11/2026 con la opción A; ver "Cierre de la decisión 9" al final.
025	cómo recibe el OMS la dirección de entrega sin sacar datos personales a Kafka	Aceptado el 15/11/2026 por Andrés con la opción A (propuesto el 11/11/2026 por el agente; toca la regla 2 de `CLAUDE.md` y ADR-010). Complementa ADR-010 (gRPC pasa de un punto a dos). Sin implementar al 15/11/2026; hasta entonces el registro en el OMS sale sin dirección.
026	los identificadores de la orden tienen formato declarado y salen del detector de tarjetas	Aceptado el 14/11/2026 por Andrés. Lo implementa el carril `detector-tarjetas`.
027	API de Kubernetes solo privada, con acceso por túnel de Session Manager	Aceptado el 14/11/2026 por Andrés; escrito por el carril `acceso-eks`. Reemplaza en parte ADR-022 (el endpoint de la API de Kubernetes: la excepción de Trivy del endpoint público en la decisión 14 y la segunda viñeta de "Qué se sacrifica"); el resto de ADR-022 sigue vigente.
028	Kafka en un pod del clúster para desarrollo y ensayos, Confluent Cloud desde el 15/11/2026, con un interruptor	Aceptado el 14/11/2026 por Andrés. Lo implementó el carril `borde-eks`. Complementa ADR-024 (decisión 8, Kafka en Confluent Cloud) y no lo reemplaza: Confluent sigue siendo el Kafka del demo; este ADR fija cuándo entra y qué hay si falla.
029	los datos sensibles se enmascaran al pasar a la DLQ	Aceptado el 15/11/2026 por Andrés (opción A). Lo implementa el carril `pagos-y-adaptadores` en payment-service; order-service aplica el mismo marcador al outbox (`entrada-valida`, R8).
030	la entrada sigue con Gateway y VirtualService de Istio, sin la Gateway API de Kubernetes	Aceptado el 15/11/2026 por Andrés. Complementa ADR-008 (Istio con sidecars) y ADR-022 (fila 8: TLS de origen en `istio-ingress`).
031	recorrido en vivo de una petición, reconstruido desde Tempo	Aceptado el 15/11/2026 (regla de Andrés: ADR necesario y no absorbido por otro, aprobado; lo comunicó la sesión de planeación). Propuesto ese mismo día por el carril `recorrido-en-vivo` (número confirmado por planeación: 030 es de `integracion`, 032 de `monitoreo-en-vivo`, 033 de `panel-de-control`).
032	panel de monitoreo de solo lectura y pila de observabilidad en el clúster	Aceptado el 15/11/2026 (regla de Andrés: ADR necesario y no absorbido por otro, aprobado; lo comunicó la sesión de planeación). Propuesto ese mismo día por el carril `monitoreo-en-vivo`. Pedido de Andrés del 15/11/2026: un panel de solo lectura en `monitor.andesretail.com` con logs, métricas, trazas, quién compra, la prueba de carga y el grafo de componentes en vivo.
033	Consola del demo con escritura acotada en el clúster	Aceptado el 15/11/2026 (decisión del carril `panel-de-control`, con aviso a planeación). Complementa la fase F7 de `docs/plan.md` y `docs/demo/02-subdominios-e-interfaz-de-sistemas.md` ("Los dos modos de exposición").
034	Kafka en pod y Confluent Cloud siempre arriba, con un cambio rápido entre ellos	aceptado el 15/11/2026. Requisito de Andrés (15/11/2026, 14:15 hora de Colombia): "kafka debe estar funcionando siempre en los dos ambientes: pod y en confluent. El switch debe ser algo muy rápido cuando sea necesario como en este momento." Escrito por el carril `nube`. Complementa ADR-028 y no lo reemplaza: sigue habiendo dos modos y un interruptor, `KAFKA_MODE`; cambia qué hace el interruptor.
035	dos caminos para escribir la tarjeta en Stripe, con interruptor	Aceptado el 15/11/2026 (pedido de Andrés). Complementa el ADR-013: agrega un segundo camino de captura de la tarjeta, la página alojada por Stripe, junto al componente de Stripe que el 013 ya definía. La saga, el contrato de la capa y las llaves de `payment-service` no cambian.