Flow Analysis — Request→Response y Data Pipelines

Descripción de la cápsula

Los dependency maps que aprendiste en la cápsula anterior te muestran qué está conectado con qué — la estructura estática del codebase. Pero un codebase no es solo estructura; es comportamiento. Y el comportamiento se entiende a través de flujos: cómo un request viaja desde el entry point hasta la respuesta, cómo los datos se transforman en cada paso, y qué side effects ocurren en el camino.

En esta cápsula vas a aprender a generar flow analysis con Claude Code — traces completos que muestran la secuencia de ejecución de un feature. Vas a trazar flujos HTTP (request→response), flujos de datos (input→transformaciones→output), y flujos de error (excepción→propagación→respuesta). Cada tipo de flujo revela información diferente sobre el codebase.

La conexión con el proyecto es directa: en el Architecture Map que vas a construir en la cápsula 05, el flow analysis es uno de los tres componentes principales (junto con dependency maps y pattern analysis). Sin flow analysis, tu mapa arquitectural muestra estructura pero no comportamiento.

Por Qué el Flow Analysis Importa

Estructura vs Comportamiento

# Los dependency maps te dicen:
# "order_service.py importa payment_service.py"
#
# El flow analysis te dice:
# "Cuando un usuario hace checkout, order_service
#  valida el carrito, calcula el total, llama a
#  payment_service.charge(), y si el pago falla,
#  revierte los cambios de inventario"

La estructura te muestra las piezas. El flujo te muestra cómo encajan cuando se ejecutan. Para tomar decisiones de refactoring, necesitas ambos.

Los 3 tipos de flujo

Request Flow Analysis

Qué es y qué revela

Un request flow traza la secuencia completa de funciones que se ejecutan cuando llega un request HTTP. Revela:

• Capas de procesamiento: middleware → route → service → repository → DB
• Lógica de negocio: qué valida, qué calcula, qué verifica
• Puntos de decisión: if/else que cambian el flujo
• Side effects: emails, logs, eventos, cache updates

Generando request flows con Claude Code

Nivel básico — Trace lineal:

# Prompt:
> "Usa Explore para rastrear el flujo completo del endpoint
   POST /api/users/register. Para cada paso, indica:
   archivo, función, qué recibe, y qué produce."

# Output esperado:
# 1. src/api/routes/auth.py:register()
#    Recibe: POST body {name, email, password}
#    Produce: llama auth_service.create_user()
#
# 2. src/middleware/validator.py:validate_request()
#    Recibe: raw request
#    Produce: validated RegisterRequest (Pydantic)
#
# 3. src/services/auth_service.py:create_user()
#    Recibe: RegisterRequest
#    Produce: User object + tokens
#    Pasos internos:
#      - Verifica email no existe
#      - Hashea password (bcrypt)
#      - Crea User en DB
#      - Genera JWT tokens
#
# 4. src/models/user.py:User.create()
#    Recibe: user_data dict
#    Produce: User row en DB
#
# 5. src/utils/security.py:generate_tokens()
#    Recibe: user_id
#    Produce: {access_token, refresh_token}
#
# 6. src/api/routes/auth.py:register()
#    Recibe: User + tokens
#    Produce: HTTP 201 {user: {...}, tokens: {...}}

Nivel intermedio — Trace con branching:

# Prompt:
> "Usa Explore para rastrear el flujo de POST /api/orders,
   incluyendo los puntos donde el flujo puede bifurcarse
   (validación fallida, pago rechazado, inventario agotado)"

# Output esperado incluye el happy path Y los branches:
#
# Paso 3: validate_order()
#   → Si carrito vacío: return HTTP 400 "Empty cart"
#   → Si producto sin stock: return HTTP 409 "Out of stock"
#   → Si válido: continuar a Paso 4
#
# Paso 5: charge_payment()
#   → Si tarjeta rechazada: rollback inventory → HTTP 402
#   → Si timeout: retry 1 vez → si falla: HTTP 503
#   → Si exitoso: continuar a Paso 6

Nivel avanzado — Trace con side effects:

# Prompt:
> "Usa Explore para rastrear el flujo de POST /api/orders
   incluyendo TODOS los side effects. No solo lo que retorna
   el endpoint, sino todo lo que pasa como consecuencia:
   emails, eventos, actualizaciones de cache, logs."

