Mapa de arquitectura de una página para un prototipo desordenado: un método práctico

Por qué los prototipos desordenados son difíciles de arreglar sin un mapa

Un prototipo desordenado confunde de una manera muy específica. Nada está etiquetado, los nombres de las carpetas suenan importantes pero no significan nada, y el comportamiento real se oculta tras helpers y fragmentos copiados. Haces clic en un botón en la UI y se disparan tres llamadas API, se ejecuta un trabajo en segundo plano y aparecen datos en una tabla que parece llenarse desde otra parte.

Cuando intentas arreglar problemas en un repositorio así, acabas adivinando. Adivinar es caro por dos razones: pierdes tiempo persiguiendo el archivo equivocado y creas nuevos bugs cuando cambias algo que parecía no usarse pero que silenciosamente mantenía viva la app.

Un mapa de arquitectura de una página ayuda porque le da a todo el mundo la misma imagen de cómo funciona básicamente la app. No es un diagrama perfecto ni documentación para cada clase. Es una referencia compartida para que el equipo pueda hablar de lo mismo.

Sin un mapa, las correcciones a menudo se convierten en:

• cambiar código cerca del bug y luego descubrir que la causa real está dos pasos antes
• parchear el mismo problema en varios lugares porque la lógica está duplicada
• romper autenticación, pagos o emails porque un cambio “pequeño” tocó middleware compartido
• olvidar dependencias externas como webhooks, colas o almacenamiento de terceros

Este enfoque es especialmente útil cuando la base de código es heredada, apresurada o generada por herramientas que producen demos funcionales con estructura inestable. Muchos prototipos generados por IA entran en esta categoría: los flujos son implícitos y secretos, autenticación y reglas de datos están dispersas.

Un ejemplo rápido: un fundador informa “iniciar sesión funciona en local, falla en producción.” Sin un mapa, es fácil fijarse en el formulario de login. Con un mapa, ves todo el camino: UI -> ruta de auth -> búsqueda en la base de datos -> cookie o token establecido -> comprobación de middleware en la siguiente petición. Esa vista suele mostrar dónde se rompe realmente el flujo.

Qué hace útil a un mapa de arquitectura de una página

Un mapa de arquitectura de una página funciona cuando alguien puede leerlo en 60 segundos y decir: “Sí, así es como funciona.” Una vez que todos coinciden en la historia, se deja de discutir por conjeturas y se empieza a probar los pasos correctos.

Los mejores mapas usan palabras simples. En lugar de nombres de carpeta como src/services/authV2, etiqueta una caja “Inicio de sesión y sesiones.” En lugar de api/routes, etiqueta “Endpoints HTTP.” Esto mantiene el mapa legible para compañeros no técnicos y te obliga a nombrar lo que el código realmente hace.

Un mapa de una página también evita la sobredocumentación. Muestras solo los caminos que importan para el negocio y para los bugs que persigues. La mayoría de los prototipos tienen algunos recorridos críticos; todo lo demás puede esperar.

Empieza con los flujos que suelen decidir si la app funciona:

• inicio de sesión y creación de cuentas
• el flujo central (lo principal por lo que vinieron los usuarios)
• pagos (si cobras)
• emails, notificaciones o webhooks
• subidas y descargas (si hay archivos involucrados)

Las flechas vencen a los párrafos. Una flecha debe responder: quién llama a quién, qué datos entran y qué sale. “Navegador -> API -> Base de datos” más una nota como “crea registro de usuario” suele ser más útil que una página de texto.

Recoge pistas rápidas antes de leer mucho código

Cuando un prototipo tiene poca o ninguna documentación, tu primer trabajo no es entender cada función. Tu primer trabajo es aprender qué dice hacer la app, de qué depende y dónde toca el mundo exterior.

Empieza con los archivos que “delatan” el proyecto. Un README (aunque sea malo) puede mencionar las funciones principales, la configuración de hosting o problemas conocidos. Archivos de dependencias como package.json, requirements.txt o lockfiles revelan rápidamente el framework, controladores de base de datos, librerías de autenticación, herramientas de jobs en segundo plano y SDKs de pago o email.

Luego revisa cómo obtiene configuración la app. Busca .env.example, plantillas de config, archivos Docker y notas sobre secretos. Aquí a menudo descubres claves faltantes, URLs de callback incorrectas o tokens hardcodeados que funcionan localmente y fallan tras el despliegue.

Si quieres una lista rápida, concéntrate en:

