Documentación

Todo lo que hace Fluyo, en una página que se lee entera.

Qué es Fluyo y qué problema resuelve

Fluyo es un editor de diagramas de arquitectura en el que las conexiones se mueven: puntos que recorren las flechas mostrando la dirección del flujo, nodos que laten y elementos que aparecen en secuencia. El resultado se exporta como GIF animado.

El problema concreto que resuelve: explicar un sistema distribuido con una imagen estática obliga a que quien la ve reconstruya mentalmente el orden de los pasos. Un diagrama animado lo muestra. Eso importa cuando el diagrama va a un README, a una presentación, a una propuesta de diseño o a un post — sitios donde no puedes estar delante para narrarlo.

Las herramientas que animan de verdad son de pago, viven en la nube y te piden una cuenta. Fluyo es open source con licencia MIT, no tiene backend y no guarda nada: el editor, la animación y hasta la codificación del GIF ocurren en tu navegador.

Cómo empezar

Abres fluyo.space y ya estás dentro. No hay registro, ni email, ni onboarding, ni límite de uso.

Si prefieres no depender de nadie: clona el repositorio y sírvelo tú. Es HTML, CSS y JavaScript sin dependencias ni paso de compilación.

git clone https://github.com/itsnect/fluyo.git
cd fluyo
python -m http.server 8000

Y abre http://localhost:8000. Cualquier servidor de archivos estáticos sirve.

Referencia de features

Lienzo y navegación

El lienzo es infinito. Se mueve con la rueda del ratón, con clic derecho, clic central o Alt+arrastrar, y se hace zoom con Ctrl+rueda.

En pantalla táctil: un dedo sobre el vacío desplaza el plano, un dedo sobre un nodo lo arrastra y dos dedos hacen zoom. Doble toque edita el texto. Con algo seleccionado aparece una barra con Conectar (toca después el elemento de destino: la conexión sale del que tenías seleccionado) y Seleccionar varios (cada toque suma o quita; Todo y Listo), además de la papelera para borrar.

En móvil, las propiedades y las Historias se abren en una hoja sobre la parte baja del lienzo: el botón de ajustes de la cabecera abre las propiedades, Historias (en la barra inferior, junto a Presentar) abre las Historias, y la propia hoja tiene un botón para cerrarla. Deshacer y Rehacer están siempre en la cabecera; los ajustes del lienzo y las acciones de archivo, en el menú ⋯.

La hoja de Historias en móvil tiene cuatro estados: compacta (la Historia, Reproducir y «Volver a editar» sobre el lienzo), ampliada (los eventos como fichas y la línea de tiempo; el lienzo sigue a la vista, se desplaza y, al tocar un paso, enseña su destino), reproduciendo (el mando de la reproducción, con el lienzo despejado) y cerrada. Mientras se reproduce, el momento en curso se lee sobre el lienzo y el mando ofrece Pausar/Reanudar, el momento anterior y el siguiente, y Detener (vuelve a la Historia lista; al terminar, Repetir). Tocar un paso de la línea de tiempo salta a su momento. Es el mismo mando en el editor, en Presentar y en el enlace compartido. En el teléfono las páginas se eligen con un selector (con «＋ Nueva página» dentro); en escritorio, renombrar y eliminar una página están en el menú ▾ de la pestaña activa. La animación ambiental del lienzo y la ayuda de atajos y gestos están, en móvil, en el menú ⋯.

Con el teléfono en horizontal, el lienzo ocupa casi toda la pantalla: la barra superior lleva el selector de página, Historias y Presentar, y no hay barra inferior. Las propiedades y las Historias se abren como una hoja a la derecha; al reproducir, el mando se recoge en una franja de una fila al pie. Si giras el teléfono con el diagrama entero a la vista, se vuelve a encajar.

Al crear un evento (nombre, dónde ocurre, cómo lo cuentas y su símbolo; su aspecto, en «Cómo se ve»), Fluyo entra directamente a colocarlo: toca la conexión o el elemento donde ocurre. Con el dedo puedes desplazar el lienzo mientras tanto para llegar al destino; tocar el vacío no cancela. «Cancelar» o Esc lo dejan en la biblioteca para colocarlo después.