# Output esperado agrega:
# Side effects del happy path:
#   1. inventory_service.reduce_stock() → actualiza DB
#   2. email_service.send_confirmation() → email al usuario
#   3. event_bus.publish(OrderCreated) → notifica subscribers
#   4. analytics.track("order_created") → métricas
#   5. cache.invalidate("user_orders_{id}") → limpia cache
#   6. audit_log.record() → registro de auditoría

Data Flow Analysis

Qué es y qué revela

Un data flow traza cómo se transforman los datos a través del sistema. No se enfoca en qué funciones se llaman, sino en qué forma tienen los datos en cada punto.

Generando data flows con Claude Code

Trace de transformación de datos:

# Prompt:
> "Usa Explore para rastrear cómo se transforman los datos
   desde que un usuario envía un JSON para crear una orden
   hasta lo que se guarda en la base de datos. En cada paso,
   muestra la estructura de los datos."

# Output esperado:
#
# Paso 1: Input del cliente (JSON)
# {
#   "product_id": 123,
#   "quantity": 2,
#   "shipping_address": "...",
#   "coupon_code": "SAVE10"
# }
#
# Paso 2: Después de validación (Pydantic model)
# OrderCreateRequest(
#   product_id=123,
#   quantity=2,
#   shipping_address=Address(street="...", city="...", ...),
#   coupon_code="SAVE10"
# )
# + Se agrega: user_id=456 (del JWT token)
#
# Paso 3: Después de cálculos (dict enriquecido)
# {
#   "user_id": 456,
#   "product_id": 123,
#   "quantity": 2,
#   "unit_price": 24.99,
#   "subtotal": 49.98,
#   "discount": 5.00,  # cupón aplicado
#   "tax": 4.05,
#   "shipping": 5.99,
#   "total": 55.02
# }
#
# Paso 4: Lo que se guarda en DB (Order model)
# Order(
#   id=789,
#   user_id=456,
#   status="pending_payment",
#   subtotal=49.98,
#   discount=5.00,
#   tax=4.05,
#   shipping=5.99,
#   total=55.02,
#   created_at=datetime(2026, 4, 5, ...),
#   updated_at=datetime(2026, 4, 5, ...)
# )
# + OrderItem(order_id=789, product_id=123, quantity=2, unit_price=24.99)
#
# Paso 5: Lo que recibe el cliente (JSON response)
# {
#   "order_id": 789,
#   "status": "pending_payment",
#   "total": 55.02,
#   "items": [{"product_id": 123, "quantity": 2, "subtotal": 49.98}],
#   "estimated_delivery": "2026-04-10"
# }

¿Por qué esto importa para refactoring? Si necesitas cambiar cómo se calcula el descuento, el data flow te dice exactamente en qué paso ocurre la transformación y qué datos necesitas en ese punto. Sin data flow, tendrías que leer todo el código para encontrar dónde ocurre el cálculo.

Error Flow Analysis

Qué es y qué revela

Un error flow traza cómo se propagan las excepciones y errores a través del sistema. Revela:

• Dónde se originan los errores: qué función lanza la excepción
• Cómo se propagan: qué capas la capturan, transforman, o re-lanzan
• Qué recibe el usuario: el mensaje de error final y el HTTP status code
• Qué se pierde: si hay errores que se silencian o loggean sin reportar

Generando error flows con Claude Code

# Prompt:
> "Usa Explore para rastrear qué pasa cuando el pago
   falla durante la creación de una orden. Desde el error
   en Stripe hasta la respuesta al usuario, incluyendo
   cualquier rollback o cleanup."

# Output esperado:
#
# 1. stripe.Charge.create() lanza stripe.CardError
#    Archivo: (librería externa stripe)
#    Datos: {"code": "card_declined", "message": "..."}
#
# 2. payment_service.py:charge() captura CardError
#    Transforma a: PaymentFailedError(reason="card_declined")
#    Loggea: logger.warning("Payment failed", extra={...})
#
# 3. order_service.py:create_order() captura PaymentFailedError
#    Ejecuta rollback:
#      - inventory_service.restore_stock(product_id, quantity)
#      - order_repo.update_status(order_id, "payment_failed")
#    Re-lanza: OrderError("Payment failed: card_declined")
#
# 4. api/routes/orders.py:create_order() captura OrderError
#    Retorna: HTTP 402 {
#      "error": "payment_failed",
#      "message": "Tu tarjeta fue rechazada",
#      "order_id": 789,
#      "status": "payment_failed"
#    }
#
# Hallazgo: Si el rollback de inventario falla, el error
# se loggea pero la orden queda en estado inconsistente
# (status=payment_failed pero inventario no restaurado).
# Esto es un bug potencial.

