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.

El primer nodo: elige una forma en la barra izquierda y haz clic en el lienzo. Para conectar, pasa el ratón sobre un nodo y arrastra una de las flechas azules que aparecen en sus lados.

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. El marco de selección múltiple es lo único que se queda fuera del táctil: necesita el ratón.

En móvil el panel de propiedades es un cajón lateral que abre y cierra el botón ⚙ de la cabecera.

Un documento puede tener varias páginas, con pestañas en la barra inferior. Doble clic en una pestaña la renombra. 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 ofrece color de borde, relleno (automático, sólido o ninguno), estilo de línea, posición, color y fondo del texto, tamaño y negrita. 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. Hay una paleta semántica con nombres — Servicio, Eventos, Datos, Error — más una rejilla amplia y un selector personalizado. El botón Picker es un cuentagotas que toma cualquier color del lienzo (solo en navegadores con la API EyeDropper).

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 una de las flechas azules de sus lados. 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.

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. La dirección puede ser normal, inversa o alterna.
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, un toque avanza. 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

Formato	Para qué	Notas
GIF	README, presentaciones, redes	Bucle cíclico automático. FPS y duración configurables. Transparencia de bordes duros.
PNG	Imagen estática de calidad	Admite fondo transparente con bordes suaves.
JPG	Cuando el peso importa	Sin transparencia.
SVG	Seguir editando en otra herramienta	Vectorial. El fotograma es estático.

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

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.
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). 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 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.

El editor sigue sin backend; el servidor MCP es otra cosa. El editor de fluyo.space no envía tus diagramas a ninguna parte. El servidor MCP, en cambio, sí recibe el contenido del diagrama cuando lo usas como conector remoto — no puede editar lo que no ha recibido. Lo procesa en memoria y lo descarta sin guardarlo. Los dos flujos están explicados por separado en la política de privacidad.

Conectarlo

Hay dos transportes sobre el mismo núcleo. Las nueve 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 nueve 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.

Consulta siempre el README de fluyo-mcp como fuente de verdad: es el que se actualiza cuando cambian las rutas o el nombre del paquete.

Las nueve tools

Tool	Qué hace
`create_diagram`	Crea un diagrama completo a partir de una lista de nodos y aristas. Si no le das coordenadas, aplica un auto-layout por capas.
`edit_diagram`	Aplica una lista ordenada de operaciones sobre un documento existente: `add_node`, `update_node`, `remove_node`, `add_edge`, `update_edge`, `remove_edge`, `set_theme`, `rename_page` y `relayout`.
`export_diagram`	Exporta una página a SVG estático, con el mismo renderer que usa el editor.
`list_icons`	Devuelve las claves de icono válidas, para que el asistente no tenga que adivinarlas.
`list_colors`	Devuelve la paleta semántica con sus nombres (Servicio, Eventos / Kafka, Datos…).
`list_anims`	Devuelve las claves de los ocho GIFs animados, para nodos `shape="anim"`.
`list_fonts`	Devuelve las once familias tipográficas disponibles, con la familia CSS completa que espera el campo `font`.
`list_templates`	Lista los patrones de arquitectura predefinidos: Kafka, RAG y microservicios.
`create_from_template`	Instancia una de esas plantillas, sustituyendo las etiquetas por las tuyas.

Al referenciar nodos que ya existen en un documento hay que usar su id numérico. Las key que pasas en add_node son temporales: sirven para encadenar referencias dentro de la misma llamada y no se guardan en el .fluyo.json.

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 usar relayout 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.

Tus diagramas nunca 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: pageviews y un puñado de eventos de uso agregados (si se creó un diagrama, si se exportó y en qué formato, si se cargó un ejemplo, si se usó un GIF animado). Sin cookies, sin fingerprinting y sin identificar usuarios. El contenido de tus diagramas no se envía nunca, 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.