• Dónde se ejecuta: framework y runtime (desde archivos de dependencias)
• Cómo entran las peticiones: páginas, endpoints API, webhooks, tareas programadas
• Dónde viven los datos: migraciones, archivos de esquema, scripts seed, modelos ORM
• Con quién habla: autenticación, pagos, email, almacenamiento de archivos, analytics
• Cómo se supone que se ejecuta: configs de despliegue, archivos CI, scripts de “start”

Ejemplo: una app generada por IA “funciona en local”, pero los usuarios no pueden iniciar sesión en producción. Antes de leer código a fondo, detectas un SDK de auth en package.json, URLs de callback en la plantilla de env y una ruta /api/auth que espera un SECRET faltante. Eso basta para esbozar la cadena clave y marcar un riesgo real si los secretos están expuestos.

Encuentra los puntos de entrada y los flujos principales de usuario

Si empiezas a mapear desde archivos aleatorios, te perderás cómo la gente realmente usa la app. Empieza desde puntos de entrada: los primeros lugares donde un usuario real o un sistema toca tu código.

Comienza con puntos de entrada de usuario

Busca las pantallas que generan más cambios de estado: landing, registro/inicio de sesión, la pantalla principal de trabajo y cualquier área de administración. Incluso en un prototipo desordenado, estos flujos suelen revelar los objetos de datos clave (usuarios, proyectos, pagos, archivos) y las decisiones importantes (logueado vs no, gratis vs pago, acceso por roles).

Una forma práctica de confirmar el flujo es seguir lo que pasa tras hacer clic en un botón: a dónde envía al usuario, qué llamada API se dispara y qué se almacena (cookie, sesión, local storage, fila en la base de datos).

Luego captura puntos de entrada técnicos

En paralelo, lista cada puerta de entrada al backend. A menudo son la razón por la que los prototipos fallan en producción.

• rutas y páginas de UI (incluyendo admin)
• rutas API (REST/GraphQL), acciones del servidor, funciones en el edge
• callbacks de auth (redirecciones OAuth, enlaces mágicos)
• webhooks de socios (pagos, proveedor de email, CRM)
• automatizaciones (cron jobs, colas, tareas programadas)

Los llamantes externos también importan. Un navegador no es el único cliente; una app móvil, una herramienta interna de admin o un sistema de un socio pueden llamar a los mismos endpoints con suposiciones distintas.

Ejemplo: una app generada por IA puede permitir “Iniciar sesión” en localhost, pero en producción la URL de callback de OAuth apunta al dominio equivocado. Marca ese callback como punto de entrada y añade una nota junto a él: “Debe coincidir con la URL desplegada, de lo contrario bucle de login.”

Lista los módulos clave sin perderte en las carpetas

Los prototipos desordenados a menudo parecen más grandes de lo que son. Una forma rápida de tomar el control es agrupar el código por lo que hace, no por dónde está en el árbol de carpetas. Tu objetivo es un pequeño conjunto de módulos que quepan en una página.

Empieza buscando “pozos de gravedad”: archivos que muchos otros importan o llaman. Normalmente revelan los límites reales del módulo, incluso cuando la estructura del repo es aleatoria.

Un inventario simple de módulos es:

• UI: páginas, componentes, formularios y dónde se disparan las solicitudes de red
• Superficie API: handlers de rutas, controladores, middleware, validación de peticiones
• Lógica de negocio: flujos como “crear cuenta” o “checkout”, junto con jobs en segundo plano
• Acceso a datos: modelos ORM, consultas crudas, migraciones, caching, subidas de archivos
• Integraciones: autenticación, pagos, email/SMS, analytics, logs

Después de tener estos buckets, asigna archivos rápidamente. Si un archivo parece pertenecer a dos sitios, márcalo como “límite” y sigue. Los archivos límite son donde a menudo se esconden los bugs (por ejemplo, componentes de UI que construyen filtros inseguros o rutas API que contienen reglas de pago).

Ejemplo: un app generada por IA puede tener una carpeta utils con 40 archivos. Al revisar el uso, puedes encontrar varios grupos que en realidad son “envío de email”, “helpers de auth” y “formateo de datos”. Esos grupos son tus módulos, aunque las carpetas no coincidan.

Método paso a paso para esbozar el mapa desde el código

Un buen mapa de arquitectura de una página se construye a partir del comportamiento real, no de nombres de carpetas. El método más rápido es elegir un flujo, seguirlo de extremo a extremo y dibujar solo lo que puedes probar.

Empieza con un flujo que puedas rastrear