Cada paso puede decir su propio mensaje, también el de una conexión: en el menú del paso, «Mensaje del paso…» escribe la frase que cuenta qué ocurre en ese paso (hasta 120 caracteres), sin crear un evento para cada frase. Al reproducir, en el editor, al presentar y en el enlace compartido, el momento se lee con esa frase en lugar del nombre del evento; en un paso de un elemento, también es el texto de su globo. No toca el evento, sus otros usos ni los tiempos. «Quitar mensaje» vuelve al del evento.

Un documento puede tener varias páginas, con pestañas en la barra inferior. Doble clic en una pestaña la renombra; con el dedo, toca la pestaña activa (o su ▾) para renombrarla o eliminarla. Ejemplo abre un diagrama de muestra en una página nueva, sin tocar las tuyas. Cada página se exporta por separado.

Movimiento libre y rejilla

Por defecto los nodos se mueven libremente, píxel a píxel. Si prefieres alineación automática, activa Ajustar a rejilla en la barra superior. La cuadrícula visible se enciende y apaga aparte, con Cuadrícula.

Formas y contenido

• Formas — caja, cilindro (base de datos), rombo (decisión), círculo, hexágono, texto suelto y bloque de código.
• Bloque de código — un panel monoespaciado con las palabras clave resaltadas. Trae un preset de SQL/ksqlDB; se puede desactivar el resaltado o dar una lista propia de palabras. Son configurables el fondo del panel, el del bloque, el color del texto y los dos colores del resaltado.
• Iconos cloud — más de 40: GCP, AWS y Azure, más Kafka, Kubernetes, Docker, colas, cachés, balanceadores y estados.
• Imágenes — pega con Ctrl+V o arrastra un archivo al lienzo. Se incrustan en el documento como data URI, así que el .fluyo.json sigue siendo autocontenido.

Estilos

Con algo seleccionado, el panel derecho habla solo de esa selección. Arriba, su nombre, su tipo e id, el orden de capas y la papelera. En un nodo, Apariencia (forma, borde, relleno automático, sólido o ninguno, y línea del borde) y Texto (tipografía, tamaño, negrita, color, posición y fondo); un bloque de código suma el grupo Código y los ajustes raros van en Movimiento (pulso y orden de aparición). En una conexión, Trazo (color, línea, ruta y lados) y Dirección (puntas y sentido de los puntos). El color del texto es independiente del color del borde: en automático, un texto suelto hereda el color del nodo y el texto dentro de una forma usa el del tema. Cada color es una fila con la paleta semántica con nombres — Servicio, Eventos, Datos, Error… — y «⋯» abre la rejilla amplia, el color personalizado y el cuentagotas, que toma cualquier color del lienzo (solo en navegadores con la API EyeDropper). En escritorio el panel se puede plegar con su botón o con ⚙; la animación del lienzo está en Lienzo y los atajos en Más › Ayuda y gestos.

Capas

El orden de dibujado se controla con Al frente, Al fondo, Subir y Bajar. No hay que confundirlo con Orden de aparición, que es un número distinto: controla la secuencia de la animación de entrada, no qué tapa a qué.

Conexiones

Pasa el ratón sobre un nodo y arrastra el punto que aparece en el lado más cercano; con el dedo, selecciona el nodo, pulsa «Conectar» y toca el destino. La flecha queda anclada a ese lado, así que se mantiene coherente cuando muevas los nodos. Se puede elegir ruta recta u ortogonal, fijar por qué lado sale y entra, y poner o quitar punta en cada extremo.

Con una flecha seleccionada aparecen puntos huecos: arrástralos para doblarla; doble clic en un codo lo elimina.

Una conexión puede declarar qué significa. Un Flujo se dibuja con dos pequeñas cuñas en el centro de su tramo más largo, en el sentido de origen a destino, aunque la punta visible apunte al revés. Un Requisito se dibuja con un anillo cerca del origen. Las marcas no cambian durante una Historia y salen también al exportar. Una conexión sin tipo es una conexión de siempre. El tipo se elige en Propiedades, en Semántica, dentro del grupo «Puntos».

