Las apps web preparadas para API son más fáciles de escalar después de un PoC
Una app web de PoC no necesita una arquitectura enterprise completa. Pero no debe construirse de una forma que bloquee el siguiente paso.
La mejor primera versión mantiene acotado el flujo de trabajo del usuario mientras hace visibles los límites de datos y los supuestos de integración. "Alcance acotado" y "arquitectura desechable" no son lo mismo: la primera decisión es mantener el alcance visible pequeño; la segunda, mantener el interior lo bastante limpio para que ese alcance pueda crecer.
Qué significa estar preparado para API
Estar preparado para API no siempre significa que todas las integraciones estén completas. Significa que el primer sprint deja claro por dónde entran los datos, dónde se toman las decisiones y adónde tendrán que ir las salidas más adelante.
Eso suele incluir:
Fuentes de datos con nombre
Modelos de entrada y salida claros
Límites de API simulados o reales
Logging de las acciones importantes
Supuestos de errores y reintentos
Notas para la preparación de cara a producción
Algunas decisiones de ingeniería que se amortizan de forma desproporcionada, incluso en un PoC de 2 semanas:
Modelos tipados en los límites. Define las formas de entrada y salida como esquemas (Pydantic, Zod, TypeBox, JSON Schema) desde el primer commit. El modelo es el contrato; todo lo demás es implementación.
Clases de repositorio o servicio por sistema externo. Incluso cuando el sistema está simulado, la interfaz debe parecerse a la real: `invoices.fetch(since)`, `crm.upsert(contact)`. Cambiar el mock por el adaptador real se convierte en un cambio de configuración, no en una reescritura.
Claves de idempotencia para cualquier escritura. Cada llamada que muta datos debe aceptar una clave de idempotencia (un UUID o un hash determinista de las entradas). Los reintentos pasan a ser seguros por defecto.
Una tabla `events` o `runs`. Persiste cada acción significativa: entradas, salidas, tiempos, estado, quién la disparó. Loguear a stdout no es suficiente; el PoC necesita un historial consultable.
Un único módulo `config`. Todos los valores específicos de entorno (URLs, claves, feature flags) viven en un solo sitio, tipados y validados al arrancar. Nada de accesos a `process.env` repartidos por los archivos.
Un `.env.example` y un arranque con un solo comando. `make dev` o `docker compose up` deben levantar todo el stack en local. El traspaso empieza el primer día.
Ninguna de estas decisiones añade un tiempo significativo a un sprint de 2 semanas. Todas ahorran semanas en el siguiente sprint.
Por qué ayuda a los compradores
Los compradores suelen necesitar una prueba antes de que el acceso a la API esté del todo aprobado. Un sprint puede empezar con exportaciones, datos simulados o subidas manuales, y avanzar hacia la integración directa cuando el PoC se gane la confianza.
Una progresión realista de acceso a datos:
1. Semana 1. Subida manual de CSV o archivos de muestra anonimizados. La app se comporta como si recibiera los datos de una API, aunque la fuente sea una carpeta.
2. Semanas 2-3. Acceso de solo lectura a la API con una cuenta de servicio en un sandbox, o una exportación programada a S3/SFTP. Las escrituras siguen yendo a una tabla de staging que el cliente puede inspeccionar.
3. Semana 4+. Acceso a la API de producción con autenticación adecuada, límites de velocidad y auditoría. Escrituras protegidas por un feature flag y un interruptor de apagado por tenant.
Esa secuencia mantiene el impulso sin fingir que compras y la revisión de seguridad no existen. También separa las preguntas: "¿funciona el flujo de trabajo?" se responde en la primera semana; "¿podemos conectar con los sistemas reales?" es una vía paralela que avanza a su propio ritmo.
Qué evitar
El riesgo es una demo que funciona solo porque todo está hardcodeado. Eso puede ser útil para un concepto muy temprano, pero es una prueba débil para un sistema de negocio.
Antipatrones concretos que rechazar, incluso bajo presión de tiempo:
Escrituras directas a la base de datos desde el frontend. Una "comodidad de PoC" que se convierte en un incidente de seguridad en cuanto un usuario real toca la app.
Una única función que hace la ingesta, la transformación, las llamadas a la IA, la validación y la persistencia. Una vez existe esa función, cada cambio se vuelve arriesgado. Divídela el primer día.
Credenciales hardcodeadas en el repo, incluso en `.env.local`. Usa un gestor de secretos o archivos solo locales ignorados por git. El PoC acabará compartiéndose más de lo previsto.
Cero tests. Un PoC no necesita un 90% de cobertura, pero sí un smoke test para el camino feliz y otro para el modo de fallo más probable. Esa es la diferencia entre un traspaso y una reimplementación.
Autenticación solo para la demo. Una contraseña compartida o un interruptor de "saltar el login" valen para la demo de arranque y son peligrosos más allá de ella. Conecta Auth.js, Clerk o Cognito pronto.
Un sprint mejor construye justo la estructura suficiente para que el comprador vea cómo la app se conectaría a los sistemas reales más adelante. La estética no es "enterprise": es "pequeño, limpio y claramente extensible". Un PoC que parece el interior de una app de producción, solo que más pequeño, es el que consigue financiación para el siguiente sprint.