AuraReels: construir un sistema distribuido dirigiendo IA .

AuraReels es un SaaS de procesamiento de vídeo con IA pensado para creadores que producen reels y shorts en volumen. El usuario sube un vídeo, el sistema lo procesa de forma asíncrona y devuelve metadatos listos para publicar.

El reto técnico no era la "funcionalidad de IA" en abstracto, sino sostener un flujo distribuido real con varios servicios cooperando — escritos en su mayoría dirigiendo IA, sin que el resultado pareciera un Frankenstein.

Este registro no cuenta el "qué hace AuraReels" — eso lo cuenta el producto. Cuenta cómo se dirige IA para construir un sistema así: qué se firma, qué se delega, y por qué la arquitectura está pensada para que cualquier parte se pueda romper sin tirar abajo el resto.

La primera decisión técnica fue la más cara de revertir: cómo dividir el sistema. La regla no fue "qué tecnología elegimos", sino qué pasa cuando una parte se rompe.

Cada componente — la UI, la API central, los workflows de IA, los servicios auxiliares — tiene un ciclo de vida y un radio de explosión distinto. Algunos cambian varias veces al día; otros, cuando se modifica un esquema (semanas). Forzar un monolito habría diluido las fronteras de cambio y multiplicado los downtimes evitables.

Una buena división no une el código: separa los radios de explosión.

La ventaja es operativa: cuando algo falla, el incidente queda localizado. Y cuando hay que tocar una zona, el cambio no obliga a redeployar las demás.

Tres capas, comunicación bien tipada entre ellas:

Capa de presentación

UI tipada, contratos explícitos contra el backend, estados de tarea visibles al usuario en todo momento. Cuando algo tarda, el usuario sabe en qué paso está — y el equipo sabe qué reproducir si revienta.

Capa de servicios de negocio

API central que concentra la lógica transaccional, autenticación de usuarios y persistencia con identidad fuerte. Aquí viven los contratos que el resto del sistema consume — versionados, tipados y validados en los bordes.

Capa de orquestación e integración

Workflows asíncronos que orquestan llamadas a proveedores externos (CDN de vídeo, modelos multimodales, generación de imágenes), polling determinista de estados y servicios auxiliares con su propio dominio. Las claves de proveedores externos viven solo aquí — el navegador nunca las toca.

Lo importante no es la lista de tecnologías — es que cada componente se puede explicar en una frase y cada interfaz tiene un contrato claro. Esa es la condición para que la IA pueda escribir código dentro y no romper nada fuera.

El sistema se rige por reglas que firma el repo, no la persona del momento. Lo crítico:

• Validación en los bordes. Cada endpoint y cada respuesta de un proveedor externo entra por un parser tipado. Si la forma cambia, el sistema avisa antes de propagar el dato.
• Efectos secundarios aislados. Funciones puras para la lógica de transformación. Efectos secundarios empaquetados en envoltorios nombrados, inyectables en tests.
• Composición sobre herencia. Cada unidad — función, módulo, nodo de workflow — tiene una responsabilidad única. Las composiciones viven en piezas explícitas, no en clases que crecen sin freno.
• Logs estructurados. Identificador de tarea + paso + duración en JSON. Cualquier reproducción de bug parte de un grep — no de "abre la consola del navegador y dime qué ves".
• Validación de configuración en arranque. Cada servicio valida sus variables de entorno al arrancar y muere ruidosamente si falta una. El fallo silencioso de un servicio que arranca con un secret undefined es de los bugs más caros y menos justificables.

Estas reglas no son cosméticas: son la condición que permite que un cambio generado por IA pase por revisión sin que tenga que reinspeccionar todo el sistema cada vez.

Dirigir IA no es "usar Copilot mejor". Es operar un subordinado capaz pero sin contexto: rápido en ejecución, terrible en juicio de arquitectura. El reto fue que el sistema se escribiera en su mayoría por IA, sin que eso se notara al abrir el código.

La IA ejecuta, yo respondo.

Principios del método de supervisión

1. 01 —

   Plan antes que línea

   Ningún prompt sin arquitectura cerrada. Contratos de datos, modelo de seguridad y puntos de fallo quedan escritos antes de invocar la IA.

2. 02 —

   Fases acotadas de ejecución

   Cada fase entra en un build-phase-NN.md. La IA no toca dos capas a la vez. Si el alcance se ensancha, se corta y se abre fase nueva.

3. 03 —

   Revisión antes de continuar

   Estructura, inyección de dependencias, validación en los bordes, aislamiento de efectos secundarios, tests. Nada avanza con deuda — nunca se acumula.

4. 04 —

   Firma explícita

   Cada merge lleva mi firma. Si algo falla en producción, la responsabilidad no se diluye entre el modelo, el cliente y el hype.

5. 05 —

   Observabilidad desde el commit 1

   Logs estructurados, control de costes por llamada y plan B obligatorio. La IA ejecuta — pero ejecuta con instrumentos.

El flujo se apoya en un comando propio, /build-phase, que acota el alcance, escribe el plan y bloquea merges sin revisión humana:

  1# fase 07 · flujo asíncrono de transcodificación   2$ claude /build-phase --plan=07-transcode.md \   3 --scope=apps/worker/src/transcode \   4 --budget=200k-tokens \   5 --require=zod,tests,observability   6   7→ plan leído · 4 módulos · 12 tests requeridos   8→ fase acotada: no toca /auth, /billing, /api   9→ merge bloqueado hasta firma senior   10   11✓ arquitectura revisada   12✓ contratos firmados   13✓ tests verdes · 12/12   14✓ observabilidad: cost-per-video bajo presupuesto   15   16# respondo yo — deploy staging autorizado   17$ ./ship staging  

Cada fase vive en su propio archivo build-phase-NN.md versionado junto al código. Son artefactos auditables: el cliente — o mi yo futuro — puede reconstruir por qué se decidió un compromiso técnico, por qué un módulo aisló efectos secundarios, y quién firmó qué merge. El registro de decisiones no es un documento de marketing: es parte del repo.

Lo que volvería a hacer

• Orquestación visual para la parte volátil. La ingeniería de prompts y los enganches con APIs externas eran lo más cambiante del producto. Tenerlas en un workflow visual permitió iterar sin tocar la UI ni la API central.
• Polling determinista cuando los webhooks no son fiables. Más caro en peticiones, pero predecible — y una tarea que nunca llega a su estado final es peor que una que tarda unos segundos extra.
• Separar lectura pública de gestión. Aislar la superficie de visualización del flujo de gestión bajó la superficie de fallo y redujo el código que se redeploya por cada cambio.

Lo que no volvería a hacer igual

• Mezclar dos sistemas de estilos en el frontend. La próxima, uno solo desde el día uno.
• Modos de prueba inyectados vía query param. Práctico al principio, pero contamina la lógica de producción. Si lo rehago, lo aíslo en un middleware.

La métrica que importa no es ningún número aislado: es que después de meses en producción, cualquier cambio sigue cabiendo en una fase, sigue revisándose en un PR humano y sigue desplegándose sin sustos.

Si lo que has leído te resuena — porque tienes un flujo de IA atascado en piloto, porque tu equipo está dirigiendo IA sin método, o simplemente porque quieres una segunda opinión técnica sobre un sistema que ya tienes — reserva 30 minutos.

Te digo honestamente si encajo o si te conviene otro perfil. Cero venta.

→ Ir a contacto