Si la página tiene algún Flujo, bajo los controles de una Historia aparece la ruta observada: un origen y un destino (en Automática los elige Fluyo cuando los Flujos de la página empiezan en un solo nodo y terminan en uno solo) y si se puede ir de uno a otro siguiendo Flujos por nodos disponibles. Al reproducir, el lienzo marca la ruta y una línea dice «Ruta disponible» o «Ruta no disponible», también al presentar y en los enlaces compartidos.

La ruta cambia en el instante en que un nodo cambia de estado. Un envío, en cambio, se decide al salir: si sale con su destino disponible, se completa aunque la ruta deje de estarlo mientras viaja. Si quieres que el cambio se vea cuando el envío llega, abre el menú del evento que cambia el estado y usa «Esperar a que llegue…».

Animación y GIF

Esto es el diferenciador del producto:

• Flujo de puntos — puntos que recorren cada flecha. Velocidad y cantidad globales, con multiplicador y número propios por flecha. El sentido de los puntos está en el grupo Dirección de la conexión, junto a las puntas: Hacia el destino, Hacia el origen o Ida y vuelta.
• Una pelota por ruta — en vez de puntos sueltos en cada flecha, las flechas se encadenan y una única pelota recorre el camino entero: nace en el primer nodo, pasa al segundo y termina en el último. Al llegar a un nodo que se abre en varias ramas, la pelota se parte y sigue por todas a la vez, sincronizadas: hasta la bifurcación se ve una sola. Las ramas más cortas terminan antes y se apagan al llegar a su destino.
• Pulso — un nodo late para llamar la atención.
• Aparición secuencial — los elementos entran uno a uno siguiendo su orden. Las flechas aparecen cuando ya están sus dos nodos.
• GIFs predefinidos — ocho animaciones dibujadas fotograma a fotograma (cargando, progreso, error, éxito, escribiendo, subiendo, latido, ticket) que se colocan como cualquier nodo y se animan también en el GIF exportado.

Al exportar a GIF, el bucle de flujo se ajusta solo para que el resultado sea perfectamente cíclico y no dé un salto al reiniciar.

Modo presentación

El botón Presentar (o la tecla P) esconde toda la interfaz, pone el diagrama a pantalla completa y lo encaja en la pantalla. Cada página pasa a ser una diapositiva.

Se avanza con →, Espacio o AvPág, se retrocede con ← y se sale con Esc; en táctil, con los botones del mando (un toque en el lienzo no hace nada: así un roce no corta una Historia). Si la página tiene una Historia, Espacio la reproduce y, mientras se reproduce, la pausa y la reanuda. Si la animación de aparición está activa, se reinicia en cada diapositiva. Al salir se recupera la vista exacta —posición y zoom— que había antes de presentar.

Tipografías

Once familias, todas de sistema — no se descarga ninguna fuente. Se puede fijar una global para el diagrama entero y sobrescribirla en elementos concretos.

Exportación

La escala va de 0,5× a 2×. El recorte se calcula sobre el contenido real, no sobre el lienzo completo.

Los cuatro formatos llevan las marcas de Flujo y Requisito de las conexiones. Nunca llevan lo que se ve solo al reproducir una Historia.

Autoguardado

La sesión se guarda sola en el localStorage de tu navegador. Al volver, Fluyo pregunta si quieres restaurarla. Es un archivo local en tu equipo: no se sube a ninguna parte.

El formato .fluyo.json

Guardar (Ctrl+S) descarga un .fluyo.json. Es JSON legible y versionable en git, sin nada binario salvo las imágenes que hayas pegado.