Valor del error flow: encontrar cómo se propagan errores frecuentemente revela bugs. En el ejemplo anterior, descubrimos que un fallo en el rollback deja datos inconsistentes — un finding que vale más que todo el analysis junto.

Visualizando Flujos con Mermaid

Generando diagramas con Claude Code

# Prompt:
> "Genera un diagrama mermaid de secuencia para el flujo
   de POST /api/orders (happy path)"

# Output esperado:
# ```mermaid
# sequenceDiagram
#     participant C as Cliente
#     participant R as Router
#     participant V as Validator
#     participant OS as OrderService
#     participant PS as PaymentService
#     participant DB as Database
#     participant ES as EmailService
#
#     C->>R: POST /api/orders
#     R->>V: validate(request)
#     V-->>R: OrderCreateRequest
#     R->>OS: create_order(request)
#     OS->>DB: check_inventory()
#     DB-->>OS: stock available
#     OS->>PS: charge(amount)
#     PS-->>OS: payment_id
#     OS->>DB: save_order()
#     DB-->>OS: order_id
#     OS->>ES: send_confirmation()
#     OS-->>R: Order(id=789)
#     R-->>C: HTTP 201 {order_id: 789}
# ```

Diagramas para error flows

# Prompt:
> "Genera un diagrama mermaid de secuencia para el flujo
   de POST /api/orders cuando el pago falla"

# Output esperado incluirá:
# PS--xOS: CardError
# OS->>DB: rollback_inventory()
# OS--xR: PaymentFailedError
# R-->>C: HTTP 402

Comparación: Análisis Manual vs Claude Code

Trade-off: El análisis manual da intuición profunda sobre el código (lo lees, lo entiendes visceralmente). Claude Code da completitud y velocidad. Lo ideal es usar Claude Code para el primer trace y luego leer manualmente las partes que te parecen críticas o sospechosas.

Conexión con Proyecto

En el Architecture Map que construirás en la cápsula 05, el flow analysis es el segundo componente principal:

• Dependency maps (cápsula 02) muestran la estructura estática
• Flow analysis (esta cápsula) muestra el comportamiento dinámico
• Pattern analysis (cápsula 04) identifica patrones y anti-patterns

Para el proyecto, necesitas al menos 2 flow traces de flujos críticos del codebase que estés analizando.

Troubleshooting

Problema 1: El trace es demasiado largo

Causa: El flujo pasa por muchas capas.

Solución: Pide el trace a diferentes niveles de zoom:

# Nivel alto (overview):
> "Trace del endpoint a nivel de servicios, sin detallar
   funciones internas de cada servicio"

# Nivel detallado (solo una sección):
> "Ahora detalla solo el paso de payment_service.charge():
   qué hace internamente paso a paso"

Problema 2: No encuentro el entry point

Causa: El codebase usa un framework con routing implícito.

Solución: Pide a Explore que encuentre el entry point primero:

> "¿Dónde está definido el endpoint POST /api/orders?
   ¿Qué archivo y función maneja ese request?"

Problema 3: Side effects ocultos

Causa: El codebase usa eventos, signals, o decoradores que causan side effects no evidentes.

Solución: Pregunta específicamente:

> "¿Hay event listeners, signals de Django, o decoradores
   que se ejecutan cuando se crea una orden? Incluye
   side effects que no son llamados directamente."

Problema 4: El error flow no muestra rollback

Causa: No hay rollback implementado (posible bug).

Solución: Documéntalo como finding:

"Hallazgo: Cuando charge() falla después de reducir
inventario, no hay rollback automático del inventario.
Esto puede causar inconsistencia de datos."

Ejercicios

Ejercicio 1: Identificar tipo de flujo (Fácil)

Para cada pregunta, indica qué tipo de flow analysis usarías (request flow, data flow, o error flow):

1. "¿Cómo se procesa un request de login?"
2. "¿Qué pasa con el JSON del cliente antes de guardarse en la DB?"
3. "¿Qué ocurre cuando la DB está caída?"
4. "¿Cuántas funciones se ejecutan para generar un reporte?"
5. "¿Cómo cambia el formato de la fecha a lo largo del sistema?"

Ejercicio 2: Escribir prompts de flow analysis (Fácil)

Escribe un prompt de Claude Code para cada tipo de flujo, aplicado a un sistema de e-commerce:

# Request flow:
> "Usa Explore para rastrear el flujo completo de
   POST /api/cart/checkout. Desde el request del usuario
   hasta la respuesta HTTP, lista cada función que se
   ejecuta con su archivo y propósito."