Elige un flujo central con inicio y fin claros, como registro hasta la primera acción exitosa (crear un proyecto, subir un archivo, hacer un pedido). Encuentra el primer punto de entrada de ese flujo: una página, ruta, controlador o endpoint API.

Luego sigue cada salto en orden y convierte cada salto en una caja. No te preocupes por nombres perfectos. Usa lo que el código llame (por ejemplo, auth.ts, createProject, POST /api/upload). Si no puedes seguir un salto, para y márcalo como “desconocido” en lugar de adivinar.

Junto a cada caja captura unos pocos esenciales:

• qué lo dispara (clic de botón, llamada API, cron job, webhook)
• qué devuelve (redirect, JSON, URL de archivo, error)
• dónde cambia el estado (tabla BD, cookie, local storage)
• el riesgo o suposición principal (falta de validación, confiar en input del cliente)

Añade servicios y límites de confianza como formas separadas

Los servicios externos merecen sus propias cajas porque fallan distinto que tu código. Los comunes: proveedores de auth, procesadores de pagos, email/SMS, almacenamiento de objetos, analytics.

Marca los límites de confianza con etiquetas simples en las aristas, como “navegador a servidor” y “servidor a tercero.” Esto te ayuda a detectar dónde cruzan secretos, tokens y datos personales a sitios que no controlas.

Repite el mismo método para dos o tres flujos críticos hasta que la página se sienta “llena” pero todavía legible. Login, restablecimiento de contraseña y la acción principal de crear o pagar suelen ser suficientes.

Añade notas de seguridad y de protección de datos mientras mapeas

Un mapa de arquitectura de una página no es solo cajas y flechas. Añade pequeñas notas de seguridad directamente en el dibujo mientras el código está fresco en tu cabeza. Estas notas suelen explicar por qué un prototipo funciona en modo demo pero falla (o se vuelve peligroso) en producción.

Empieza por la autenticación. Marca dónde ocurre el login, qué crea la sesión o token y qué endpoints dependen de ello. Si hay restablecimiento de contraseña u OAuth, anota la ruta de callback y dónde la app almacena estado (cookies, local storage, sesión en servidor).

Luego busca secretos. Anota dónde viven las claves API y cadenas de conexión y dónde podrían filtrarse. En prototipos desordenados, las claves a menudo acaban en código cliente, archivos de config comiteados, logs de depuración o mensajes de error.

Después sigue la entrada del usuario al sistema. Etiqueta cada límite donde aparece dato no confiable: formularios, query strings, webhooks, subidas de archivos, callbacks de terceros. Añade una nota: “validado en servidor” o “solo UI”.

Para seguridad de la base de datos, marca dónde se construyen las consultas. Si ves SQL crudo, filtros dinámicos o concatenación de cadenas, señalízalo en el mapa. Es una fuente común de inyección SQL y filtrado de datos.

Finalmente, anota permisos. Una ruta detrás de “auth” no es lo mismo que estar autorizada. Marca dónde se hacen comprobaciones de rol, cheques de pertenencia (el usuario puede ver solo sus registros) y acciones solo admin.

Si necesitas una lista corta de verificación para anotar, usa:

• tipo de auth y dónde se verifica
• dónde viven los secretos y si alguno está expuesto
• dónde se valida la entrada
• cómo se consulta la BD (ORM vs SQL crudo)
• dónde se aplican reglas de autorización

Errores comunes que vuelven engañoso al mapa

El objetivo es claridad, no exhaustividad. La forma más rápida de arruinar un mapa de una página es tratarlo como un índice de archivos. Terminas con una página densa que aún no explica el comportamiento de la app.

Otra trampa es nombrar cajas por herramientas en lugar de por comportamiento. “Next.js + tRPC + Prisma” le dice a un desarrollador qué usaste, pero no qué sucede cuando un usuario inicia sesión, sube un archivo o paga. Un mapa debe leerse como una historia simple: quién llama a qué, qué datos se mueven y qué puede fallar.

Errores comunes:

• dibujar cada carpeta y perder los pocos flujos que importan (inicio de sesión, pagos, acciones de admin, onboarding)
• nombrar cajas por stacks tecnológicos en lugar de acciones (“Crear factura” supera a “Servicio backend”)
• olvidar caminos silenciosos como cron jobs, colas y webhooks entrantes que solo fallan en producción
• mezclar entornos (mocks locales, claves falsas, servicios que no existen tras el despliegue)
• omitir el modelo de datos y luego preguntarse por qué la lógica de negocio se contradice entre pantallas