{
  "version": 3,
  "app": "fluyo",
  "doc": {
    "theme": "dark",
    "customBg": "",
    "cur": 0,
    "pages": [
      {
        "name": "Página 1",
        "nextId": 5,
        "nodes": [
          {
            "id": 1, "shape": "rect", "x": 480, "y": 620,
            "w": 180, "h": 70, "label": "API Gateway",
            "color": "#6a9fb5", "fill": null, "border": "solid",
            "lblPos": "center", "pulse": false, "order": 0
          }
        ],
        "edges": [
          {
            "id": 3, "from": 1, "to": 2,
            "fromSide": "e", "toSide": "w", "route": "ortho",
            "waypoints": [], "label": "eventos",
            "animated": true, "dashed": false,
            "startArrow": false, "endArrow": true, "flowDir": "normal"
          }
        ]
      }
    ]
  },
  "settings": { "speed": 0.5, "dots": 3, "build": false, "stagger": 0.45 }
}

Lo esencial:

• doc.pages es un array: un documento son varias páginas independientes.
• Los id son únicos por página y nextId es el siguiente a repartir. Nodos y flechas comparten el mismo contador.
• Las flechas referencian nodos por from y to. Si apuntan a un id inexistente, simplemente no se dibujan.
• Una flecha puede llevar kind: "FLOWS_TO" (Flujo) o "REQUIRES" (Requisito). Sin kind es una conexión de siempre. Un valor que tu versión de Fluyo no conoce se conserva al guardar y se lee como conexión.
• Cada Historia puede guardar su ruta observada en observedFlow: {"from": 1, "to": 6}, dos ids de nodo de la misma página. Si un extremo ya no existe, la Historia se reproduce igual y no se muestra ninguna ruta.
• Cualquier paso (SEND, OCCURRENCE o SET_STATE) puede llevar message: su frase, de 1 a 120 caracteres y no solo espacios. Al reproducir es el título de su momento en lugar del nombre del evento; en un paso de un elemento, también el texto de su globo en lugar del mensaje de su evento. No cambia tiempos ni resultados. Una versión de Fluyo que no conoce la clave (o, en un envío, anterior a esta) no abre el documento.
• x e y son el centro del nodo, no su esquina.
• shape puede ser rect, cylinder, diamond, circle, hex, text, icon, image, anim o code. icon, image y anim usan además icon, img o anim como clave.
• En shape:"code" el label es el código, con entre líneas. Cuatro campos propios: lang ("sql" o "none"), keywords (lista propia que sustituye al preset), kwBg y kwColor (los dos colores del resaltado; sin kwBg, la palabra clave se distingue por color y peso, sin caja). Reutiliza los campos de siempre para el resto: fill pinta el panel, textBg el fondo del bloque, textColor el código y font la tipografía, que por defecto es IBM Plex Mono.
• Al abrir un archivo antiguo, los campos que falten se rellenan con valores por defecto: no hace falta escribir todas las claves a mano.

Los diagramas de ejemplo son archivos .fluyo.json reales, así que sirven de referencia viva del formato.

Servidor MCP

fluyo-mcp es un servidor Model Context Protocol que permite a un asistente de IA crear y editar diagramas de Fluyo por ti: describes la arquitectura en lenguaje natural y recibes un .fluyo.json que abres en el editor.

Es una capa delgada sobre el mismo modelo de documento que usa el editor, con la paleta, los iconos y el exportador SVG portados uno a uno. Un diagrama generado desde el MCP se abre con el botón Abrir de Fluyo sin conversión de por medio.

Conectarlo

Hay dos transportes sobre el mismo núcleo. Las quince tools, sus schemas y el renderer son idénticos en ambos; lo único que cambia es por dónde entran los mensajes.

Como conector remoto

Lo más rápido: no hay nada que instalar. Pega esta URL donde tu cliente MCP pida un servidor remoto.

https://mcp.fluyo.space/mcp

Sin autenticación y sin cuenta: no hay que registrarse, ni pedir una clave, ni autorizar nada por OAuth. Pegas la URL y ya está.

En Claude, la ruta es Settings → Connectors → Add custom connector: pon Fluyo como nombre y esa URL como endpoint. Las quince tools aparecen en la conversación en cuanto se conecta.

En ChatGPT el conector está en proceso de revisión. Hasta que se apruebe, la vía que funciona ahí es el proceso local por stdio, que se explica justo debajo.

El endpoint remoto tiene topes que la versión local no tiene: 1 MB por petición, 200 KB por respuesta de herramienta y 30 peticiones por minuto y por IP. Un diagrama con imágenes incrustadas puede pasarse de los dos primeros.