# Data flow:
> "Usa Explore para rastrear cómo se transforman los datos
   del carrito de compras desde que el usuario hace click
   en 'Comprar' hasta lo que se guarda como Order en la DB.
   En cada paso, muestra la estructura de los datos."

# Error flow:
> "Usa Explore para rastrear qué pasa cuando un item
   del carrito se queda sin stock durante el checkout.
   ¿En qué punto se detecta, cómo se propaga el error,
   y qué respuesta recibe el usuario?"

Ejercicio 3: Trace multi-nivel (Medio)

Diseña una secuencia de 3 prompts para analizar el flujo de "password reset" a tres niveles de zoom: overview, detalle del servicio, y detalle del envío de email.

# Nivel 1 — Overview:
> "Usa Explore para rastrear el flujo de password reset
   a nivel de servicios. Solo los pasos principales:
   request → procesamiento → email → confirmación."

# Nivel 2 — Detalle del servicio:
> "Profundiza en el paso de auth_service.initiate_reset().
   ¿Qué token genera, cómo lo almacena, y cuánto dura?
   ¿Verifica rate limiting?"

# Nivel 3 — Detalle del email:
> "Profundiza en el envío del email de reset. ¿Qué
   template usa, qué datos incluye, y cómo se construye
   el link de reset? ¿Hay retry si el envío falla?"

Ejercicio 4: Encontrar bugs con error flow (Medio)

Escribe un prompt para encontrar posibles bugs en el manejo de errores de un sistema de pagos. El prompt debe pedir a Explore que identifique escenarios donde un error podría dejar datos en estado inconsistente.

> "Usa Explore para analizar el error handling del flujo
   de pagos. Para cada paso que puede fallar (validación,
   charge, save_order, send_email), verifica:
   1. ¿Se captura el error?
   2. ¿Se hace rollback de los pasos anteriores?
   3. ¿Puede quedar datos inconsistentes si falla a
      mitad de camino?
   4. ¿El usuario recibe un mensaje claro del error?
   Lista cualquier escenario donde un fallo pueda dejar
   la orden o el inventario en estado inconsistente."

Ejercicio 5: Flow analysis completo (Difícil)

Elige un endpoint de un proyecto real y produce los 3 tipos de flow analysis (request, data, error). Documenta los prompts y resultados.

# Request flow:
> "Rastrear POST /api/users: secuencia de funciones,
   middleware incluido"
# Resultado: 7 pasos desde request hasta response

# Data flow:
> "Rastrear cómo se transforman los datos de POST /api/users:
   JSON input → validación → procesamiento → DB → response"
# Resultado: 5 transformaciones de datos con estructura en cada paso

# Error flow:
> "Rastrear qué pasa en POST /api/users cuando:
   a) email ya existe, b) password muy corto,
   c) DB connection timeout"
# Resultado: 3 error paths con HTTP status codes y mensajes

# Hallazgos:
# - El password se loggea en modo DEBUG (seguridad)
# - No hay rate limiting en registro (abuse potential)
# - El error de DB timeout retorna 500 genérico sin retry

Resumen

En esta cápsula aprendiste:

• Tres tipos de flow analysis: request flow (secuencia de ejecución), data flow (transformación de datos), error flow (propagación de errores)
• Request flow revela las capas de procesamiento, lógica de negocio, y side effects de un endpoint
• Data flow muestra cómo se transforman los datos en cada paso — esencial para saber dónde hacer cambios
• Error flow descubre bugs potenciales: datos inconsistentes, errores silenciados, rollbacks faltantes
• Claude Code genera diagramas mermaid directamente, evitando herramientas externas
• Los flujos complementan los dependency maps: estructura (estática) + flujos (dinámica) = comprensión completa

Próxima cápsula: Pattern Identification y Anti-Pattern Detection. Vas a aprender a reconocer patrones arquitecturales (MVC, service layer, repository) y anti-patterns (god objects, circular dependencies) usando Claude Code.

Recursos Adicionales

1. Mermaid Sequence Diagrams - Sintaxis de diagramas de secuencia que Claude Code genera
2. Data Flow Diagrams - Martin Fowler - Fundamentos de análisis de flujo de datos
3. Error Handling Patterns - Patterns of Enterprise Application Architecture (Fowler)
4. Request Tracing - OpenTelemetry - Herramientas de tracing que complementan el análisis manual
5. Python Exception Hierarchy - Referencia de excepciones de Python
6. Debugging with Data Flow Analysis - Fundamentos académicos de data flow analysis