Módulo 8: Proyecto Integrador — Migración de Proyecto Legacy Real
Onboarding y Architecture Analysis del Proyecto Legacy
Onboarding y Architecture Analysis del Proyecto Legacy
Descripción de la cápsula
Con el assessment completo (cápsula 01), tienes una foto inicial del proyecto legacy: tamaño, stack, tech debt prioritario, health score. Eso te dice qué arreglar. Esta cápsula te enseña a entender el proyecto a profundidad — el dónde y el cómo — antes de tocar nada.
Vas a aplicar las técnicas de Phase 1 (Módulos 1-3) al proyecto que asseseaste: onboarding sistemático con las 5 preguntas (M1), exploración profunda con Explore subagent (M2), y generación de architecture map con dependency maps + flow analysis + pattern identification (M3). Ya practicaste cada técnica aislada — aquí las orquestas en un único documento integrado.
El output de esta cápsula es un Architecture Analysis Document completo. Es el input directo de la cápsula 03 (migration planning): los anti-patterns informan qué refactorizar, los dependency maps informan el orden, y los flow traces informan dónde poner tests de regresión.
Al terminar, vas a poder producir un Architecture Analysis profesional aplicando M1-M3 en secuencia, identificar los puntos de cambio prioritarios con evidencia, y entregar un documento que un arquitecto senior reconocería como riguroso.
Por Qué Onboarding y Architecture VAN Antes que Cualquier Cambio
Es tentador empezar a refactorizar inmediatamente — "ya leí el assessment, ya sé qué hay que cambiar". Pero el assessment es una vista de 30K pies. Para tomar decisiones de migración, necesitas la vista de 100 pies.
ASSESSMENT (cápsula 01) te dice:
→ "Hay lógica en route handlers" (problema general)
→ "Sin tests" (estado de cobertura)
→ "Dead code" (cantidad estimada)
ARCHITECTURE ANALYSIS (esta cápsula) te dice:
→ "Hay 23 handlers con lógica de negocio. Los 5 más complejos son:
/payments, /orders, /reports, /auth, /admin — y comparten 4 funciones
helper que deberían ir a un service layer"
→ "El flujo de /payments toca 8 archivos en este orden: ...
Tests deberían cubrir esos 8 puntos"
→ "Los 'dead' callbacks de notifications.py están registrados como
handlers dinámicos en config.py — NO están muertos"
La diferencia es accionable vs general. Sin architecture analysis, refactorizas con la vista del assessment — adivinando dónde poner el bisturí. Con architecture analysis, tienes coordenadas exactas.
Paso 1: Onboarding Sistemático (M1)
Las 5 preguntas iniciales
Aplicamos las 5 preguntas del Módulo 1 al codebase específico:
> "Aplica el onboarding sistemático a este proyecto.
Para cada una de estas 5 preguntas, da la respuesta con
referencias a archivos específicos y números de línea
cuando aplique:
1. ¿Cuál es la estructura de directorios y qué hace cada carpeta?
2. ¿Cuáles son los entry points (main.py, app.py, wsgi.py, etc.)?
3. ¿Cómo fluyen los datos desde el input hasta la respuesta
(al menos para el flujo principal)?
4. ¿Qué patterns arquitecturales se usan (MVC, service layer,
repository, etc.)? ¿Son consistentes?
5. ¿Dónde está el tech debt más visible? Da los 3-5 ejemplos
más representativos con archivo y línea."
Documentar hallazgos: Onboarding Doc
Produce un onboarding doc breve (1-2 páginas) que se incorpora al Architecture Analysis Document final:
## Onboarding Summary
### Estructura de Directorios
- `app/` — Flask application code
- `routes/` — 23 route handlers (con lógica mezclada)
- `models/` — 12 SQLAlchemy models
- `utils/` — funciones helper sin organización clara
- `tests/` — DIRECTORIO VACÍO ⚠️
- `requirements.txt` — 14 dependencias, 2 deprecated
### Entry Points
- `app.py` — Flask factory, registra blueprints
- `wsgi.py` — gunicorn entry point para deployment
- `manage.py` — CLI commands para tareas administrativas
### Data Flow Principal (Compra de un producto)
1. POST `/api/orders` → `routes/orders.py:create_order()`
2. Valida payload → `utils/validators.py:validate_order_payload()`
3. Crea Order → `models/order.py:Order.__init__()`
4. Cobra → `routes/orders.py:_charge_card()` (lógica inline)
5. Notifica → `utils/notifications.py:send_order_email()`
6. Retorna response → `routes/orders.py:create_order()` (200 o 400)
### Patterns Observados
- ❌ NO hay service layer (lógica en handlers)
- ✅ Repository implícito vía SQLAlchemy ORM
- ❌ Validación esparcida (validators.py + inline + Pydantic-ish ad-hoc)
- ❌ No hay manejo central de errores
### Tech Debt Visible (top 3)
1. `routes/orders.py:50-150` — 100 líneas de lógica de cobro inline
2. `utils/notifications.py:1-200` — funciones similares duplicadas para email/SMS/push
3. `routes/admin.py:230-380` — handler god con 7 responsabilidades distintasPaso 2: Exploración con Explore (M2)
Una vez tienes el panorama del onboarding, profundiza con Explore para preguntas específicas que el onboarding general no responde.
Investigación profunda con Explore
> "Usa Explore (read-only) para investigar 4 preguntas específicas:
1. ¿Cómo se maneja la autenticación end-to-end?
Traza de request entrante → identificación de usuario → autorización.
2. ¿Qué dependencias tiene cada módulo?
Para cada archivo en app/, lista qué importa y qué lo importa.
3. ¿Hay lógica duplicada entre módulos?
Busca funciones con cuerpo similar (>70% similitud) en archivos distintos.
4. ¿Dónde están los posibles problemas de seguridad?
SQL injection candidates, hardcoded secrets, validación faltante,
manejo de errores que filtra info."
Aplica los tres patrones de exploración del Módulo 2
| Patrón | Cuándo usarlo en este proyecto |
|---|---|
| Top-Down | Para entender la estructura general primero, antes de zoom in |
| Feature-Tracing | Para mapear el flujo de las features principales (orders, payments, auth) |
| Dependency-Following | Para entender qué módulos están acoplados y cuáles son independientes |
El output de Explore se incorpora al Architecture Analysis Document como contexto profundo del onboarding.
Paso 3: Architecture Map (M3)
Con onboarding + exploración profunda en mano, generas los 3 componentes del Architecture Map del Módulo 3.
Componente 1: Dependency Map
> "Genera un dependency map del proyecto mostrando los módulos principales
y sus dependencias. Formato Mermaid. Marca:
- Módulos con muchas dependencias entrantes (riesgo alto al modificar)
- Módulos con muchas dependencias salientes (candidatos a service layer)
- Dependencias circulares (anti-pattern crítico)"
Ejemplo de output esperado:
graph LR
routes/orders --> utils/validators
routes/orders --> models/order
routes/orders --> utils/notifications
routes/admin --> models/order
routes/admin --> utils/notifications
utils/notifications --> models/user
models/order --> models/user
style routes/orders fill:#f99
style utils/notifications fill:#ff9
(routes/orders en rojo = alto fan-out, candidato a refactoring; utils/notifications en amarillo = alta reutilización, candidato a service layer.)
Componente 2: Flow Analysis
> "Traza el flujo completo del endpoint más importante del proyecto
(típicamente: el que toca el dinero o el dato más crítico).
Step-by-step con archivos y funciones. Identifica:
- Cada función involucrada
- Los puntos donde se mezcla lógica de negocio con I/O
- Los puntos donde se debería poner test de regresión"
Ejemplo:
## Flow Analysis: POST /api/orders
| Step | File | Function | Tipo | Test Point |
|------|------|----------|------|------------|
| 1 | routes/orders.py | create_order | Handler + Lógica mezclada | ✅ Sí (input/output) |
| 2 | utils/validators.py | validate_order_payload | Validación pura | ✅ Sí (unit) |
| 3 | models/order.py | Order.__init__ | Lógica de dominio | ✅ Sí (unit) |
| 4 | routes/orders.py | _charge_card | Lógica de pago inline | ✅ Sí (CRÍTICO — toca dinero) |
| 5 | external | Stripe API | I/O externo | Mock obligatorio |
| 6 | utils/notifications.py | send_order_email | I/O externo | Mock |
| 7 | routes/orders.py | (return) | Response building | ✅ Sí (integration) |
**Puntos de cambio identificados:**
- Step 1: extraer create_order a service layer
- Step 4: mover _charge_card a payment_service
- Step 6: abstraer notification interfaceComponente 3: Pattern + Anti-Pattern Analysis
> "Identifica patterns arquitecturales (si los hay) y anti-patterns.
Lista cada uno con:
- Ubicación (archivo:línea)
- Severidad (alta/media/baja)
- Acción sugerida
- Conexión con migración (¿abordar ahora? ¿documentar como deuda
remanente?)"
Ejemplo:
## Pattern Analysis
| Pattern | Dónde | Consistencia |
|---------|-------|-------------|
| Repository (vía ORM) | models/* | ✅ Consistente |
| Validation | utils/validators.py | ⚠️ Parcial (50% de handlers la usan) |
| Service Layer | — | ❌ Ausente |
| Error Handler centralizado | — | ❌ Ausente (cada handler maneja sus errores) |
## Anti-Patterns Found
| # | Anti-Pattern | Ubicación | Severidad | Acción |
|---|-------------|-----------|-----------|--------|
| 1 | Lógica en handlers | routes/orders.py:50-150 | ALTA | Extraer a service (cápsula 04) |
| 2 | God class | routes/admin.py:230-380 | ALTA | Split en 3-4 handlers (cápsula 04) |
| 3 | Duplicación | utils/notifications.py:1-200 | MEDIA | Refactor a interface (cápsula 04) |
| 4 | Hardcoded secrets | config.py:45 | CRÍTICA | Mover a env vars (cápsula 03) |
| 5 | except Exception genérico | varios | MEDIA | Excepciones específicas (M7 cápsula 03) |
| 6 | Dead code apariencia | utils/legacy.py | BAJA | Verificar dynamic dispatch antes |Entregable: Architecture Analysis Document
Combina onboarding + Explore findings + architecture map en un único documento:
# Architecture Analysis: [Proyecto]
> Output combinado de Onboarding (M1) + Exploración (M2) + Architecture Map (M3)
> Aplicado al proyecto del assessment de la cápsula 01
---
## 1. Onboarding Summary
[Las 5 preguntas respondidas con referencias a archivos]
## 2. Exploración Profunda (Explore)
[Hallazgos de las 4 preguntas adicionales]
## 3. Dependency Map
[Diagrama Mermaid + comentarios sobre módulos críticos]
## 4. Flow Analysis
[Trace del flujo principal — típicamente "money path" o "data crítico"]
[Trace de al menos 1 flujo secundario importante]
## 5. Pattern Analysis
[Tabla de patterns observados con consistencia]
## 6. Anti-Patterns Found
[Tabla de anti-patterns con severidad y acción sugerida]
## 7. Architecture Map: BEFORE
[Diagrama del estado actual]
## 8. Key Findings
1. [Finding más importante con evidencia]
2. [Segundo finding con evidencia]
3. [Tercer finding con evidencia]
## 9. Implicaciones para la Migración
- Qué refactorizar primero (alta severidad + bajo riesgo)
- Dónde poner tests de regresión (puntos críticos del flow)
- Qué documentar como tech debt remanente (no abordable en este scope)Este documento es el input directo de la cápsula 03 (Migration Planning). Cada decisión del plan de migración va a referenciar findings específicos de aquí.
Conexión con Siguiente Cápsula
El Architecture Map que produces aquí es el input directo de la cápsula 03 (Migration Planning):
- Los anti-patterns informan qué refactorizar (orden de la cápsula 04)
- Los dependency maps informan el orden de los cambios (qué tocar primero para minimizar ripple)
- Los flow traces informan dónde poner tests de regresión (cápsula 03)
- Los patterns ausentes (service layer, error handler) informan qué introducir vs qué mejorar
Trampas a Evitar en Esta Cápsula
Cinco errores comunes al ejecutar onboarding + architecture sobre un proyecto real.
1. Saltar onboarding "porque ya lei el assessment"
El assessment (cápsula 01) te da scores y categorías. El onboarding te da el mapa real. Sin onboarding, las decisiones de refactoring son adivinanza educada. Invierte el tiempo aquí — se recupera 5× en la ejecución.
2. Hacer Explore "general" en lugar de preguntas específicas
Explore funciona mejor con preguntas dirigidas. "Explora el código" produce respuestas vagas. "¿Cómo se maneja autenticación end-to-end con archivo y línea?" produce respuestas accionables. La cápsula 02 del Módulo 2 te dio la diferencia — aquí la aplicas.
3. Incluir todo en el Architecture Map y sobrecargar el documento
El Architecture Map es selectivo. Incluye los módulos importantes (alto fan-out, alta criticidad) y los anti-patterns severos. Si tu diagrama tiene 80 nodos, no es útil — está crudo. La regla: "puede un colega entender el proyecto leyendo SOLO este doc en 15 minutos?"
4. No conectar findings con acciones de migración
Cada anti-pattern en tu lista debe terminar con acción sugerida: "extraer a service layer en cápsula 04", "documentar como deuda remanente", "verificar antes de eliminar". Sin acción, los findings son crítica vacía. Con acción, son el plan que ejecutas en cápsulas 03-05.
5. Confundir "dead code" con "código sin uso aparente"
Antes de marcar algo como dead, verifica dynamic dispatch (Módulo 7 trampa #3): callbacks registrados, rutas con strings, imports dinámicos. Si tu Architecture Map dice "dead code: legacy.py", revisa una vez más. Eliminar callbacks vivos en la cápsula 04 es el bug más caro de este proyecto.
Diagnóstico: ¿Está Listo Tu Architecture Analysis?
Cinco preguntas para verificar antes de pasar a la cápsula 03.
Pregunta 1: ¿Tu Onboarding Summary tiene referencias a archivos:línea o solo descripciones generales?
Si tiene referencias: vas bien. Las decisiones del plan se pueden trazar.
Si solo descripciones: vuelve al Paso 1 — sin referencias, las decisiones del plan son vagas.
Pregunta 2: ¿Tu Dependency Map identifica los 2-3 módulos con mayor fan-in y fan-out?
Si sí: sabes dónde tocar y dónde no tocar.
Si no: los nodos rojos/amarillos del diagrama deben estar marcados — son los que más impactan al refactorizar.
Pregunta 3: ¿El Flow Analysis del flujo principal identifica al menos 5 puntos de test de regresión?
Si sí: la cápsula 03 (safety nets) tiene su input.
Si no: profundiza el flow analysis — sin puntos identificados, los tests serán insuficientes.
Pregunta 4: ¿Tu lista de Anti-Patterns tiene severidad y acción sugerida para cada uno?
Si sí: la cápsula 03 (plan) y 04 (ejecución) tienen su roadmap.
Si no: completa la columna acción — sin ella, los anti-patterns no se traducen en migración.
Pregunta 5: ¿Podrías darle este documento a un colega y que entienda el proyecto en 15 minutos?
Si sí: está al nivel profesional.
Si no: edita. Probablemente sobre detalle o falten resúmenes ejecutivos al inicio de cada sección.
Si dudaste en 2 o más: itera el documento antes de pasar a la cápsula 03. La calidad del Architecture Analysis determina la calidad del plan, y la calidad del plan determina la calidad de la migración. Es la cápsula con mayor leverage del proyecto.
Troubleshooting
El proyecto es demasiado grande para analizar completo
Usa context management (M6): analiza por módulos, genera CLAUDE.md para dar contexto persistente, y aplica chunking strategy (feature, layer, o module). Documenta solo los módulos en scope de la migración — no todo el codebase.
No hay patterns claros
Documéntalo. "Arquitectura orgánica sin patterns claros" es un finding válido que informa la strategy de refactoring (probablemente: introducir un patterns simple como service layer en lugar de mantener consistencia con un pattern inexistente).
El dependency map es un mess (muchas dependencias circulares)
Es normal en legacy code. Documéntalo tal cual — los circular dependencies y el high coupling son exactamente lo que vas a refactorizar. Marca los ciclos en el diagrama como prioridad alta para la cápsula 04.
El "money path" o "flujo crítico" no es obvio
Pregunta a alguien del equipo (o, si es open-source, lee issues y PRs históricos). Si nadie lo sabe, documenta los 2-3 candidatos más probables y marca los 3 para safety net. Mejor sobre-cubrir el flujo crítico que asumir cuál es.
Resumen
- Esta cápsula aplica M1+M2+M3 al proyecto del assessment, en secuencia
- El output es un Architecture Analysis Document integrado
- Sin este documento, la migración es adivinanza educada
- Conecta cada anti-pattern con una acción específica de migración
- Verifica dinámicamente antes de marcar código como dead
- El doc debe ser legible por un colega en 15 minutos
Siguiente cápsula: 03 — Migration Planning + Safety Nets — usas este Architecture Analysis para crear el plan de migración con phases, checkpoints, y los tests de regresión que protegen los cambios. Sin este doc bien hecho, la cápsula 03 no se puede ejecutar correctamente.
Recursos Adicionales
- Software Architecture: The Hard Parts - Neal Ford et al. - Análisis arquitectural en sistemas distribuidos y monolitos
- C4 Model - Framework para diagramas de arquitectura (Context, Containers, Components, Code)
- Mermaid Documentation - Sintaxis para diagramas en markdown (usado en este módulo)
- Building Evolutionary Architectures - Ford, Parsons, Kua - Arquitecturas que evolucionan, marco para legacy
- Working Effectively with Legacy Code - Michael Feathers - Capítulos 7-10: cómo entender código legacy
- Claude Code Documentation - Referencia oficial