Las suposiciones no son el problema; las suposiciones ocultas sí. Si no estás seguro de si “los emails los envía el proveedor A” o “un job corre cada hora”, escríbelo como “asumido” o “desconocido.” Eso convierte la confusión en un to-do claro.

Chequeos rápidos antes de compartir el mapa

Antes de enviar el mapa a un compañero o cliente, haz una pasada rápida de sensatez. La meta no es la perfección. Es asegurarte de que la página dice la verdad y apunta a las preguntas correctas.

Intenta esto: ¿puedes explicar el flujo principal del usuario en menos de dos minutos usando solo lo que está en la página? Si sigues diciendo “y entonces pasa algo”, añade una caja o flecha faltante.

Cinco comprobaciones que atrapan la mayoría de problemas:

• cada servicio externo aparece en algún lugar (auth, email/SMS, pagos, almacenamiento, analytics)
• existe al menos una caja clara de “almacenamiento de datos” (base de datos, almacenamiento de objetos) con flechas de lectura/escritura
• los límites de confianza son visibles (cliente, tu servidor, terceros)
• los puntos de entrada son obvios (rutas, endpoints, jobs, webhooks)
• los riesgos principales son visibles (manejo de auth/sesiones, secretos, validación de entrada)

Después añade un pequeño rincón de “Desconocidos” con hasta cinco elementos. Hazlos específicos para que alguien pueda confirmarlos rápidamente.

Ejemplo: mapear un prototipo generado por IA que falla en producción

Un fundador hereda un prototipo de Bolt o Lovable que parece bien en localhost, pero se desmorona tras el despliegue. Los usuarios pueden abrir la landing, pero el registro falla y nadie puede iniciar sesión.

Empieza con una acción real de usuario: “Crear cuenta.” No necesitas cajas perfectas. Necesitas las pocas cajas que expliquen qué habla con qué y dónde cambian los datos.

Un mapa típico para esta situación incluye:

• UI del navegador (formulario de registro) llama a una acción del servidor o ruta API
• el código del servidor habla con un proveedor de auth y recibe un callback
• el servidor escribe una fila de usuario en la base de datos
• un servicio de email envía mensajes de verificación
• variables de entorno proporcionan claves y URLs de callback

Ahora rastrea el paso que falla en producción. La UI envía, el servidor redirige al proveedor de auth y el callback vuelve a un dominio distinto al esperado porque la URL de callback sigue apuntando a localhost. En peores casos, el bundle cliente contiene un secreto de auth porque se guardó en una variable de entorno pública.

Mientras mapeas, añade pequeñas notas de alerta que hagan obvias las primeras correcciones:

• secreto expuesto en la configuración del cliente
• falta de comprobaciones de rol o pertenencia en endpoints sensibles
• nombres de tablas inconsistentes (users vs user, profile vs profiles)
• callbacks de auth apuntando a localhost o al dominio equivocado

El resultado no es un diagrama bonito. Es claridad y un orden de reparaciones más seguro.

Próximos pasos: convertir el mapa en un plan de reparación

Un mapa de arquitectura de una página solo importa si cambia lo que haces después. Úsalo para convertir “arreglar bugs a ciegas” en un orden claro de trabajo, de modo que abordes primero los riesgos que bloquean.

Un orden práctico de correcciones para la mayoría de prototipos desordenados:

• estabilizar autenticación y sesiones (login, roles, almacenamiento de tokens, restablecimiento de contraseña)
• confirmar el modelo de datos (tablas, relaciones, migraciones, puntos de validación)
• reparar el flujo central del usuario (la acción que el producto debe completar de extremo a extremo)
• encargarse de extras (notificaciones, analytics, herramientas admin)

Después decide si parchear, refactorizar o reconstruir:

• Parchear cuando el flujo está claro y los problemas están aislados (una integración rota, unas pocas consultas malas).
• Refactorizar cuando la app funciona pero la estructura te dificulta los cambios (lógica duplicada, límites poco claros).
• Reconstruir cuando el mapa muestra arquitectura enredada (todo habla con todo, secretos están dispersos, no hay lugar seguro para añadir comprobaciones).

Mantén la página viva mientras reparas. Cada vez que muevas responsabilidades (por ejemplo, centralizar acceso a la base de datos o llevar comprobaciones de auth al middleware), actualiza el mapa para que el equipo no vuelva a las conjeturas.

Si quieres una segunda opinión sobre una base de código generada por IA, FixMyMess (fixmymess.ai) empieza con un diagnóstico del código y puede ayudar a reparar problemas como autenticación rota, secretos expuestos y acceso a datos inseguro antes de que inviertas tiempo en reescrituras.