Como proceso local

Sin red de por medio y sin ningún tope. El servidor sí tiene paso de compilación — la restricción de «cero build» es del editor, no de esta herramienta:

git clone https://github.com/itsnect/fluyo-mcp.git
cd fluyo-mcp
npm install
npm run build

Después añade el servidor a tu configuración MCP, apuntando a la ruta absoluta del dist/index.js que acabas de generar:

{
  "mcpServers": {
    "fluyo": {
      "command": "node",
      "args": ["/ruta/absoluta/a/fluyo-mcp/dist/index.js"]
    }
  }
}

Si lo instalas como ejecutable global (con npm link, o desde npm cuando esté publicado), la configuración se reduce a "command": "fluyo-mcp" sin argumentos.

Las quince tools

Para modificar un documento, describe_document da su revision y los id de cada elemento; author_document los usa y, dentro de un lote, permite nombrar con ref lo que acaba de crear. Las key de create_diagram y las ref son temporales: no se guardan en el .fluyo.json. edit_diagram, la tool de edición anterior, se retiró: la sustituye author_document.

Qué no puede hacer todavía

• Solo exporta SVG. Nada de PNG ni GIF: eso requeriría un renderer en Node. Para el GIF animado, abre el documento en el editor y expórtalo desde ahí.
• El SVG no lleva animación — ni flujo de puntos ni aparición progresiva. Es la misma limitación que el export SVG nativo del editor, no un problema del MCP.
• No puede crear nodos de tipo image, porque dependen de archivos binarios importados a mano. Sí puede editarlos si ya existen en el documento.
• El auto-layout es por capas (Sugiyama simplificado). Va muy bien con pipelines y arquitecturas convencionales; para grafos densos conviene dar coordenadas a mano o partir de lo que propone propose_layout y ajustar después.

Privacidad y telemetría

Este resumen cubre el editor. El servidor MCP remoto tiene un comportamiento distinto y se explica aparte en la política de privacidad, que es la fuente de verdad para ambos.

Usando el editor, tus diagramas no salen de tu navegador. No hay backend al que puedan ir: Fluyo es un sitio de archivos estáticos. El dibujado, la animación y la codificación del GIF ocurren en tu equipo, y lo que se guarda con el autoguardado va al localStorage de tu navegador, no a un servidor.

En el sitio público fluyo.space hay telemetría de producto: una lista cerrada de eventos de uso, sin pageviews. Sin cookies y sin identificarte por tu nombre o tu cuenta, aunque Umami deriva de cada petición un identificador de sesión y una ubicación aproximada. Los eventos y lo que obtiene el proveedor están en la política de privacidad. La telemetría no envía el contenido de tus diagramas, ni entero ni en fragmentos: los eventos solo llevan valores de una lista cerrada, como png o gif.

El script de telemetría se carga únicamente cuando el dominio es el oficial. Si clonas el repositorio, lo abres en local o lo self-hosteas, no se ejecuta ninguna telemetría y no se hace ninguna llamada de red — no es que se filtren los datos, es que ese código no llega a correr. Los dominios de preview también quedan fuera a propósito.

Si quieres cero telemetría, usa el proyecto en local o self-hosteado. La condición está en js/analytics.js, en un solo bloque, para que puedas comprobarlo tú mismo en un minuto.

La única petición externa del editor es gif.js desde un CDN, la librería que codifica el GIF. Se precachea en la primera visita para que funcione sin conexión.

Cómo contribuir

Fluyo es MIT y las contribuciones son bienvenidas. No hay paso de compilación ni dependencias: clonas, abres y editas.

• Empieza por CONTRIBUTING.md: explica la estructura de archivos y trae guías paso a paso para las dos contribuciones más habituales, añadir un icono y añadir una animación.
• Para arreglos pequeños, manda el Pull Request directamente.
• Para cambios grandes o features nuevas, abre antes un issue: es más rápido acordar el enfoque que rehacer el trabajo.
• ¿Una idea que no vas a implementar ahora? Va a ideas.md.