BuilderLab comenzó con una observación sencilla: la forma actual de aprender no refleja la dinámica real una vez que alguien es contratado. Los proyectos individuales o los tutoriales rara vez reproducen las condiciones de una entrega en equipo. BuilderLab es, por lo tanto, un intento de reducir la distancia entre las etapas de aprendizaje y de trabajo.
BuilderLab trata esta experiencia de equipo ausente como un problema de producto, no como otro ejercicio aislado. Permite que quienes aprenden propongan proyectos, encuentren colaboradores, coordinen el trabajo, mantengan un Build Log y hagan visible una parte suficiente del proceso para que otra persona entienda cómo se llegó al resultado, no solamente cómo se ve la interfaz final.
01La brecha de colaboración es un problema de ingeniería comprobable
Los estudiantes pueden practicar por su cuenta SQL, Git, Linux, el despliegue cloud o un lenguaje de programación. Las partes difíciles de la ingeniería profesional suelen estar en otro lugar: negociar el alcance, repartir responsabilidades, manejar desacuerdos, documentar decisiones, recuperarse de bloqueos y mantener un sistema compartido después de su primera entrega.
Conocer una herramienta no equivale a trabajar en equipo
Un tutorial individual puede enseñar sintaxis y API. No puede reproducir por completo la responsabilidad sobre un componente, los relevos, el control de acceso ni las consecuencias del cambio de otra persona.
La captura final oculta la mayor parte del trabajo
Una página de proyecto puede conservar hitos, actualizaciones, bloqueos, decisiones, participantes y retroalimentación para que el camino hacia el resultado siga siendo verificable.
Una vez que trabajamos como ingenieros, colaboramos con otras personas todos los días. BuilderLab convierte ese hecho cotidiano en la restricción que organiza el producto.
Identificar un problema recurrente de aprendizaje o colaboración.
Traducir el problema en roles, estados y transiciones.
Construir el flujo coherente más pequeño y exponerlo a un uso real.
Registrar fallas, reforzar límites y definir el siguiente experimento.
02Tres capas de producto acompañan un proyecto desde la idea hasta la evaluación
El producto se divide en tres capas conectadas. Uso esta separación para mantener visibles problemas distintos, en lugar de ocultarlos detrás de una idea amplia de “colaboración”.
Perfiles, ideas de proyectos, descubrimiento, solicitudes de ingreso, pertenencia al equipo, seguimiento y páginas públicas de proyecto.
En líneaTareas, hitos, chat del equipo y actualizaciones del Build Log dentro del espacio de trabajo del proyecto.
En línea / en evoluciónYa existe un índice de proyectos terminados; las evaluaciones estructuradas entre pares y su método de puntuación siguen planeados.
Parcialmente en línea / planeadoEl ciclo de vida previsto va más allá de conectar personas con proyectos. Una solicitud puede convertirse en pertenencia al equipo; esa pertenencia abre un espacio de trabajo; ciertas transiciones de tareas pueden crear entradas públicas en el Build Log; completar el proyecto puede dar lugar a evaluaciones entre colaboradores; y un proyecto terminado puede seguir disponible como evidencia. Cada paso requiere una transición de estado explícita, no solamente una pantalla nueva.
03La aplicación separa el descubrimiento público del trabajo autenticado
El repositorio actual utiliza App Router de Next.js con TypeScript. Los grupos de rutas separan la superficie pública del espacio de trabajo de la aplicación sin cambiar las URL públicas. Los Server Components obtienen los datos iniciales de la página; los Client Components manejan formularios, filtros, ventanas modales, chat, cambios de tareas y actualizaciones optimistas de la interfaz.
El flujo típico de una página comienza con un Server Component que lee filas y el contexto de identidad antes de entregar el resultado a un Client Component para la interacción. Esto se observa en el feed y en los flujos de detalle del proyecto.
obtener proyectos + usuario actual
búsqueda, filtros, contexto de responsabilidad
solicitudes de ingreso y acciones de seguimiento
04El modelo de datos sigue la vida social y técnica de un proyecto
La decisión de modelado más importante fue evitar tratar un proyecto como solamente un título y una descripción. BuilderLab representa la identidad, el descubrimiento, la formación del equipo, la ejecución, la finalización y la retroalimentación como aspectos relacionados, pero distintos.
Una conexión es una solicitud, no una membresía. Un follower puede consultar secciones restringidas del proyecto, pero no actuar como miembro. Un miembro puede salir sin desaparecer del registro histórico. Una tarea puede asignarse, bloquearse o vincularse con un hito. Una actualización pública es distinta de un mensaje del equipo. Estas diferencias vuelven visible la idea del producto dentro del esquema y dan a las políticas de acceso reglas concretas que aplicar.
pending a accepted, un trigger de PostgreSQL inserta al remitente en project_members. La transición es atómica y no depende de que el cliente complete correctamente una segunda solicitud.05Los límites de confianza deben resistir una llamada directa a la API
Autenticación no es lo mismo que autorización. Ocultar un botón puede orientar a una persona, pero no protege una base de datos. En los flujos siguientes, la interfaz y Row Level Security de PostgreSQL comparten la responsabilidad: la interfaz presenta las acciones válidas, mientras que las políticas de la base rechazan operaciones fuera del rol del usuario autenticado.
Q1¿Quién puede modificar una tarea?
El propietario del proyecto puede crear, modificar o eliminar cualquier tarea. Puede delegar el rol HiveOS Manager a un solo miembro activo a la vez, otorgándole los mismos derechos de gestión de tareas. Un miembro regular puede actualizar el estado de una tarea que tiene asignada. La política comprueba a nivel de base de datos las identidades del propietario, del manager y de la persona asignada.
Limitación actual: la base controla quién puede actualizar una tarea asignada, pero el conjunto detallado de transiciones de estado permitidas todavía depende en gran medida de la interfaz. Una política de transición más estricta reduciría esa confianza restante en el comportamiento del cliente.
Q2¿Cómo se convierte una solicitud aceptada en pertenencia al equipo?
Una solicitud comienza como una fila en connectionsDespués de que el propietario la acepta, un trigger de PostgreSQL crea la fila activa en project_members con protección contra conflictos. Esto mantiene coherentes la aceptación y la pertenencia, incluso si quien llama evita la interfaz.
Q3¿Qué ocurre cuando un miembro sale?
Tanto la salida voluntaria como la eliminación por parte del propietario requieren una razón de 10 a 300 caracteres. La fila de pertenencia cambia a left en lugar de eliminarse, se retira el requisito de evaluación, se elimina el acceso a funciones exclusivas del equipo y las tareas que seguían asignadas quedan sin responsable. La razón no se muestra al resto del equipo.
La especificación actual también expone un caso de limpieza: si la persona que sale era HiveOS Manager, el indicador de manager puede permanecer almacenado aunque ya no tenga acceso. Automatizar esa limpieza es un siguiente cambio razonable en la base de datos.
Q4¿Qué secciones del proyecto son públicas?
Milestones, Build Log, Team Chat y Team members tienen cada uno un control independiente manejado por el propietario y son públicos de forma predeterminada. Cuando se restringen, siguen visibles para el propietario, los miembros activos y los followers. Los followers forman así un nivel intermedio de confianza: pueden consultar más contexto, pero no publicar actualizaciones, usar el chat ni utilizar HiveOS.
Esto significa que, por ahora, “privado” quiere decir restringido a una audiencia definida del proyecto, no visible solamente para el equipo activo. El lenguaje y la interfaz deben mantener clara esa diferencia.
Q5¿Cómo se envían notificaciones sin exponer direcciones de correo?
Las notificaciones por correo y dentro de la aplicación se crean mediante manejadores de rutas del lado del servidor que utilizan la clave service-role de Supabase, la cual nunca se envía al navegador. La ruta lee en el servidor el correo del destinatario, envía el mensaje mediante Resend y crea una notificación dentro de la aplicación. Gracias a RLS, las filas de notificaciones solo pueden ser leídas por su destinatario.
Mantener la clave del lado del servidor es necesario, pero no suficiente. Estas rutas todavía deben incorporar verificación explícita de quien llama y del estado del flujo, validación de entradas, límites de frecuencia y registro operativo.
Q6¿Cómo se mantiene alineada la documentación con la base de datos?
Por ahora, la alineación depende de la disciplina, no de una prueba automatizada. Aplico cada migración a un proyecto de desarrollo en Supabase, actualizo de inmediato la documentación de la base, registro el cambio de producto en el changelog y hago commit conjunto de la migración, la documentación y el código de la aplicación.
Este es el límite más débil del proceso actual porque nada demuestra automáticamente que la documentación coincida con el esquema en servicio. La introspección del esquema y un diff de documentación son siguientes experimentos naturales.
06Un producto en línea convierte las lecciones en cambios de método
La base de código ha crecido mientras aprendo. Eso se observa en funciones útiles, pero también en archivos que se han vuelto demasiado grandes, un historial de migraciones que todavía no ofrece una ruta reproducible completa, polling cada cinco segundos en el chat del equipo y un quickstart anterior que menciona archivos de configuración SQL ausentes del archivo entregado.
Las pruebas son el ejemplo más claro de un cambio de método. No comencé BuilderLab con una estrategia de pruebas automatizadas. Fue una omisión. Durante una clase de MLOps, el consejo de introducir pruebas desde el principio, en vez de agregarlas cuando el sistema ya es difícil de cambiar, dejó más claro el costo de esa decisión. Desde entonces escribí una estrategia de pruebas en la rama de desarrollo. Es un comienzo, todavía no una suite automatizada completa ni un control de integración continua.
Estoy adoptando un enfoque similar con la infraestructura. Podría corregir de inmediato el antiguo quickstart SQL, pero la dirección prevista es un entorno declarativo construido con Terraform. Prefiero establecer ese proceso después de cubrir los conceptos relevantes y reemplazar una sola vez la ruta de configuración obsoleta, en lugar de actualizar instrucciones que ya espero sustituir.
07Lo que demuestra la beta y lo que probaría después
Evidencia actual
- Las rutas públicas y autenticadas están separadas sin cambiar la estructura externa de las URL.
- Los clientes de Supabase para servidor, navegador y service-role representan límites de confianza distintos.
- El modelo de dominio distingue solicitudes, followers, miembros, propietarios, managers, tareas, hitos, actualizaciones, chat y evaluaciones.
- HiveOS convierte ciertos eventos de tareas en evidencia dentro del Build Log sin publicar cada acción interna.
- Los triggers de la base protegen transiciones importantes, como la creación de perfiles y la incorporación al equipo después de aceptar una solicitud.
- El producto está desplegado como beta en línea con documentación pública y código fuente.
Restricciones conocidas
- El historial de migraciones debe convertirse en la fuente de verdad reproducible del esquema actual.
- Varios componentes interactivos necesitan dividirse antes de volverse más difíciles de probar y mantener.
- El polling del chat del equipo debe reemplazarse o hacerse incremental a medida que crece el uso.
- La estrategia de pruebas debe convertirse en pruebas ejecutables y un control automatizado.
- El quickstart debe reemplazarse por una ruta de aprovisionamiento declarativa, en lugar de corregirse indefinidamente.
- La alineación entre documentación y esquema todavía necesita una comprobación automatizada.
Ejercitar llamadas API del propietario, manager, persona asignada, follower y actores no autorizados frente a las políticas RLS.
Verificar solicitudes aceptadas, salidas, desasignación de tareas y limpieza del rol de manager como transiciones de estado a nivel de base de datos.
Comprobar la identidad de quien llama, el estado esperado del flujo, el aislamiento del destinatario y el comportamiento ante fallas antes de enviar correo.
Introspeccionar el esquema de desarrollo y compararlo con las migraciones y la documentación generada.
Usar Terraform para hacer reproducible la configuración de desarrollo y retirar el quickstart SQL obsoleto.
Comparar Realtime o polling incremental con el enfoque actual de cinco segundos bajo actividad realista.
Ninguno de estos pasos es valioso solamente porque use otra herramienta. Cada uno debe responder una pregunta concreta: ¿la política rechaza al actor equivocado?, ¿puede reproducirse el entorno?, ¿la documentación detecta deriva?, ¿un nuevo mecanismo de mensajería reduce lecturas sin debilitar la entrega?
08Evidencia abierta
BuilderLab sigue siendo una beta en línea. Los enlaces siguientes exponen el producto, su documentación para usuarios y el repositorio de código para que las afirmaciones de este artículo puedan verificarse, no solamente aceptarse por su descripción.